Skip to main content
Back to Docs

Architecture Overview

How AgentiCraft's three packages work together to provide a complete AI agent infrastructure.

2 min read

Package Architecture

AgentiCraft is built as three focused packages, each with a clear responsibility:

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                        │
└──────────┬──────────────────┬──────────────────┬────────────┘
           │                  │                  │
           v                  v                  v
┌──────────────────┐ ┌────────────────┐ ┌────────────────────┐
│  agenticraft-llm │ │  agenticraft-  │ │   agenticraft-     │
│                  │ │  foundation    │ │   types            │
│  14 providers    │ │                │ │                    │
│  Cost routing    │ │  CSP algebra   │ │  Pydantic models   │
│  Key rotation    │ │  Topology      │ │  Protocols         │
│  Circuit breaker │ │  Verification  │ │  Error hierarchy   │
│  Rate limiting   │ │  Proofs        │ │  Config schemas    │
│  Gateway         │ │                │ │                    │
└────────┬─────────┘ └───────┬────────┘ └─────────┬──────────┘
         │                   │                     │
         └───────────────────┴─────────────────────┘
                             │
                    ┌────────┴────────┐
                    │  pydantic >=2.0 │
                    └─────────────────┘

agenticraft-types

The contract layer. Defines shared interfaces that all packages depend on:

  • Pydantic models — CompletionRequest, CompletionResponse, Message, Usage, StreamChunk, ProviderConfig
  • Protocol classes — Provider, StreamingProvider, Router, CircuitBreakerLike, KeyPoolLike
  • Error hierarchy — 12 exception types with structured error details
  • Enums — ProviderName, FailureType, RoutingStrategy, MessageRole, CircuitBreakerState
  • Configuration — RetryConfig, CircuitBreakerConfig, RateLimitConfig

Design constraints: under 1,000 LOC, zero business logic, only dependency is pydantic>=2.0.

agenticraft-llm

The operational layer. Provides a unified interface to LLM providers with production-grade resilience:

  • 14 providers — OpenAI, Anthropic, Google, Azure, Bedrock, Cohere, Ollama, Fireworks, Cerebras, DeepSeek, xAI, OpenRouter, Perplexity, Nebius
  • Cost-aware routing — Thompson sampling selects the optimal provider based on cost, latency, and success rate
  • Key pool management — Multi-key rotation with 5 strategies (round robin, least used, random, weighted, failover)
  • Circuit breaker — Prevents cascading failures when providers go down
  • Rate limiter — Token bucket algorithm for request throttling
  • Gateway — OpenAI-compatible FastAPI server for drop-in replacement

agenticraft-foundation

The mathematical layer. Formal verification and analysis for multi-agent systems:

  • CSP algebra — Process calculus for specifying and verifying agent communication
  • Topology analysis — Network graph metrics, Laplacian eigenvalues, connectivity analysis
  • Stochastic primitives — Quality functions, ensemble judges, cost routing formalization
  • Proofs — Machine-checkable correctness proofs for consensus protocols

Request Flow

A typical LLM request flows through the stack:

  Client Request
       │
       v
┌──────────────┐     CompletionRequest validated
│    Types     │──── by Pydantic models
└──────┬───────┘
       │
       v
┌──────────────┐     Thompson sampling picks
│    Router    │──── cheapest healthy provider
└──────┬───────┘
       │
       v
┌──────────────┐     Rotates to next available
│   Key Pool   │──── API key (5 strategies)
└──────┬───────┘
       │
       v
┌──────────────┐     Checks provider health,
│Circuit Breaker│──── rejects if OPEN
└──────┬───────┘
       │
       v
┌──────────────┐
│ Provider SDK │──── OpenAI / Anthropic / Google / ...
└──────┬───────┘
       │
       v
┌──────────────┐     CompletionResponse validated,
│    Types     │──── usage tracked
└──────────────┘

Integration Points

Types + LLM

All LLM providers implement the Provider protocol from agenticraft-types:

from agenticraft_types import Provider, CompletionRequest, CompletionResponse
 
class OpenAIProvider(Provider):
    async def complete(self, request: CompletionRequest) -> CompletionResponse:
        ...

LLM + Foundation

Foundation topology analysis evaluates multi-agent communication networks:

from agenticraft_foundation.topology import NetworkGraph
 
# Analyze agent communication topology
graph = NetworkGraph(agents=["planner", "coder", "reviewer"])
graph.add_edge("planner", "coder")
graph.add_edge("coder", "reviewer")
graph.add_edge("reviewer", "planner")
 
# Algebraic connectivity (Fiedler value)
lambda_2 = graph.fiedler_value()

Next Steps