model-router-cli 1.0.0__py3-none-any.whl

app/cli/main.py

@@ -0,0 +1,287 @@
+import sys
+import os
+import asyncio
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+
+# Set UTF-8 encoding support for Windows terminals
+if sys.platform.startswith("win"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
+
+from app.config.settings import get_settings
+from app.analyzer.heuristics import analyze_request_heuristics
+from app.router.engine import route_request
+from app.storage.database import init_db, AsyncSessionLocal
+from app.storage.models import ModelRecord, RoutingPolicyRecord
+from app.api.routes import db_model_to_meta
+from app.fallback.handler import execute_with_fallback
+from sqlalchemy import select
+
+app = typer.Typer(help="Model Router: Intelligent LLM Request Routing Platform")
+console = Console(safe_box=True)
+settings = get_settings()
+
+
+@app.command()
+def doctor():
+    """Run environment, connectivity, and dependency health checks."""
+    console.print(Panel.fit("[bold cyan]Model Router Diagnostics (modelrouter doctor)[/bold cyan]"))
+    
+    # 1. Python Check
+    py_ver = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    console.print(f" [green][OK][/green] Python: [bold]{py_ver}[/bold]")
+    
+    # 2. Database Check
+    try:
+        asyncio.run(init_db())
+        console.print(" [green][OK][/green] SQLite Database: [bold]Initialized & Ready[/bold]")
+    except Exception as exc:
+        console.print(f" [red][FAIL][/red] Database Error: {exc}")
+
+    # 3. Ollama Connectivity Check
+    ollama_ok = False
+    try:
+        r = httpx.get(f"{settings.OLLAMA_BASE_URL}/api/tags", timeout=1.5)
+        if r.status_code == 200:
+            models = [m.get("name") for m in r.json().get("models", [])]
+            console.print(f" [green][OK][/green] Ollama (Local): [bold]Connected[/bold] ({len(models)} local models found)")
+            ollama_ok = True
+    except Exception:
+        pass
+    if not ollama_ok:
+        console.print(f" [yellow][!][/yellow] Ollama (Local): [dim]Not running on {settings.OLLAMA_BASE_URL} (Optional, local fallback available)[/dim]")
+
+    # 4. Mock Engine
+    console.print(" [green][OK][/green] Mock Engine: [bold]Ready (Zero API keys required)[/bold]")
+
+    # 5. External Providers
+    if settings.OPENAI_API_KEY:
+        console.print(" [green][OK][/green] OpenAI Provider: [bold]API Key Configured in .env[/bold]")
+    else:
+        console.print(" [yellow][!][/yellow] OpenAI Provider: [dim]Not configured (Optional)[/dim]")
+
+    if settings.ANTHROPIC_API_KEY:
+        console.print(" [green][OK][/green] Anthropic Provider: [bold]API Key Configured in .env[/bold]")
+    else:
+        console.print(" [yellow][!][/yellow] Anthropic Provider: [dim]Not configured (Optional)[/dim]")
+
+    if settings.GEMINI_API_KEY:
+        console.print(" [green][OK][/green] Gemini Provider: [bold]API Key Configured in .env[/bold]")
+    else:
+        console.print(" [yellow][!][/yellow] Gemini Provider: [dim]Not configured (Optional)[/dim]")
+
+    console.print("\n[bold green]Ready for local-first intelligent routing![/bold green]\n")
+
+
+@app.command()
+def models():
+    """List all registered candidate models and their capability scores."""
+    async def _list():
+        await init_db()
+        async with AsyncSessionLocal() as db:
+            res = await db.execute(select(ModelRecord).order_by(ModelRecord.tier, ModelRecord.name))
+            records = res.scalars().all()
+            
+            table = Table(title="Model Router Registry", border_style="bright_blue")
+            table.add_column("Model ID", style="cyan", no_wrap=True)
+            table.add_column("Tier", style="magenta")
+            table.add_column("Provider", style="green")
+            table.add_column("Context", style="yellow")
+            table.add_column("Quality", style="blue")
+            table.add_column("Speed", style="cyan")
+            table.add_column("Cost / 1K In/Out", style="white")
+
+            for m in records:
+                cost_str = f"${m.cost_per_input_token*1000:.4f} / ${m.cost_per_output_token*1000:.4f}" if m.cost_per_input_token > 0 else "Free ($0)"
+                table.add_row(
+                    m.id,
+                    m.tier,
+                    m.provider,
+                    f"{m.context_window:,}",
+                    f"{m.quality_score*100:.0f}%",
+                    f"{m.speed_score*100:.0f}%",
+                    cost_str,
+                )
+            console.print(table)
+
+    asyncio.run(_list())
+
+
+@app.command()
+def route(
+    prompt: str = typer.Argument(..., help="Prompt text to route"),
+    policy: str = typer.Option("balanced", "--policy", "-p", help="Routing policy to use"),
+):
+    """Analyze prompt and explain why the optimal model was selected (Dry Run)."""
+    async def _route():
+        await init_db()
+        analysis = analyze_request_heuristics(prompt)
+        
+        async with AsyncSessionLocal() as db:
+            res_m = await db.execute(select(ModelRecord).filter_by(is_active=True))
+            models = [db_model_to_meta(m) for m in res_m.scalars().all()]
+            
+            res_p = await db.execute(select(RoutingPolicyRecord).filter_by(id=policy))
+            pol = res_p.scalar_one_or_none()
+            weights = {
+                "quality_weight": pol.quality_weight if pol else 0.35,
+                "cost_weight": pol.cost_weight if pol else 0.25,
+                "speed_weight": pol.speed_weight if pol else 0.20,
+                "capability_weight": pol.capability_weight if pol else 0.15,
+                "reliability_weight": pol.reliability_weight if pol else 0.05,
+            }
+
+            decision = route_request(
+                analysis=analysis,
+                available_models=models,
+                policy_weights=weights,
+                policy_name=policy,
+            )
+
+            console.print(Panel.fit(
+                f"[bold white]Prompt:[/bold white] \"{prompt}\"\n"
+                f"[bold cyan]Task Type:[/bold cyan] {analysis.task_type.value} | [bold cyan]Complexity:[/bold cyan] {analysis.complexity_label.value} ({analysis.complexity:.2f})\n"
+                f"[bold green]Selected Model:[/bold green] [bold yellow]{decision.selected_model_name}[/bold yellow] ({decision.selected_model})\n"
+                f"[bold magenta]Confidence:[/bold magenta] {decision.confidence * 100:.0f}%\n"
+                f"[bold blue]Estimated Latency:[/bold blue] {decision.estimated_latency_ms:.0f}ms | [bold blue]Estimated Cost:[/bold blue] ${decision.estimated_cost_usd:.6f}",
+                title="ROUTING DECISION",
+                border_style="bright_blue",
+            ))
+
+            console.print("[bold cyan]Why this model?[/bold cyan]")
+            for r in decision.reasons:
+                console.print(f"  [green]+[/green] {r}")
+
+            if decision.rejected_candidates:
+                console.print("\n[bold red]Rejected Candidates:[/bold red]")
+                for cid, reason in decision.rejected_candidates.items():
+                    console.print(f"  [dim]- {cid}: {reason}[/dim]")
+
+    asyncio.run(_route())
+
+
+@app.command()
+def run(
+    prompt: str = typer.Argument(..., help="Prompt to route and execute"),
+    policy: str = typer.Option("balanced", "--policy", "-p", help="Routing policy to use"),
+):
+    """Route request and execute inference through the chosen provider."""
+    async def _run():
+        await init_db()
+        analysis = analyze_request_heuristics(prompt)
+        
+        async with AsyncSessionLocal() as db:
+            res_m = await db.execute(select(ModelRecord).filter_by(is_active=True))
+            models = [db_model_to_meta(m) for m in res_m.scalars().all()]
+            
+            decision = route_request(
+                analysis=analysis,
+                available_models=models,
+                policy_weights={"quality_weight": 0.35, "cost_weight": 0.25, "speed_weight": 0.20, "capability_weight": 0.15, "reliability_weight": 0.05},
+                policy_name=policy,
+            )
+
+            console.print(f"[bold cyan]Routing to:[/bold cyan] {decision.selected_model} via provider: {decision.provider}...")
+            
+            resp, fallback_used, orig_m, fb_reason = await execute_with_fallback(
+                prompt=prompt,
+                selected_model_id=decision.selected_model,
+                selected_provider_id=decision.provider,
+                all_models=models,
+            )
+
+            console.print(Panel(
+                resp.content,
+                title=f"RESPONSE from {resp.model} ({'FALLBACK: ' + orig_m if fallback_used else 'PRIMARY'})",
+                subtitle=f"Latency: {resp.provider_latency_ms:.0f}ms | Tokens: {resp.total_tokens}",
+                border_style="green" if not fallback_used else "yellow",
+            ))
+
+    asyncio.run(_run())
+
+
+@app.command()
+def traffic(limit: int = 10):
+    """View recent routed traffic log."""
+    async def _traffic():
+        await init_db()
+        from app.storage.models import RequestRecord
+        from sqlalchemy import desc
+        async with AsyncSessionLocal() as db:
+            res = await db.execute(select(RequestRecord).order_by(desc(RequestRecord.timestamp)).limit(limit))
+            records = res.scalars().all()
+            
+            table = Table(title="Recent Routed Traffic Feed", border_style="bright_blue")
+            table.add_column("Time", style="dim")
+            table.add_column("Task", style="cyan")
+            table.add_column("Selected Model", style="green")
+            table.add_column("Latency", style="yellow")
+            table.add_column("Cost", style="magenta")
+            table.add_column("Prompt Sample", style="white")
+
+            for r in records:
+                t_str = r.timestamp.strftime("%H:%M:%S") if r.timestamp else "N/A"
+                table.add_row(
+                    t_str,
+                    r.task_type,
+                    r.selected_model,
+                    f"{r.total_latency_ms:.0f}ms",
+                    f"${r.estimated_cost:.5f}",
+                    r.prompt[:40] + ("..." if len(r.prompt) > 40 else ""),
+                )
+            console.print(table)
+
+    asyncio.run(_traffic())
+
+
+@app.command()
+def analytics():
+    """Display system-wide routing performance and cost savings analytics."""
+    async def _analytics():
+        await init_db()
+        from app.analytics.service import get_system_analytics
+        async with AsyncSessionLocal() as db:
+            data = await get_system_analytics(db)
+            console.print(Panel.fit(
+                f"[bold cyan]Total Routed Requests:[/bold cyan] {data['total_requests']}\n"
+                f"[bold green]Average Latency:[/bold green] {data['avg_latency_ms']}ms (Routing overhead: {data['avg_routing_latency_ms']}ms)\n"
+                f"[bold yellow]Total Cost:[/bold yellow] ${data['total_cost_usd']:.6f}\n"
+                f"[bold magenta]Cost Saved vs Baseline:[/bold magenta] ${data['savings']['cost_saved_usd']:.6f} ({data['savings']['savings_percentage']}%)\n"
+                f"[bold blue]Fallback Rate:[/bold blue] {data['fallback_rate_percent']}%\n",
+                title="MODEL ROUTER ANALYTICS OVERVIEW",
+                border_style="bright_blue",
+            ))
+
+    asyncio.run(_analytics())
+
+
+@app.command()
+def ui(
+    host: str = typer.Option("127.0.0.1", "--host", "-h", help="Host address to bind the web server"),
+    port: int = typer.Option(8000, "--port", "-p", help="Port to run the Model Router Control Room on"),
+):
+    """Launch the Model Router API Gateway & AI Traffic Control Room UI."""
+    import uvicorn
+    console.print(Panel.fit(
+        f"[bold cyan]Starting Model Router AI Traffic Control Room[/bold cyan]\n"
+        f"Web Dashboard: [bold green]http://{host}:{port}[/bold green]\n"
+        f"API Documentation: [bold green]http://{host}:{port}/docs[/bold green]",
+        title="MODEL ROUTER UI LAUNCHER",
+        border_style="cyan"
+    ))
+    uvicorn.run("main:app", host=host, port=port, reload=False, app_dir=os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
+
+
+if __name__ == "__main__":
+    app()
+

app/config/settings.py

@@ -0,0 +1,43 @@
+from functools import lru_cache
+from typing import Optional
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    APP_ENV: str = "development"
+    DEBUG: bool = True
+    PORT: int = 8000
+    HOST: str = "0.0.0.0"
+
+    DATABASE_URL: str = "sqlite+aiosqlite:///./model_router.db"
+    ROUTER_ANALYZER: str = "rules"  # "rules" or "llm"
+    DEFAULT_ROUTING_POLICY: str = "balanced"
+    BASELINE_MODEL_ID: str = "mock-power"
+
+    DEFAULT_PROVIDER: str = "mock"
+    OLLAMA_BASE_URL: str = "http://localhost:11434"
+
+    # External Provider Keys (optional)
+    OPENAI_API_KEY: Optional[str] = None
+    ANTHROPIC_API_KEY: Optional[str] = None
+    GEMINI_API_KEY: Optional[str] = None
+
+    # Budgets
+    DAILY_BUDGET: float = 10.00
+    MONTHLY_BUDGET: float = 100.00
+    PER_REQUEST_BUDGET: float = 1.00
+
+    # Execution / Reliability
+    MAX_RETRIES: int = 2
+    PROVIDER_TIMEOUT_SECONDS: float = 30.0
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()

app/experiments/service.py

@@ -0,0 +1,85 @@
+import uuid
+import datetime
+from typing import Dict, Any, List
+from sqlalchemy import select, func
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.storage.models import ExperimentRecord, ExperimentRunRecord
+
+
+async def log_experiment_run(
+    session: AsyncSession,
+    experiment_id: str,
+    request_id: str,
+    policy: str,
+    model: str,
+    cost: float,
+    latency_ms: float,
+):
+    run = ExperimentRunRecord(
+        id=str(uuid.uuid4()),
+        experiment_id=experiment_id,
+        request_id=request_id,
+        assigned_policy=policy,
+        selected_model=model,
+        cost=cost,
+        latency_ms=latency_ms,
+    )
+    session.add(run)
+    
+    # Increment sample count
+    res = await session.execute(select(ExperimentRecord).filter_by(id=experiment_id))
+    exp = res.scalar_one_or_none()
+    if exp:
+        exp.sample_count += 1
+    await session.commit()
+
+
+async def get_experiment_summary(
+    session: AsyncSession,
+    experiment_id: str,
+) -> Dict[str, Any]:
+    res = await session.execute(select(ExperimentRecord).filter_by(id=experiment_id))
+    exp = res.scalar_one_or_none()
+    if not exp:
+        return {}
+
+    # Calculate metrics for Policy A vs Policy B
+    runs_a = await session.execute(
+        select(
+            func.count(ExperimentRunRecord.id),
+            func.avg(ExperimentRunRecord.cost),
+            func.avg(ExperimentRunRecord.latency_ms),
+        ).filter_by(experiment_id=experiment_id, assigned_policy=exp.policy_a)
+    )
+    count_a, cost_a, lat_a = runs_a.one()
+
+    runs_b = await session.execute(
+        select(
+            func.count(ExperimentRunRecord.id),
+            func.avg(ExperimentRunRecord.cost),
+            func.avg(ExperimentRunRecord.latency_ms),
+        ).filter_by(experiment_id=experiment_id, assigned_policy=exp.policy_b)
+    )
+    count_b, cost_b, lat_b = runs_b.one()
+
+    return {
+        "id": exp.id,
+        "name": exp.name,
+        "description": exp.description,
+        "policy_a": exp.policy_a,
+        "policy_b": exp.policy_b,
+        "status": exp.status,
+        "total_samples": exp.sample_count,
+        "results": {
+            exp.policy_a: {
+                "sample_count": count_a or 0,
+                "avg_cost_usd": round(cost_a or 0.0, 6),
+                "avg_latency_ms": round(lat_a or 0.0, 1),
+            },
+            exp.policy_b: {
+                "sample_count": count_b or 0,
+                "avg_cost_usd": round(cost_b or 0.0, 6),
+                "avg_latency_ms": round(lat_b or 0.0, 1),
+            },
+        },
+    }

app/fallback/handler.py

@@ -0,0 +1,105 @@
+import time
+import asyncio
+from typing import List, Optional, Tuple, Dict, Any
+from app.models.schemas import ProviderResponse, ModelMetadata
+from app.providers.registry import provider_registry
+from app.config.settings import get_settings
+
+settings = get_settings()
+
+RETRYABLE_ERRORS = [
+    "timeout",
+    "connection error",
+    "rate limit",
+    "429",
+    "503",
+    "service unavailable",
+    "econnreset",
+]
+
+
+def is_retryable(error_str: Optional[str]) -> bool:
+    if not error_str:
+        return False
+    low = error_str.lower()
+    return any(keyword in low for keyword in RETRYABLE_ERRORS)
+
+
+async def execute_with_fallback(
+    prompt: str,
+    selected_model_id: str,
+    selected_provider_id: str,
+    all_models: List[ModelMetadata],
+    system_prompt: Optional[str] = None,
+    temperature: float = 0.7,
+    max_retries: int = 1,
+) -> Tuple[ProviderResponse, bool, Optional[str], Optional[str]]:
+    """
+    Executes model generation with configurable retries and fallback hierarchy.
+    Returns: (ProviderResponse, fallback_used, original_model, fallback_reason)
+    """
+    current_model_id = selected_model_id
+    current_provider_id = selected_provider_id
+    fallback_used = False
+    original_model = selected_model_id
+    fallback_reason = None
+
+    # Step 1: Attempt primary model with retries
+    provider = provider_registry.get_provider(current_provider_id)
+    if not provider:
+        provider = provider_registry.get_provider("mock")
+        current_provider_id = "mock"
+        current_model_id = "mock-balanced"
+        fallback_used = True
+        fallback_reason = f"Provider '{selected_provider_id}' is not loaded. Fell back to Mock."
+
+    for attempt in range(max_retries + 1):
+        resp = await provider.generate(
+            prompt=prompt,
+            model_id=current_model_id,
+            system_prompt=system_prompt,
+            temperature=temperature,
+        )
+
+        if not resp.error and resp.finish_reason != "error":
+            return resp, fallback_used, original_model if fallback_used else None, fallback_reason
+
+        # If non-retryable error or last attempt, prepare for fallback
+        if not is_retryable(resp.error) or attempt == max_retries:
+            fallback_reason = resp.error or "Unknown primary model execution error."
+            break
+
+        await asyncio.sleep(0.5 * (attempt + 1))
+
+    # Step 2: Determine Fallback Candidate
+    fallback_used = True
+    # Priority: Mock model of same or balanced tier, or active local Ollama
+    candidate_fallbacks = [
+        m for m in all_models
+        if m.id != selected_model_id and m.is_active and (m.provider == "mock" or m.type == "LOCAL")
+    ]
+    if not candidate_fallbacks:
+        candidate_fallbacks = [m for m in all_models if m.id != selected_model_id and m.is_active]
+
+    fallback_target = candidate_fallbacks[0] if candidate_fallbacks else None
+
+    if fallback_target:
+        fb_provider = provider_registry.get_provider(fallback_target.provider) or provider_registry.get_provider("mock")
+        fb_resp = await fb_provider.generate(
+            prompt=prompt,
+            model_id=fallback_target.id,
+            system_prompt=system_prompt,
+            temperature=temperature,
+        )
+        if not fb_resp.error:
+            return fb_resp, True, original_model, f"Primary model failed: {fallback_reason} -> Fallback to {fallback_target.id}"
+
+    # Step 3: Emergency Hard Mock fallback
+    emergency_mock = provider_registry.get_provider("mock")
+    emergency_resp = await emergency_mock.generate(
+        prompt=prompt,
+        model_id="mock-balanced",
+        system_prompt=system_prompt,
+        temperature=temperature,
+    )
+    return emergency_resp, True, original_model, f"Emergency fallback triggered due to: {fallback_reason}"

app/models/schemas.py

@@ -0,0 +1,127 @@
+from enum import Enum
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class TaskType(str, Enum):
+    GENERAL_QA = "GENERAL_QA"
+    CODING = "CODING"
+    DEBUGGING = "DEBUGGING"
+    REASONING = "REASONING"
+    SUMMARIZATION = "SUMMARIZATION"
+    EXTRACTION = "EXTRACTION"
+    WRITING = "WRITING"
+    TRANSLATION = "TRANSLATION"
+    ANALYSIS = "ANALYSIS"
+    MATH = "MATH"
+    LONG_CONTEXT = "LONG_CONTEXT"
+    CREATIVE = "CREATIVE"
+
+
+class PriorityLevel(str, Enum):
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+
+
+class ModelTier(str, Enum):
+    FAST = "FAST"
+    BALANCED = "BALANCED"
+    POWER = "POWER"
+
+
+class ProviderType(str, Enum):
+    MOCK = "mock"
+    OLLAMA = "ollama"
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GEMINI = "gemini"
+    CUSTOM = "custom"
+
+
+class RequestAnalysis(BaseModel):
+    task_type: TaskType = Field(default=TaskType.GENERAL_QA)
+    complexity: float = Field(default=0.5, ge=0.0, le=1.0)
+    complexity_label: PriorityLevel = Field(default=PriorityLevel.MEDIUM)
+    reasoning_required: bool = Field(default=False)
+    coding_required: bool = Field(default=False)
+    vision_required: bool = Field(default=False)
+    tools_required: bool = Field(default=False)
+    context_size: int = Field(default=0)  # in estimated tokens / characters
+    latency_priority: PriorityLevel = Field(default=PriorityLevel.MEDIUM)
+    cost_sensitivity: PriorityLevel = Field(default=PriorityLevel.MEDIUM)
+    quality_requirement: PriorityLevel = Field(default=PriorityLevel.MEDIUM)
+    keywords_detected: List[str] = Field(default_factory=list)
+    analyzer_used: str = Field(default="rules")
+
+
+class ModelMetadata(BaseModel):
+    id: str
+    name: str
+    provider: str
+    type: str = "LOCAL"  # LOCAL, CLOUD, MOCK
+    tier: ModelTier = ModelTier.BALANCED
+    context_window: int = 8192
+    
+    supports_coding: bool = False
+    supports_reasoning: bool = False
+    supports_vision: bool = False
+    supports_tools: bool = False
+    
+    quality_score: float = 0.75  # 0.0 - 1.0
+    speed_score: float = 0.75    # 0.0 - 1.0
+    reliability_score: float = 0.95
+    
+    cost_per_input_token: float = 0.0
+    cost_per_output_token: float = 0.0
+    availability: str = "AVAILABLE"
+    is_active: bool = True
+
+
+class CandidateScore(BaseModel):
+    model_id: str
+    model_name: str
+    provider: str
+    tier: str
+    overall_score: float  # 0 - 100
+    quality_component: float
+    cost_component: float
+    speed_component: float
+    capability_component: float
+    reliability_component: float
+    estimated_latency_ms: float
+    estimated_cost_usd: float
+    eligible: bool = True
+    rejection_reason: Optional[str] = None
+
+
+class RoutingDecision(BaseModel):
+    decision_id: str
+    request_id: str
+    selected_model: str
+    selected_model_name: str
+    provider: str
+    tier: str
+    confidence: float
+    policy_used: str
+    reasons: List[str]
+    candidate_scores: List[CandidateScore]
+    rejected_candidates: Dict[str, str] = Field(default_factory=dict)
+    estimated_cost_usd: float
+    estimated_latency_ms: float
+    rule_applied: Optional[str] = None
+    timestamp: str
+
+
+class ProviderResponse(BaseModel):
+    content: str
+    finish_reason: str = "stop"
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    provider_latency_ms: float = 0.0
+    time_to_first_token_ms: Optional[float] = None
+    is_mock: bool = False
+    model: str = ""
+    provider: str = ""
+    error: Optional[str] = None

app/observability/events.py

@@ -0,0 +1,43 @@
+import json
+import logging
+from typing import Dict, Any, Optional
+import datetime
+
+logger = logging.getLogger("model_router.observability")
+logger.setLevel(logging.INFO)
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('{"time":"%(asctime)s", "level":"%(levelname)s", "event":%(message)s}')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+
+def log_router_event(
+    event_name: str,
+    request_id: str,
+    model: Optional[str] = None,
+    provider: Optional[str] = None,
+    duration_ms: Optional[float] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+):
+    """
+    Structured event logger for model router pipeline.
+    Redacts sensitive credentials automatically.
+    """
+    payload = {
+        "event": event_name,
+        "request_id": request_id,
+        "timestamp": datetime.datetime.utcnow().isoformat(),
+        "model": model,
+        "provider": provider,
+        "duration_ms": duration_ms,
+    }
+    if metadata:
+        # Sanitize any key that looks like an API token
+        safe_meta = {
+            k: ("[REDACTED]" if "key" in k.lower() or "secret" in k.lower() or "token" in k.lower() and "count" not in k.lower() else v)
+            for k, v in metadata.items()
+        }
+        payload["metadata"] = safe_meta
+
+    logger.info(json.dumps(payload))