🚀 Intelligent AI orchestration platform with multi-provider routing, automatic failover, and cost optimization. Routes tasks to optimal AI models (OpenAI, Claude, Gemini, etc.) based on complexity, cost, latency, and accuracy requirements.
🎯 Key Features 🏗️ Architecture 🔄 Data Flow Pipeline 🔀 Multi-Provider Support 🧠 Intelligent Routing 🛡️ Circuit Breaker 💰 Cost Optimization 🔗 Agent Orchestration Patterns 📊 State Management 📈 Performance Optimization 🛠️ Technology Stack 📁 Project Structure 🚀 Getting Started 💻 API Reference 🧪 Testing 📊 Monitoring 🤝 Contributing 📜 License 🙏 Acknowledgments
Feature
Icon
Description
Multi-Provider Routing 🔀
Intelligent task distribution across OpenAI, Anthropic, Google, Azure, and open-source models
Automatic Failover 🛡️
3-layer resilience: Provider → Model → Agent with instant switching
Cost Optimization 💰
Real-time token counting, budget tracking, and model tiering
Circuit Breaker ⚡
Prevents cascade failures with exponential backoff policies
Multi-Agent Orchestration 🔗
Sequential, parallel, hierarchical, and consensus patterns
Performance Optimization 🚀
Caching, streaming, compression, and predictive pre-loading
State Management 🔄
Hot (Redis), Warm (PostgreSQL), Cold (S3) tiered storage
Observability 📊
Prometheus metrics, structured logging, distributed tracing
High-Level Architecture Diagram ╔═══════════════════════════════════════════════════════════════════════════════════════════════╗
║ COMPASS AI ║
║ Production-Ready AI Orchestration ║
╠═══════════════════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌────────────────────────────────────────────────────────────────────────────────────────────┐ ║
║ │ CLIENTS │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ║
║ │ │ REST API │ │ WebSocket │ │ Python │ │ JavaScript│ │ CLI Tool │ │ ║
║ │ │ Client │ │ Streaming │ │ SDK │ │ SDK │ │ │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ║
║ └────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌────────────────────────────────────────────────────────────────────────────────────────────┐ ║
║ │ API GATEWAY │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ║
║ │ │ Rate │ │ Auth │ │ Request │ │ Cache │ │ Metrics │ │ ║
║ │ │ Limiter │ │ (JWT) │ │ Validator │ │ (Layer) │ │ Collector │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ║
║ └────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ╔═══════════════════════════════════════════════════════════════════════════════════════════╗ ║
║ ║ CONTROL PLANE ║ ║
║ ╠═══════════════════════════════════════════════════════════════════════════════════════════╣ ║
║ ║ ║ ║
║ ║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║ ║
║ ║ │ Task │ │ Model │ │ Health │ │ Cost │ ║ ║
║ ║ │ Classifier │ │ Selection │ │ Monitor │ │ Optimizer │ ║ ║
║ ║ │ & Router │ │ Engine │ │ & Breaker │ │ │ ║ ║
║ ║ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ ║ ║
║ ║ │ │ │ │ ║ ║
║ ║ └──────────────────┴────────┬────────┴──────────────────┘ ║ ║
║ ║ │ ║ ║
║ ║ ┌──────────────┐ ┌──────────────┐ │ ┌──────────────┐ ┌──────────────┐ ║ ║
║ ║ │ Flow │ │ Analytics │◄─┴──│ Telemetry │ │ Config │ ║ ║
║ ║ │ State │ │ Engine │ │ Engine │ │ Manager │ ║ ║
║ ║ │ Manager │ │ │ │ │ │ │ ║ ║
║ ║ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ║ ║
║ ║ ║ ║
║ ╚═══════════════════════════════════════════════════════════════════════════════════════════╝ ║
║ │ ║
║ ▼ ║
║ ╔═══════════════════════════════════════════════════════════════════════════════════════════╗ ║
║ ║ DATA PLANE ║ ║
║ ╠═══════════════════════════════════════════════════════════════════════════════════════════╣ ║
║ ║ ║ ║
║ ║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║ ║
║ ║ │ Agent │ │ Sub- │ │ Context │ │ Token │ ║ ║
║ ║ │ Pool │ │ Agent │ │ Store │ │ Counter │ ║ ║
║ ║ │ Manager │ │ Spawner │ │ (Memory) │ │ Service │ ║ ║
║ ║ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ║ ║
║ ║ ║ ║
║ ║ ┌──────────────────────────────────────────────────────────────────────────────┐ ║ ║
║ ║ │ COMMUNICATION BUS (Message Queue) │ ║ ║
║ ║ │ RabbitMQ / Redis Streams / Apache Kafka │ ║ ║
║ ║ └──────────────────────────────────────────────────────────────────────────────┘ ║ ║
║ ║ ║ ║
║ ╚═══════════════════════════════════════════════════════════════════════════════════════════╝ ║
║ │ ║
║ ▼ ║
║ ╔═══════════════════════════════════════════════════════════════════════════════════════════╗ ║
║ ║ PROVIDER ABSTRACTION LAYER ║ ║
║ ╠═══════════════════════════════════════════════════════════════════════════════════════════╣ ║
║ ║ ║ ║
║ ║ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ║ ║
║ ║ │ OpenAI │ │ Anthropic │ │ Google │ │ Azure │ │ Open │ ║ ║
║ ║ │ (GPT) │ │ (Claude) │ │ (Gemini) │ │ OpenAI │ │ Source │ ║ ║
║ ║ │ │ │ │ │ │ │ │ │ (Llama) │ ║ ║
║ ║ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ ║ ║
║ ║ ║ ║
║ ║ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐ ║ ║
║ ║ │ Rate Limit Manager │ │ Failover Controller │ │ Response Normalizer │ ║ ║
║ ║ └─────────────────────────┘ └─────────────────────────┘ └─────────────────────────┘ ║ ║
║ ║ ║ ║
║ ╚═══════════════════════════════════════════════════════════════════════════════════════════╝ ║
║ │ ║
║ ▼ ║
║ ┌────────────────────────────────────────────────────────────────────────────────────────────┐ ║
║ │ EXTERNAL PROVIDERS │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ ║
║ │ │ api.open │ │api.an- │ │generat- │ │azure. │ │replicate│ │ hugging │ │ vllm │ │ ║
║ │ │ ai.com │ │thropic.com│ │iveai.google│ │azure.com│ │.ai │ │face │ │ server │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ ║
║ └────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════════════════╝
Component
Responsibility
Technology
API Gateway Request routing, auth, rate limiting
FastAPI + Uvicorn
Task Classifier Multi-stage task analysis
NLP + Rule-based
Model Selection Engine Weighted decision matrix
Custom algorithm
Health Monitor Real-time provider health
Prometheus + Custom
Circuit Breaker Failure isolation
Custom implementation
Cost Optimizer Token counting, budgeting
tiktoken + Custom
Agent Pool Manager Sub-agent lifecycle
ThreadPool/ProcessPool
Context Store In-memory state
Redis + In-process
Message Queue Async communication
RabbitMQ/Kafka/Redis
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ TASK LIFECYCLE │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CLIENT │────►│ API │────►│ TASK │────►│ COMPLEXITY │ │
│ │ REQUEST │ │ GATEWAY │ │ CLASSIFIER │ │ SCORING │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ MODEL SELECTION ENGINE │ │
│ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ DECISION MATRIX (Weighted Scoring) │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────────┬─────────┬──────────────┬─────────────────────┐ │ │ │
│ │ │ │ Dimension │ Weight │ Formula │ Example │ │ │ │
│ │ │ ├─────────────────┼─────────┼──────────────┼─────────────────────┤ │ │ │
│ │ │ │Task Complexity │ 30% │ keyword + │ code → Codex │ │ │ │
│ │ │ │ │ │ historical │ │ │ │ │
│ │ │ ├─────────────────┼─────────┼──────────────┼─────────────────────┤ │ │ │
│ │ │ │ Token Budget │ 25% │ input + │ <500 tokens → Tier3 │ │ │ │
│ │ │ │ │ │ expected out │ │ │ │ │
│ │ │ ├─────────────────┼─────────┼──────────────┼─────────────────────┤ │ │ │
│ │ │ │Latency Req. │ 20% │ real-time vs │ streaming → fast │ │ │ │
│ │ │ │ │ │ batch │ │ │ │ │
│ │ │ ├─────────────────┼─────────┼──────────────┼─────────────────────┤ │ │ │
│ │ │ │Cost Constraints│ 15% │ budget per │ $0.01 budget → T3 │ │ │ │
│ │ │ │ │ │ task type │ │ │ │ │
│ │ │ ├─────────────────┼─────────┼──────────────┼─────────────────────┤ │ │ │
│ │ │ │Accuracy Req. │ 10% │ mission vs │ critical → Tier1 │ │ │ │
│ │ │ │ │ │ exploratory │ │ │ │ │
│ │ │ └─────────────────┴─────────┴──────────────┴─────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ TIER CLASSIFICATION │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ TIER 1 (Premium) ─────────────────────────────────────────► │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 🎯 Use Cases: Complex reasoning, critical decisions │ │ │ │
│ │ │ │ 🤖 Models: GPT-4, Claude 3 Opus, Gemini Ultra │ │ │ │
│ │ │ │ 💰 Cost: $0.03-0.15/1K tokens │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ TIER 2 (Balanced) ─────────────────────────────────────────► │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 🎯 Use Cases: General tasks, content generation │ │ │ │
│ │ │ │ 🤖 Models: GPT-3.5-turbo-16k, Claude Sonnet │ │ │ │
│ │ │ │ 💰 Cost: $0.002-0.008/1K tokens │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ TIER 3 (Fast) ─────────────────────────────────────────────► │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 🎯 Use Cases: Simple QA, high-volume tasks │ │ │ │
│ │ │ │ 🤖 Models: Claude Haiku, GPT-3.5-turbo │ │ │ │
│ │ │ │ 💰 Cost: $0.00025-0.001/1K tokens │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ TIER 4 (Specialized) ─────────────────────────────────────► │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 🎯 Use Cases: Code generation, embeddings, search │ │ │ │
│ │ │ │ 🤖 Models: Codex, text-embedding-3, GPT-4 │ │ │ │
│ │ │ │ 💰 Cost: $0.001-0.02/1K tokens │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ FAILOVER EXECUTION │ │
│ │ │ │
│ │ ╭────────────────────────────────────────────────────────────────────╮ │ │
│ │ │ LAYER 1: Provider Failover │ │ │
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ │ OpenAI │───►│ Claude │───►│ Azure │───►│Replicate│ │ │ │
│ │ │ │ GPT-4 │ │ Opus │ │ GPT-4 │ │ Llama-3 │ │ │ │
│ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │
│ │ ╰────────────────────────────────────────────────────────────────────╯ │ │
│ │ │ │
│ │ ╭────────────────────────────────────────────────────────────────────╮ │ │
│ │ │ LAYER 2: Model Failover │ │ │
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ │ GPT-4 │───►│GPT-4-turbo│───►│GPT-3.5 │ │ │ │
│ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │
│ │ ╰────────────────────────────────────────────────────────────────────╯ │ │
│ │ │ │
│ │ ╭────────────────────────────────────────────────────────────────────╮ │ │
│ │ │ LAYER 3: Agent Failover │ │ │
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ │ Agent A │ │ Agent B │ │ Agent C │ │ Consensus│ │ │ │
│ │ │ │(GPT-4) │ │(Claude) │ │(Gemini) │ │ Judge │ │ │ │
│ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │
│ │ ╰────────────────────────────────────────────────────────────────────╯ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ OUTPUT HANDLING │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Response │ │ Cost │ │ Metrics │ │ Cache │ │ │
│ │ │ Builder │ │ Tracker │ │ Logger │ │ Storage │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────────────┘
Provider Comparison Matrix
Provider
API Endpoint
Models
Context Window
Pricing (Input)
Pricing (Output)
Status
OpenAI api.openai.com/v1GPT-4, GPT-4-turbo, GPT-3.5-turbo
128K
$0.03-0.06/1K
$0.06-0.12/1K
✅
Anthropic api.anthropic.comClaude 3 Opus, Sonnet, Haiku
200K
$0.015-0.15/1K
$0.075-0.60/1K
✅
Google generativeai.googleapis.comGemini Pro, Ultra
32K
$0.001-0.005/1K
$0.001-0.005/1K
✅
Azure OpenAI {your-resource}.openai.azure.comGPT-4, GPT-3.5
128K
$0.03-0.06/1K
$0.06-0.12/1K
✅
Replicate api.replicate.comLlama-3, Mistral, CodeLlama
8K-128K
$0.0004-0.002/1K
$0.0004-0.002/1K
✅
HuggingFace api-inference.huggingface.coOpenChat, StarCoder
4K-16K
$0.0004/1K
$0.0004/1K
✅
Model
Reasoning
Coding
Creative
Math
Multilingual
Vision
Function Calling
GPT-4
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
Claude 3 Opus
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐
Gemini Ultra
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
GPT-3.5-turbo
⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐
⭐⭐⭐⭐
-
⭐⭐⭐⭐⭐
Claude Sonnet
⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐⭐
⭐⭐⭐
⭐⭐⭐⭐
Claude Haiku
⭐⭐⭐
⭐⭐⭐
⭐⭐⭐
⭐⭐⭐
⭐⭐⭐⭐
-
⭐⭐⭐
Task Classification Pipeline ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ MULTI-STAGE CLASSIFICATION │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ STAGE 1: Rapid Pre-Filter (Microseconds) │
│ ╭─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Keyword │ │ Token │ │ Urgency │ │ │
│ │ │ Matching │ │ Count │ │ Detection │ │ │
│ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ "code" → Codex <500 → Tier 3 "urgent" → Fast │ │
│ │ "debug" → Codex <1K → Tier 2 "async" → Batch │ │
│ │ "analyze" → Premium >10K → Tier 1 "real-time" → Fastest │ │
│ │ │ │
│ ╰─────────────────────────────────────────────────────────────────────────────────────╯ │
│ │ │
│ ▼ │
│ STAGE 2: Complexity Scoring (Milliseconds) │
│ ╭─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Sentence │ │ Technical │ │ Multi-Step │ │ │
│ │ │ Structure │ │ Term Density │ │ Reasoning │ │ │
│ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ Simple sentence → 1 Few terms → 1 No steps → 1 │ │
│ │ Complex → 3 Technical → 3 Multi-step → 3 │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Domain │ │ Historical │ │ Context │ │ │
│ │ │ Specificity │ │ Pattern │ │ Window │ │ │
│ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ General → 1 Good history → 1 Short → 1 │ │
│ │ Legal/Medical → 3 Poor history → 3 Long → 3 │ │
│ │ │ │
│ ╰─────────────────────────────────────────────────────────────────────────────────────╯ │
│ │ │
│ ▼ │
│ STAGE 3: Dynamic Reassessment (Real-Time) │
│ ╭─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ │ │
│ │ Monitor initial response quality ──► Auto-escalate if insufficient │ │
│ │ │ │
│ │ Tier 3 ──► [Quality < 0.6] ──► Tier 2 ──► [Quality < 0.7] ──► Tier 1 │ │
│ │ │ │
│ │ Tier 1 ──► [Quality > 0.9 + Cost High] ──► De-escalate to Tier 2 │ │
│ │ │ │
│ ╰─────────────────────────────────────────────────────────────────────────────────────╯ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
Priority
Rule Type
Examples
Behavior
🔴 Safety
Hard limits
Cost ceiling, max retries, timeout
Never violate
🟡 Optimization
Best effort
Cache hit, load balance, price arbitrage
Best performance
🟢 Learning
Adaptive
Bayesian updates, A/B testing
Continuous improvement
🛡️ Circuit Breaker System ┌─────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ CLOSED │ │
│ └────┬─────┘ │
│ │ │
│ │ failures > 20% │
│ │ in 60s window │
│ ▼ │
│ ┌──────────────────┐ │
│ │ │ │
│ │ OPEN │ │
│ │ (Provider │ │
│ │ disabled, │ │
│ │ route around) │ │
│ │ │ │
│ └────────┬─────────┘ │
│ │ │
│ │ timeout │
│ │ (1min → 5min) │
│ ▼ │
│ ┌──────────────────┐ │
│ │ │ │
│ │ HALF-OPEN │ │
│ │ (Test with │ │
│ │ limited │ │
│ │ traffic) │ │
│ │ │ │
│ └────────┬─────────┘ │
│ │ │
│ │ 3 successful │
│ │ requests │
│ ▼ │
│ ┌──────────┐ │
│ │ CLOSED │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────┘
Parameter
Value
Description
failure_rate_threshold>20%
Open circuit if failures exceed this
consecutive_failures5
Open after this many failures
timeout60s
Time before half-open
recovery_threshold3
Successful requests to close
backoffexponential
1min → 5min → 15min → 1hr
Real-Time Cost Tracking Architecture ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ COST OPTIMIZATION SYSTEM │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ TOKEN LAYER │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ Provider │ Tokenizer │ Encoding │ Accuracy │ │ │
│ │ │ ───────────────────────────────────────────────────────────────────── │ │ │
│ │ │ OpenAI │ tiktoken │ cl100k_base │ ~99% │ │ │
│ │ │ Anthropic │ anthropic │ BPE │ ~98% │ │ │
│ │ │ Google │ google │ SentencePiece │ ~97% │ │ │
│ │ │ Azure │ tiktoken │ cl100k_base │ ~99% │ │ │
│ │ │ Custom │ huggingface │ BPE │ ~96% │ │ │
│ │ │ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ COST CALCULATION LAYER │ │
│ │ │ │
│ │ Cost = (Input_Tokens × Input_Rate) + (Output_Tokens × Output_Rate) + Fixed_Costs │ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ Input Cost │ + │ Output Cost │ + │ Fixed Cost │ = │ Total Cost │ │ │
│ │ │ Calculator │ │ Calculator │ │ (API key) │ │ Calculator │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ BUDGET MANAGEMENT LAYER │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Budget │ │ Alert │ │ Quota │ │ │
│ │ │ Allocator │ │ Thresholds │ │ Enforcer │ │ │
│ │ │ (per-workflow│ │ (50/75/90%) │ │ (hard limit) │ │ │
│ │ │ per-agent) │ │ │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
Task Type
Tier 1 (Premium)
Tier 2 (Balanced)
Tier 3 (Fast)
Recommended
Simple QA $0.10
$0.02
$0.001
🥉 Tier 3
Code Generation $0.30
$0.08
N/A
🥈 Tier 2 (Codex)
Complex Reasoning $0.50
$0.10
$0.02
🥇 Tier 1
Data Extraction $0.20
$0.05
$0.01
🥉 Tier 3
Creative Writing $0.40
$0.09
$0.03
🥈 Tier 2
Translation $0.15
$0.04
$0.005
🥉 Tier 3
Summarization $0.08
$0.02
$0.002
🥉 Tier 3
Analysis $0.35
$0.08
$0.015
🥈 Tier 2
Strategy
Savings Potential
Implementation
Cache Hit 100%
Semantic similarity matching
Model De-escalation 50-80%
Dynamic quality monitoring
Batch Processing 20-40%
Request batching
Off-Peak Scheduling 10-30%
Time-based routing
Prompt Compression 10-20%
Shortest effective prompts
🔗 Agent Orchestration Patterns 1. Sequential Chain Pattern ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ SEQUENTIAL CHAIN PATTERN │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Input │────►│ Agent │────►│ Agent │────►│ Agent │────►│ Output │ │
│ │ │ │ A │ │ B │ │ C │ │ │ │
│ │ Task │ │ (Parse) │ │ (Process)│ │ (Synth) │ │ Result │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Dependencies: A → B → C (each depends on previous output) │
│ Optimization: Pipeline parallelism where possible │
│ Use Cases: Multi-step analysis, document processing, complex queries │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
2. Parallel Fan-Out/Fan-In Pattern ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ PARALLEL FAN-OUT/FAN-IN PATTERN │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ │
│ │ Input │ │
│ │ Task │ │
│ └────┬─────┘ │
│ │ │
│ ┌────────────────────────────┼────────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent A │ │ Agent B │ │ Agent C │ │
│ │ (Parallel) │ │ (Parallel) │ │ (Parallel) │ │
│ │ Sub-task 1 │ │ Sub-task 2 │ │ Sub-task 3 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └────────────────────────────┼────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Aggregator │ │
│ │ Agent │ │
│ │ (Consensus/ │ │
│ │ Voting) │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Output │ │
│ │ Combined │ │
│ └──────────────┘ │
│ │
│ Use Cases: Multi-perspective analysis, comparison shopping, research aggregation │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
3. Hierarchical Delegation Pattern ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ HIERARCHICAL DELEGATION PATTERN │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ Master │ │
│ │ Agent │ │
│ │ (Orchestr.) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌──────────────────────────────┼──────────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Sub-Agent │ │ Sub-Agent │ │ Sub-Agent │ │
│ │ A │ │ B │ │ C │ │
│ │ (Code) │ │ (Research) │ │ (Synthesis) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Code Review │ │ Web Search │ │ Summary │ │
│ │ Linter │ │ Database │ │ Formatter │ │
│ │ Tester │ │ API Fetch │ │ Writer │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Tree structure with recursive decomposition │
│ Use Cases: Complex projects, software development, comprehensive research │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
4. Debate/Consensus Pattern ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ DEBATE/CONSENSUS PATTERN │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ Input │ │
│ │ Problem │ │
│ └──────┬───────┘ │
│ │ │
│ ┌──────────────────────────────┼──────────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent A │ │ Agent B │ │ Agent C │ │
│ │ (GPT-4) │ │ (Claude) │ │ (Gemini) │ │
│ │ │ │ │ │ │ │
│ │ Solution │ │ Solution │ │ Solution │ │
│ │ v1 │ │ v2 │ │ v3 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────────────────┼──────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Judge │ │
│ │ Agent │ │
│ │ (Consensus) │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Winner │ │ Alternative │ │ Confidence│ │ Final │ │
│ │ Selected │ │ Flagged │ │ Score │ │ Output │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Compare outputs, identify discrepancies, resolve via voting or judge agent │
│ Use Cases: Critical decisions, creative generation, quality assurance │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
Tiered Storage Architecture
Tier
Storage
Use Case
Latency
Persistence
Hot Redis
Active workflows, cached context
<1ms
Optional (TTL)
Warm PostgreSQL
Completed tasks, analytics
<10ms
Durable
Cold S3/Blob
Archives, logs, exports
<100ms
Durable
# Workflow State
{
"workflow_id" : "wf_123" ,
"status" : "running" ,
"current_stage" : "agent_b" ,
"context" : {...},
"history" : [...],
"metadata" : {
"created_at" : "2024-01-15T10:30:00Z" ,
"total_cost" : 0.05 ,
"total_tokens" : 1500
}
}📈 Performance Optimization
Strategy
Latency Impact
Cost Impact
Implementation Complexity
Parallel Processing -40%
+20%
Medium
Intelligent Caching -60%
-30%
High
Predictive Pre-loading -30%
+5%
Medium
Streaming Response -50%
0%
Low
Context Compression -20%
-15%
Medium
Request Batching -25%
-20%
Low
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ PERFORMANCE BENCHMARKS │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Metric │ Baseline │ Optimized │ Improvement │
│ ───────────────────────────────────────────────────────────────────────────────────── │
│ Average Response Time (p50) │ 2.3s │ 1.1s │ -52% │
│ Average Response Time (p95) │ 5.8s │ 2.4s │ -59% │
│ Average Response Time (p99) │ 8.2s │ 3.1s │ -62% │
│ Throughput (req/min) │ 120 │ 350 │ +192% │
│ Cache Hit Rate │ N/A │ 45% │ +45% │
│ Cost per 1K Tokens │ $0.045 │ $0.028 │ -38% │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
Category
Technology
Version
Purpose
Runtime Python
3.11+
Core language
Web Framework FastAPI
0.115+
REST API
ASGI Server Uvicorn
0.30+
Application server
Database PostgreSQL
14+
Primary storage
Cache Redis
7+
In-memory cache
Message Queue RabbitMQ/Kafka
Latest
Async communication
HTTP Client httpx
0.27+
API calls
Validation Pydantic
2.9+
Data models
Provider
SDK
Version
OpenAI
openai
1.50+
Anthropic
anthropic
0.34+
Google
google-generativeai
0.8+
Azure
azure-openai
Latest
Monitoring & Observability
Tool
Purpose
Prometheus
Metrics collection
Grafana
Visualization
Jaeger
Distributed tracing
ELK/Loki
Log aggregation
Compass-AI/
│
├── 📦 pyproject.toml # Project configuration (Hatch)
├── 📜 LICENSE # MIT License
├── 🤝 CONTRIBUTING.md # Contribution guidelines
├── 🚀 README.md # This file
│
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── 🐛 bug_report.md
│ │ └── ✨ feature_request.md
│ └── 📝 PULL_REQUEST_TEMPLATE.md
│
├── src/
│ ├── __init__.py
│ │
│ ├── 🌐 api/ # REST API layer
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── routes/
│ │ │ ├── tasks.py # Task endpoints
│ │ │ ├── workflows.py # Workflow endpoints
│ │ │ └── metrics.py # Metrics endpoints
│ │ └── dependencies/
│ │ ├── auth.py # JWT authentication
│ │ └── rate_limit.py # Rate limiting
│ │
│ ├── 🔧 core/ # Core utilities
│ │ ├── __init__.py
│ │ ├── config.py # Configuration management
│ │ ├── exceptions.py # Custom exceptions
│ │ └── utils.py # Helper functions
│ │
│ ├── 🗄️ db/ # Database layer
│ │ ├── __init__.py
│ │ ├── base.py # SQLAlchemy base
│ │ ├── session.py # Database session
│ │ └── models/ # ORM models
│ │ ├── task.py
│ │ ├── workflow.py
│ │ └── user.py
│ │
│ ├── 📊 models/ # Pydantic schemas
│ │ ├── __init__.py
│ │ ├── task.py
│ │ ├── workflow.py
│ │ └── response.py
│ │
│ └── 🧠 services/ # Business logic
│ ├── __init__.py
│ │
│ ├── 🤖 agents/ # Agent management
│ │ ├── __init__.py
│ │ ├── base.py # Base agent class
│ │ ├── pool.py # Agent pool manager
│ │ └── factory.py # Agent factory
│ │
│ ├── 💾 cache/ # Caching layer
│ │ ├── __init__.py
│ │ ├── engine.py # Cache implementation
│ │ └── strategy.py # Cache strategies
│ │
│ ├── 🛡️ circuit_breaker/ # Failover logic
│ │ ├── __init__.py
│ │ ├── state.py # Circuit states
│ │ ├── breaker.py # Main implementation
│ │ └── monitor.py # Health monitoring
│ │
│ ├── 💰 cost/ # Cost optimization
│ │ ├── __init__.py
│ │ ├── counter.py # Token counting
│ │ ├── calculator.py # Cost calculation
│ │ └── tracker.py # Budget tracking
│ │
│ ├── 🎯 orchestrator/ # Workflow orchestration
│ │ ├── __init__.py
│ │ ├── engine.py # Orchestration engine
│ │ ├── patterns.py # Pattern implementations
│ │ └── state.py # State management
│ │
│ └── 🔀 router/ # Task routing
│ ├── __init__.py
│ ├── classifier.py # Task classifier
│ ├── selector.py # Model selector
│ └── rules.py # Routing rules
│
├── 🧪 tests/ # Test suite
│ ├── __init__.py
│ ├── unit/
│ │ ├── __init__.py
│ │ ├── test_router.py
│ │ ├── test_circuit_breaker.py
│ │ └── test_cost_calculator.py
│ └── integration/
│ ├── __init__.py
│ ├── test_api.py
│ └── test_providers.py
│
├── 📋 docs/ # Documentation
│ ├── architecture.md
│ ├── api-reference.md
│ └── deployment.md
│
└── 🔧 scripts/ # Utility scripts
├── migrate.py
└── seed_data.py
Requirement
Version
Installation
🐍 Python
3.11+
python --version
🗄️ PostgreSQL
14+
brew install postgresql
🧠 Redis
7+
brew install redis
# 1. Clone repositorycd Compass-AI
# 2. Create virtual environment# 3. Activate virtual environment# Windows:\S cripts\a ctivate
# Linux/Mac:source venv/bin/activate
# 4. Install dependencies" .[dev]" # 5. Configure environment# Edit .env with your API keys# 6. Run database migrations# 7. Start the server# Build and run with Docker Compose# View logs# Stop
Method
Endpoint
Description
Auth
POST
/api/v1/tasksSubmit new task
✅
GET
/api/v1/tasks/{task_id}Get task status
✅
GET
/api/v1/tasks/{task_id}/streamStream task progress
✅
DELETE
/api/v1/tasks/{task_id}Cancel task
✅
POST
/api/v1/workflowsSubmit workflow
✅
GET
/api/v1/workflows/{workflow_id}Get workflow status
✅
GET
/api/v1/metricsGet system metrics
✅
GET
/api/v1/providersList available providers
✅
POST
/api/v1/admin/configUpdate configuration
🔒
GET
/api/v1/healthHealth check
❌
Request/Response Examples curl -X POST https://api.compass-ai.io/api/v1/tasks \
-H " Authorization: Bearer YOUR_API_KEY" " Content-Type: application/json" ' { "prompt": "Write a Python function to calculate factorial",
"complexity": "medium",
"preferred_provider": "openai"
}' {
"task_id" : " task_abc123" "status" : " processing" "model_selected" : " gpt-4-turbo" "estimated_time" : 2.5 ,
"streaming_url" : " wss://api.compass-ai.io/api/v1/tasks/task_abc123/stream" # Run all tests# Run with coverage# Run specific test files# Run with verbose output# Run only failed testsName Stmts Miss Cover Missing
--------------------------------------------------------------
src/api/ 120 10 92% ...
src/services/router/ 250 25 90% ...
src/services/circuit_breaker/ 180 15 92% ...
src/services/cost/ 200 20 90% ...
--------------------------------------------------------------
TOTAL 4500 450 90%
Metric
Type
Labels
Description
compass_requests_totalCounter
provider, model, status
Total requests
compass_requests_duration_secondsHistogram
provider, model
Request duration
compass_tokens_totalCounter
provider, model, type
Token count
compass_cost_dollarsCounter
provider, workflow
Cost tracking
compass_cache_hits_totalCounter
-
Cache hits
compass_cache_misses_totalCounter
-
Cache misses
compass_failover_totalCounter
provider, from_model, to_model
Failover events
compass_circuit_breaker_stateGauge
provider
Circuit state (0/1/2)
compass_active_tasksGauge
-
Active tasks
compass_queue_depthGauge
-
Queue depth
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ GRAFANA DASHBOARD │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Requests/sec (by model) │ │ Avg latency (p50/p95/p99) │ │
│ │ [████████████░░░] 350/s │ │ [████░░░░] 1.1s / 2.4s / 3.1s│ │
│ └─────────────────────────────┘ └─────────────────────────────┘ │
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Cost/hr (by provider) │ │ Provider health status │ │
│ │ $12.50 (OpenAI) │ │ 🟢 OpenAI 🟢 Claude 🟢 │ │
│ │ $4.20 (Anthropic) │ │ 🟢 Google 🟡 Azure │ │
│ └─────────────────────────────┘ └─────────────────────────────┘ │
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Cache hit ratio │ │ Circuit breaker states │ │
│ │ [████████░░░] 45% │ │ Closed: 5 Open: 0 Half: 0 │ │
│ └─────────────────────────────┘ └─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
We welcome contributions! Please read our Contributing Guide for details.
🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing-feature)
🔧 Make your changes
🧪 Run tests (pytest)
📝 Commit your changes (git commit -m 'Add amazing feature')
📤 Push to the branch (git push origin feature/amazing-feature)
🔄 Create a Pull Request
Python : PEP 8 with RuffType Hints : Required for new codeDocstrings : Google styleTests : pytest with 90%+ coverage
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ using amazing open-source projects
Project
Purpose
FastAPI Web framework
LangChain/LangGraph Agent orchestration patterns
AutoGen (Microsoft) Multi-agent frameworks
PostgreSQL Data persistence
Redis Caching and state management
Prometheus Metrics collection
Tiktoken OpenAI tokenization
Made with 🧭 for intelligent AI orchestration
