Documentation

Get up and running with MagicAF in three steps: install prerequisites, add the crates, and run your first query. Prerequisites → What you need before you start — Rust toolchain and local AI services. Installation → Add MagicAF crates to your project and configure environment variables. Quickstart → Build and run a complete RAG pipeline in under 50 lines of code.

MagicAF is built around a small number of powerful ideas. Understanding these concepts will help you use the framework effectively and extend it for your domain. Architecture → The three-layer model: infrastructure, orchestration, and adapters. RAG Pipeline → How the six-step pipeline works, from query to typed result. Traits & Interfaces → The trait system that makes every component pluggable.

Practical guides that walk you through common development tasks with MagicAF. Building Adapters → Create custom EvidenceFormatter, PromptBuilder, and ResultParser implementations. Structured Output → Get typed JSON responses from the LLM using JsonResultParser<T>. Testing → Unit test your adapters and workflows using mock services.

This section documents every public type in the MagicAF framework. Use it as a reference while building. EmbeddingService → Trait and types for dense vector embedding generation. VectorStore → Trait and types for vector database operations. LlmService → Trait and OpenAI-compatible DTOs for language model inference. RAGWorkflow → The pipeline engine — builder, execution, and result types. Adapter Traits → EvidenceFormatter, PromptBuilder, ResultParser, and default implementations. Configuration → All configuration structs and their fields. ...

MagicAF is designed for secure, on-premises deployments where data must not leave the network boundary. This section covers every deployment scenario. Docker Compose → Reference Docker Compose configuration for all services. Air-Gapped Setup → Deploy in fully disconnected environments with no internet access. Edge & Mobile → Run on resource-constrained devices with InMemoryVectorStore. Observability → Structured logging, health checks, and metrics. Scaling → Horizontal scaling strategies for each component. Security → Security checklist and hardening guidance. ...

Complete, runnable examples that demonstrate real-world usage patterns. Each example shows a different level of customization. Minimal RAG → Beginner — The simplest possible RAG pipeline using default adapters. Document Q&A → Intermediate — Structured Q&A with custom adapters and JSON output parsing. Multi-Source Analysis → Advanced — Cross-referencing multiple sources with domain-specific adapters. Running Examples All examples require the same local services (see Prerequisites): # Start Qdrant, embedding server, and LLM server, then: cargo run -p example-minimal-rag cargo run -p example-document-qa cargo run -p example-intelligence-analysis Progression Example Custom Adapters Output Type Complexity Minimal RAG None (all defaults) String ★☆☆ Document Q&A EvidenceFormatter, PromptBuilder QAAnswer (JSON) ★★☆ Multi-Source Analysis All three IntelSummary (JSON) ★★★