Context Router - AI Model Routing System

An intelligent AI model routing system that automatically selects the best model (Claude 3.5 Sonnet, GPT-4o, Gemini 2.0 Flash) for your queries using advanced context analysis and structured routing logic.

🌟 Features

Core Routing System

• 🧠 Intelligent Query Analysis - Categorizes queries by type (coding, math, creative, analysis, etc.)
• 🎯 Smart Model Selection - Chooses optimal model based on capabilities, cost, and performance
• 💰 Cost Optimization - Balances quality with cost efficiency
• 🔄 Automatic Fallback - Seamlessly handles model failures
• 📊 Performance Tracking - Monitors routing decisions and outcomes

Modern Web Interface

• 🎨 Beautiful React Frontend - Modern, responsive UI built with React 18 and Tailwind CSS
• 🔍 Real-time Analysis - See how queries are analyzed and routed
• 📈 Analytics Dashboard - Comprehensive routing statistics and insights
• ⚙️ Settings Management - Easy API key configuration and routing parameters
• 📱 Mobile Responsive - Works perfectly on all devices

API & Integration

• 🚀 FastAPI Backend - High-performance async API with automatic documentation
• 🔧 MCP Protocol - Model Context Protocol integration for advanced workflows
• 🌐 RESTful API - Clean, well-documented API endpoints
• 📚 Interactive Docs - Automatic API documentation with Swagger UI

🚀 Quick Start

Option 1: One-Command Startup (Recommended)

# Clone the repository
git clone <repository-url>
cd Context-Router

# Run the startup script (installs dependencies and starts both servers)
./start.sh

This will start:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Option 2: Manual Setup

Backend Setup

# Install Python dependencies
pip3 install -r requirements.txt

# Start the backend API
python3 -m uvicorn src.api:app --reload --host localhost --port 8000

Frontend Setup

# Install Node.js dependencies
cd frontend
npm install

# Start the development server
npm run dev

🔧 Configuration

API Keys Setup

1. Via Web Interface (Recommended):

   • Open http://localhost:3000/settings
   • Enter your API keys in the Settings page
   • Restart the backend server

2. Via Environment Variables:

   export ANTHROPIC_API_KEY="sk-ant-..."
   export OPENAI_API_KEY="sk-..."
   export GOOGLE_API_KEY="AIza..."

3. Via .env File:

   # Copy the example file
   cp .env.example .env
   
   # Edit with your API keys
   nano .env

Model Configuration

The system uses context.json to configure model capabilities and routing rules:

{
  "models": {
    "claude-3-5-sonnet": {
      "capabilities": {
        "reasoning": 0.95,
        "coding": 0.90,
        "analysis": 0.85
      },
      "strengths": ["reasoning", "code analysis", "safety"]
    }
  },
  "routing": {
    "keywords": {
      "coding": ["function", "code", "python", "javascript"],
      "math": ["calculate", "equation", "integral"]
    }
  }
}

🏗️ Architecture

System Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  React Frontend │    │   FastAPI        │    │  AI Models      │
│  (Port 3000)    │◄──►│   Backend        │◄──►│  Claude/GPT/    │
│                 │    │   (Port 8000)    │    │  Gemini         │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Backend Components

• Query Analyzer (src/routing/query_analyzer.py) - Analyzes and categorizes queries
• Model Selector (src/routing/model_selector.py) - Selects optimal model
• Context Router (src/routing/router.py) - Orchestrates the routing process
• Model Implementations (src/models/) - Individual model connectors
• API Layer (src/api.py) - FastAPI web service
• MCP Server (src/mcp_server.py) - Model Context Protocol integration

Frontend Components

• Query Interface - Submit queries with advanced options
• Analysis Display - Real-time query analysis visualization
• Models Dashboard - View available models and capabilities
• Analytics Charts - Routing statistics and performance metrics
• Settings Panel - Configuration management

📊 Usage Examples

Web Interface

1. Open http://localhost:3000
2. Enter a query like "Write a Python function to calculate fibonacci numbers"
3. Click "Route Query" to see the full routing process
4. Or click "Analyze Only" to see routing decisions without API calls

API Usage

# Analyze a query
curl -X POST "http://localhost:8000/analyze" \
     -H "Content-Type: application/json" \
     -d '{"query": "What is machine learning?"}'

# Route a query to optimal model
curl -X POST "http://localhost:8000/route" \
     -H "Content-Type: application/json" \
     -d '{"query": "Explain quantum computing", "temperature": 0.7}'

CLI Usage

# Route a query
python3 -m src.cli route "Write a sorting algorithm in Python"

# Analyze query routing
python3 -m src.cli analyze "What is the capital of France?"

# List available models
python3 -m src.cli models

# View system statistics
python3 -m src.cli stats

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Or build individual containers
docker build -f Dockerfile.backend -t context-router-backend .
docker build -f frontend/Dockerfile -t context-router-frontend ./frontend

🧪 Testing

The system includes comprehensive testing and works in analysis mode without API keys:

# Test query analysis (no API keys required)
python3 -c "
from src.routing.router import ContextRouter
router = ContextRouter()
result = router.analyze_query('Write a Python function')
print(f'Selected model: {result[1].selected_model}')
print(f'Reasoning: {result[1].reasoning}')
"

📈 Monitoring & Analytics

Available Metrics

• Query Volume - Total queries processed
• Model Distribution - Usage across different models
• Success Rate - Successful routing percentage
• Average Response Time - Performance metrics
• Cost Analysis - Cost breakdown by model
• Complexity Distribution - Query complexity patterns

Access Analytics

• Web Dashboard: http://localhost:3000/analytics
• API Endpoint: http://localhost:8000/stats
• CLI Command: python3 -m src.cli stats

🔌 Integration

MCP Protocol

from src.mcp_server import MCPServer

# Initialize MCP server
server = MCPServer()

# Use MCP tools
tools = server.get_available_tools()
result = server.execute_tool("query_analyzer", {"query": "Hello world"})

REST API

• POST /route - Route query to optimal model
• POST /analyze - Analyze query without routing
• GET /models - List available models
• GET /stats - System statistics
• GET /health - Health check

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the /docs endpoint for API documentation
• Issues: Open an issue on GitHub for bugs or feature requests
• Discussions: Use GitHub Discussions for questions and ideas

🎯 Roadmap

• Advanced Analytics - More detailed routing metrics
• Custom Models - Support for additional AI models
• Caching Layer - Response caching for improved performance
• Rate Limiting - Request rate limiting and throttling
• Authentication - User authentication and authorization
• Multi-tenant - Support for multiple organizations
• Plugins - Plugin system for extensibility

---

Built with ❤️ using Python, FastAPI, React, and TypeScript