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. ...

MagicAF applications are stateless by design. Every component can be scaled independently. Scaling Strategy Component Strategy Notes Embedding Horizontal: N replicas behind a load balancer CPU or GPU instances Qdrant Distributed mode (built-in clustering) Sharding + replication LLM Horizontal: multiple GPU nodes behind a load balancer vLLM supports tensor parallelism Application Horizontal: stateless, scale freely Each instance gets its own RAGWorkflow Embedding Service Scaling Embedding is typically the most CPU/GPU-bound operation. Scale by running multiple replicas: ...

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. ...

MagicAF is designed with security as a first principle. All services run locally, no data leaves the network boundary, and the framework makes no assumptions about data sensitivity. Learn more about MagicAF’s defense-grade architecture and compliance features. Security Architecture No outbound network — every service endpoint is configurable and defaults to localhost No secrets in structs — API keys are Option<String> and never serialized to logs No PII/PHI handling — the framework never inspects payload content; data classification is the application’s responsibility Domain-neutral — adapters control what data enters the pipeline and what leaves it Hardening Checklist All service endpoints bind to internal interfaces only (127.0.0.1 or VPC, not 0.0.0.0) API keys configured for Qdrant and LLM if exposed on a shared network TLS termination at load balancer or reverse proxy Log output does not contain raw payloads (configure log level accordingly) Model files are integrity-checked (SHA-256) after transfer to air-gapped hosts Vector store access is restricted to authorized application instances Docker images are scanned for vulnerabilities before deployment Rust dependencies are audited (cargo audit) Network Security Bind to Internal Interfaces # docker-compose.yml — bind to localhost only services: qdrant: ports: - "127.0.0.1:6333:6333" llm: ports: - "127.0.0.1:8000:8000" API Key Configuration # Set API keys for services on shared networks export QDRANT_API_KEY="your-secret-key" export LLM_API_KEY="your-secret-key" MagicAF passes these keys in request headers automatically. ...

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. ...