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.
The three-layer model: infrastructure, orchestration, and adapters.
How the six-step pipeline works, from query to typed result.
The trait system that makes every component pluggable.
MagicAF follows a strict three-layer architecture. Each layer has a single responsibility, and layers communicate only through well-defined trait boundaries. Layer Model ┌ │ │ └ ┌ │ │ └ ┌ │ │ └ ┌ │ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ( ─ ─ E ─ ─ ─ ─ E ─ ─ y ─ ─ v ─ ─ ─ ─ m ─ ─ o ─ ─ i ─ ─ ─ ─ b ─ ─ u ─ ─ d ─ ─ ─ ─ e ─ ─ r ─ ─ e ─ ─ ─ ─ d ─ ─ ─ ─ n ─ ─ ─ ─ d ─ ─ b ─ ─ c ─ ─ ─ ─ i ─ ─ u ─ ─ e ─ ─ ─ ─ n ─ ─ s ─ ─ 3 F ─ ─ 2 ─ ─ 1 g ─ ─ i ─ ─ o ─ ─ ─ ─ S ─ ─ n ─ ─ · r ─ ─ · ─ ─ · e ─ ─ D e ─ ─ m ─ ─ R ─ ─ r ─ ─ o s ─ ─ A a ─ ─ O A ─ ─ I v ─ ─ m s ─ ─ d t ─ ─ r G ─ ─ n i ─ ─ a ─ ─ a t ─ ─ c W ─ ─ f c ─ ─ i l ─ ─ p e ─ ─ h o ─ ─ r e ─ ─ n o ─ ─ t r ─ ─ e r ─ ─ a ─ ─ g ─ ─ e ─ ─ s k ─ ─ s · ─ ─ A i ─ ─ r · ─ ─ t f ─ ─ t ─ ─ p c ┬ │ ▼ ┬ │ ▼ r l ┬ │ ▼ r V ─ ─ p , ─ ─ L P ─ ─ a o ─ ─ u e ─ ─ l ─ ─ a r ─ ─ t w ─ ─ c c ─ ─ i a ─ ─ y o ─ ─ i < ─ ─ t t ─ ─ c d ─ ─ e m ─ ─ o S ─ ─ u o ─ ─ a a ─ ─ r p ─ ─ n , ─ ─ r r ─ ─ t p ─ ─ t ─ ─ ─ ─ e S ─ ─ i t ─ ─ B ─ ─ L V ─ ─ t ─ ─ o e ─ ─ u ─ ─ a , ─ ─ L o ─ ─ n r ─ ─ i ─ ─ y ─ ─ a r ─ ─ s s ─ ─ l ─ ─ e L ─ ─ y e ─ ─ , ─ ─ d ─ ─ r , ─ ─ e ─ ─ ─ ─ e ─ ─ ─ ─ r · ─ ─ r ─ ─ r ─ ─ … ─ ─ ─ ─ e ─ ─ ─ ─ > ─ ─ L ─ ─ s ─ ─ · ─ ─ ─ ─ l ─ ─ u ─ ─ ─ ─ ─ ─ m ─ ─ l ─ ─ R ─ ─ ─ ─ S ─ ─ t ─ ─ e ─ ─ ─ ─ e ─ ─ ─ ─ s ─ ─ ─ ─ r ─ ─ t ─ ─ u ─ ─ ─ ─ v ─ ─ y ─ ─ l ─ ─ ─ ─ i ─ ─ p ─ ─ t ─ ─ ─ ─ c ─ ─ e ─ ─ P ─ ─ ─ ─ e ─ ─ s ─ ─ a ─ ─ ─ ─ ─ ─ ) ─ ─ r ─ ─ ─ ─ ─ ─ ─ ─ s ─ ─ ─ ─ ─ ─ ─ ─ e ─ ─ ─ ─ ─ ─ ─ ─ r ─ ─ ─ ─ ─ ┐ │ │ ┘ ┐ │ │ ┘ ┐ │ │ ┘ ┐ │ │ ┘ Layer 1 — Infrastructure The infrastructure layer provides the fundamental AI primitives. Each primitive is defined as an async trait. ...
The RAGWorkflow engine executes a deterministic six-step pipeline every time you call .run(). Each step is handled by a pluggable component. Pipeline Overview Q u e r y → [ E m b e d ] → [ S e a r c h ] → [ F o r m a t ] → [ B u i l d P r o m p t ] → [ L L M ] → [ P a r s e ] → R e s u l t < T > Step-by-Step Breakdown Step 1 — Embed the Query let query_vector = embedding_service.embed_single(query).await?; The user’s question is converted into a dense vector using the configured EmbeddingService. This vector represents the semantic meaning of the query. ...
MagicAF’s extensibility comes from its trait-based design. Every major component is accessed through an async trait, and every trait can be implemented by your application. Infrastructure Traits These traits define the fundamental AI building blocks. EmbeddingService Produces dense vector embeddings from text input. #[async_trait] pub trait EmbeddingService: Send + Sync { /// Embed a batch of input strings, returning one vector per input. async fn embed(&self, inputs: &[String]) -> Result<Vec<Vec<f32>>>; /// Embed a single string. async fn embed_single(&self, input: &str) -> Result<Vec<f32>>; /// Verify the upstream service is reachable. async fn health_check(&self) -> Result<()>; } Shipped implementation: LocalEmbeddingService — calls any OpenAI-compatible /v1/embeddings endpoint. ...