API Reference

Trait Definition #[async_trait] pub trait EmbeddingService: Send + Sync { async fn embed(&self, inputs: &[String]) -> Result<Vec<Vec<f32>>>; async fn embed_single(&self, input: &str) -> Result<Vec<f32>>; async fn health_check(&self) -> Result<()>; } Module: magicaf_core::embeddings Methods embed async fn embed(&self, inputs: &[String]) -> Result<Vec<Vec<f32>>> Embed a batch of input strings, returning one vector per input. Parameter Type Description inputs &[String] Texts to embed. Empty slice returns empty vec. Returns: Vec<Vec<f32>> — one embedding vector per input, in the same order. Errors: MagicError::EmbeddingError, MagicError::HttpError ...

Trait Definition #[async_trait] pub trait VectorStore: Send + Sync { async fn index( &self, collection: &str, embeddings: Vec<Vec<f32>>, payloads: Vec<serde_json::Value>, ) -> Result<()>; async fn search( &self, collection: &str, query_vector: Vec<f32>, limit: usize, filter: Option<serde_json::Value>, ) -> Result<Vec<SearchResult>>; async fn delete_by_entity( &self, collection: &str, entity_id: Uuid, ) -> Result<()>; async fn ensure_collection( &self, collection: &str, vector_size: usize, ) -> Result<()>; } Module: magicaf_core::vector_store Methods index async fn index( &self, collection: &str, embeddings: Vec<Vec<f32>>, payloads: Vec<serde_json::Value>, ) -> Result<()> Index a batch of embeddings with their associated JSON payloads. ...

Trait Definition #[async_trait] pub trait LlmService: Send + Sync { async fn chat(&self, request: ChatRequest) -> Result<ChatResponse>; async fn generate(&self, prompt: &str, config: GenerationConfig) -> Result<String>; async fn health_check(&self) -> Result<()>; } Module: magicaf_core::llm Methods chat async fn chat(&self, request: ChatRequest) -> Result<ChatResponse> Send a structured chat completion request. Parameter Type Description request ChatRequest The chat completion request payload Returns: ChatResponse containing the model’s reply, usage statistics, and metadata. Errors: MagicError::LlmError, MagicError::HttpError, MagicError::SerializationError generate async fn generate(&self, prompt: &str, config: GenerationConfig) -> Result<String> High-level convenience: turn a raw prompt into generated text. ...

Overview RAGWorkflow is the central pipeline engine. It is fully generic over all service and adapter traits, with zero runtime overhead — all dispatch is static. Module: magicaf_core::rag Type Signature pub struct RAGWorkflow<S, V, L, EF, PB, RP, T> where S: EmbeddingService, V: VectorStore, L: LlmService, EF: EvidenceFormatter, PB: PromptBuilder, RP: ResultParser<T>, T: Send, In practice, you never write out the type parameters — Rust infers them from the builder. ...

Adapter traits are the extension seam where your domain logic plugs into the RAG pipeline. MagicAF ships default implementations for rapid prototyping. Module: magicaf_core::adapters EvidenceFormatter #[async_trait] pub trait EvidenceFormatter: Send + Sync { async fn format_evidence(&self, results: &[SearchResult]) -> Result<String>; } Converts raw vector search results into a text block for the LLM prompt. Parameter Type Description results &[SearchResult] Search results from the vector store Returns: A formatted string ready for inclusion in the prompt. ...

All configuration structs derive Serialize and Deserialize, so they can be loaded from JSON, TOML, YAML files, or environment variables. Module: magicaf_core::config EmbeddingConfig Configuration for the embedding service endpoint. pub struct EmbeddingConfig { pub base_url: String, pub model_name: String, pub batch_size: usize, pub timeout_secs: u64, pub api_key: Option<String>, } Field Type Default Description base_url String — Base URL of the embedding server (e.g., http://localhost:8080) model_name String — Model identifier sent in the request batch_size usize 32 Maximum texts per batch request timeout_secs u64 30 HTTP request timeout in seconds api_key Option<String> None Optional bearer token for authenticated endpoints Example let config = EmbeddingConfig { base_url: "http://localhost:8080".into(), model_name: "bge-large-en-v1.5".into(), batch_size: 32, timeout_secs: 30, api_key: None, }; From JSON { "base_url": "http://localhost:8080", "model_name": "bge-large-en-v1.5", "batch_size": 64, "timeout_secs": 15 } VectorStoreConfig Configuration for the vector database backend. ...

All MagicAF operations return Result<T, MagicError>. The error type is designed for both Rust-native ? propagation and FFI-friendly numeric codes. Module: magicaf_core::errors MagicError pub enum MagicError { EmbeddingError { message: String, source: Option<Box<dyn Error + Send + Sync>> }, VectorStoreError { message: String, source: Option<Box<dyn Error + Send + Sync>> }, LlmError { message: String, source: Option<Box<dyn Error + Send + Sync>> }, ConfigError { message: String }, AdapterError { message: String, source: Option<Box<dyn Error + Send + Sync>> }, HttpError { message: String, status_code: Option<u16>, source: Option<...> }, SerializationError { message: String, source: Option<Box<dyn Error + Send + Sync>> }, HealthCheckFailed { service: String }, Internal { message: String, source: Option<Box<dyn Error + Send + Sync>> }, } Variants Variant Code When EmbeddingError 1000 Embedding service returned an error or was unreachable VectorStoreError 2000 Vector store returned an error or was unreachable LlmError 3000 LLM service returned an error or was unreachable ConfigError 4000 Configuration value was missing or invalid AdapterError 5000 An adapter (formatter, builder, parser) failed HttpError 6000 An HTTP request failed SerializationError 7000 Serialization or deserialization failed HealthCheckFailed 8000 A health check failed against an upstream service Internal 9000 Unexpected internal error Numeric Error Codes Every variant maps to a stable u32 code, suitable for FFI boundaries: ...

MagicAF’s public API is designed with future FFI (Foreign Function Interface) bindings in mind. While bindings are not yet shipped, the architecture choices make them straightforward to implement. Design Decisions 1. Flat DTO Structs All public types (ChatRequest, ChatResponse, SearchResult, GenerationConfig, etc.) are plain structs with owned fields. They map directly to C structs or language-native objects. // Example: SearchResult is a flat, owned struct pub struct SearchResult { pub id: String, pub score: f32, pub payload: serde_json::Value, } 2. Numeric Error Codes MagicError::error_code() returns a u32 that can be passed across an FFI boundary. The human-readable message is available via Display. ...