AI-Model-Context-Routing

# 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)

```bash
# 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
```bash
# 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
```bash
# 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**:
   ```bash
   export ANTHROPIC_API_KEY="sk-ant-..."
   export OPENAI_API_KEY="sk-..."
   export GOOGLE_API_KEY="AIza..."
   ```

3. **Via .env File**:
   ```bash
   # 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:

```json
{
  "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
```bash
# 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
```bash
# 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

```bash
# 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:

```bash
# 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
```python
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
- [ ] *

[truncated…]