Architecture Overview

Synaptic is organized as a Cargo workspace with 26 library crates, 1 facade crate, and several example binaries. The crates form a layered architecture where each layer builds on the one below it.

Crate Layers

Core Layer

synaptic-core defines all shared traits and types. Every other crate depends on it.

• Traits: ChatModel, Tool, RuntimeAwareTool, MemoryStore, CallbackHandler, Store, Embeddings
• Types: Message, ChatRequest, ChatResponse, ToolCall, ToolDefinition, ToolChoice, AIMessageChunk, TokenUsage, RunEvent, RunnableConfig, Runtime, ToolRuntime, ModelProfile, Item, ContentBlock
• Error type: SynapticError (20 variants covering all subsystems)
• Stream type: ChatStream (Pin<Box<dyn Stream<Item = Result<AIMessageChunk, SynapticError>> + Send>>)

Implementation Crates

Each crate implements one core trait or provides a focused capability:

Composition Crates

These crates provide higher-level orchestration:

Retrieval Pipeline

These crates form the document ingestion and retrieval pipeline:

Evaluation

Advanced Crates

These crates provide specialized capabilities for production agent systems:

Integration Crates

These crates provide third-party service integrations:

Facade

synaptic re-exports all sub-crates for convenient single-import usage:

use synaptic::core::{ChatModel, Message, ChatRequest};
use synaptic::openai::OpenAiChatModel;     // requires "openai" feature
use synaptic::models::ScriptedChatModel;   // requires "model-utils" feature
use synaptic::runnables::{Runnable, RunnableLambda};
use synaptic::graph::{StateGraph, create_react_agent};

Dependency Diagram

All crates depend on synaptic-core for shared traits and types. Higher-level crates depend on the layer below:

                            ┌──────────┐
                            │ synaptic │  (facade: re-exports all)
                            └─────┬────┘
                                  │
     ┌──────────────┬─────────────┼──────────────┬───────────────┐
     │              │             │              │               │
 ┌───┴───┐   ┌─────┴────┐  ┌────┴─────┐  ┌─────┴────┐   ┌─────┴───┐
 │ deep  │   │middleware│  │  graph   │  │runnables │   │  eval   │
 └───┬───┘   └─────┬────┘  └────┬─────┘  └────┬─────┘   └─────┬───┘
     │              │            │              │               │
     ├──────────────┴────┬───────┴──────────────┤               │
     │                   │                      │               │
┌────┴──┐ ┌─────┐ ┌─────┴──┐ ┌──────┐ ┌───────┐│┌──────┐┌─────┴──┐
│models │ │tools│ │memory  │ │store │ │prompts│││parsers││cache   │
└───┬───┘ └──┬──┘ └───┬────┘ └──┬───┘ └───┬───┘│└───┬───┘└───┬────┘
    │        │        │         │         │    │    │        │
    │  ┌─────┴─┬──────┤    ┌────┘         │    │    │        │
    │  │       │      │    │              │    │    │        │
    ├──┤  ┌────┴──┐   │  ┌─┴────┐  ┌─────┴────┴────┴────────┤
    │  │  │macros │   │  │ mcp  │  │    callbacks            │
    │  │  └───┬───┘   │  └──┬───┘  └────────┬────────────────┘
    │  │      │       │     │               │
  ┌─┴──┴──────┴───────┴─────┴───────────────┴──┐
  │              synaptic-core                  │
  │  (ChatModel, Tool, Store, Embeddings, ...) │
  └──────────────────┬──────────────────────────┘
                     │
  Provider crates (each depends on synaptic-core + synaptic-models):
  openai, anthropic, gemini, ollama

  Retrieval pipeline:

  loaders ──► splitters ──► embeddings ──► vectorstores ──► retrieval

  Integration crates: qdrant, pgvector, redis, pdf

Design Principles

Async-first with #[async_trait]

Every trait in Synaptic is async. The ChatModel::chat() method, Tool::call(), MemoryStore::load(), and Runnable::invoke() are all async functions. This means you can freely await network calls, database queries, and concurrent operations inside any implementation without blocking the runtime.

Arc-based sharing

Synaptic uses Arc<RwLock<_>> for registries (like ToolRegistry) where many readers need concurrent access, and Arc<tokio::sync::Mutex<_>> for stateful components (like callbacks and memory stores) where mutations must be serialized. This allows safe sharing across async tasks and agent sessions.

Session isolation

Memory stores and agent runs are keyed by session_id. Multiple conversations can run concurrently on the same model and tool set without state leaking between sessions.

Event-driven callbacks

The CallbackHandler trait receives RunEvent values at each lifecycle stage (run started, LLM called, tool called, run finished, run failed). You can compose multiple handlers with CompositeCallback for logging, tracing, metrics, and recording simultaneously.

Typed error handling

SynapticError has one variant per subsystem (Prompt, Model, Tool, Memory, Graph, etc.). This makes it straightforward to match on specific failure modes and provide targeted recovery logic.

Composition over inheritance

Rather than deep trait hierarchies, Synaptic favors composition. A CachedChatModel wraps any ChatModel. A RetryChatModel wraps any ChatModel. A RunnableWithFallbacks wraps any Runnable. You stack behaviors by wrapping, not by extending base classes.