smart-router

# A.I. Smart-Router

Intelligently route requests to the optimal AI model using tiered classification with automatic fallback handling and cost optimization.

## How It Works (Silent by Default)

The router operates transparently—users send messages normally and get responses from the best model for their task. No special commands needed.

**Optional visibility**: Include `[show routing]` in any message to see the routing decision.

## Tiered Classification System

The router uses a three-tier decision process:

```
┌─────────────────────────────────────────────────────────────────┐
│                    TIER 1: INTENT DETECTION                      │
│  Classify the primary purpose of the request                     │
├─────────────────────────────────────────────────────────────────┤
│  CODE        │ ANALYSIS    │ CREATIVE   │ REALTIME  │ GENERAL   │
│  write/debug │ research    │ writing    │ news/live │ Q&A/chat  │
│  refactor    │ explain     │ stories    │ X/Twitter │ translate │
│  review      │ compare     │ brainstorm │ prices    │ summarize │
└──────┬───────┴──────┬──────┴─────┬──────┴─────┬─────┴─────┬─────┘
       │              │            │            │           │
       ▼              ▼            ▼            ▼           ▼
┌─────────────────────────────────────────────────────────────────┐
│                  TIER 2: COMPLEXITY ESTIMATION                   │
├─────────────────────────────────────────────────────────────────┤
│  SIMPLE (Tier $)        │ MEDIUM (Tier $$)    │ COMPLEX (Tier $$$)│
│  • One-step task        │ • Multi-step task   │ • Deep reasoning  │
│  • Short response OK    │ • Some nuance       │ • Extensive output│
│  • Factual lookup       │ • Moderate context  │ • Critical task   │
│  → Haiku/Flash          │ → Sonnet/Grok/GPT   │ → Opus/GPT-5      │
└──────────────────────────┴─────────────────────┴───────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────...

# 🧠 A.I. Smart-Router

**Expertise-aware model router for multi-provider AI setups.** Uses weighted semantic scoring and Feb 2026 benchmarks to route each request to the best-suited model. Security redaction, context-overflow protection, and HITL gates for ambiguous intents.

> **v2.0.0** — Now with Phase G Semantic Specialization: expertise-weighted scoring, concurrency detection, and risk-based mandatory routing.

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| **Semantic Domain Detection** | Identifies SOFTWARE_ARCH, CONCURRENCY, LOGICAL_PRECISION, MASSIVE_SYNTHESIS, etc. |
| **Expertise-Weighted Scoring** | Each model scored 0-100 per domain based on Feb 2026 benchmarks (MLOC analysis) |
| **Risk-Based Mandatory Routing** | Medical → GPT-5.2, Terminal/Shell → Opus, Concurrency → Gemini (enforced) |
| **Context Overflow Protection** | >150K tokens auto-routes to Gemini Pro (1M context window) |
| **Security Credential Redaction** | API keys, tokens, passwords blocked before reaching any model |
| **Circuit Breaker** | Persistent state tracks model failures; auto-bypasses degraded providers |
| **HITL Gate** | Low-confidence (<75%) routing triggers Telegram notification for approval |
| **Automatic Fallbacks** | If a model fails, cascades to next best option automatically |
| **Cost Optimization** | Simple tasks use Flash ($0.075/M); complex tasks unlock Opus ($$$$) |
| **Multi-Provider** | Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok) |

---

## 🎯 Expert Domain Map (Feb 2026 Benchmarks)

| Model | Expert Domain | Benchmark | Known Blind Spot |
|-------|---------------|-----------|------------------|
| **Claude Opus 4.5** | SOFTWARE_ARCH | SWE-bench 80.9%, Terminal-bench 59.3% | High cost, verbosity |
| **GPT-5.2 (High)** | LOGICAL_PRECISION | 100% AIME, 22 control flow errors/MLOC | 414 concurrency issues/MLOC |
| **Gemini 3 Pro** | MASSIVE_SYNTHESIS | 1M+ context, 69 concurrency issues/MLOC | 200 control flow errors/M...