router-maestro 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

router_maestro/__init__.py

@@ -1,3 +1,3 @@
 """Router-Maestro: Multi-model routing and load balancing system."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

router_maestro/cli/client.py

@@ -241,38 +241,6 @@ class AdminClient:
             self._handle_connection_error(e)
             return False
 
-    async def get_stats(
-        self, days: int = 7, provider: str | None = None, model: str | None = None
-    ) -> dict:
-        """Get usage statistics.
-
-        Args:
-            days: Number of days to query
-            provider: Optional provider filter
-            model: Optional model filter
-
-        Returns:
-            Stats dict with total_requests, total_tokens, by_provider, by_model
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                params: dict = {"days": days}
-                if provider:
-                    params["provider"] = provider
-                if model:
-                    params["model"] = model
-
-                response = await client.get(
-                    f"{self.endpoint}/api/admin/stats",
-                    headers=self._get_headers(),
-                    params=params,
-                )
-                response.raise_for_status()
-                return response.json()
-        except httpx.HTTPError as e:
-            self._handle_connection_error(e)
-            return {}
-
     async def test_connection(self) -> dict:
         """Test connection to the server.
 

router_maestro/cli/main.py

@@ -14,14 +14,13 @@ app = typer.Typer(
 console = Console()
 
 # Import and register sub-commands
-from router_maestro.cli import auth, config, context, model, server, stats  # noqa: E402
+from router_maestro.cli import auth, config, context, model, server  # noqa: E402
 
 app.add_typer(server.app, name="server", help="Manage the API server")
 app.add_typer(auth.app, name="auth", help="Manage authentication for providers")
 app.add_typer(model.app, name="model", help="Manage models and priorities")
 app.add_typer(context.app, name="context", help="Manage deployment contexts")
 app.add_typer(config.app, name="config", help="Manage configuration")
-app.command(name="stats")(stats.stats)
 
 
 @app.callback(invoke_without_command=True)

router_maestro/cli/server.py

@@ -98,7 +98,7 @@ def status() -> None:
 
     try:
         data = asyncio.run(client.test_connection())
-        console.print(f"[green]Server is running[/green]")
+        console.print("[green]Server is running[/green]")
         console.print(f"  Version: {data.get('version', 'unknown')}")
         console.print(f"  Status: {data.get('status', 'unknown')}")
     except Exception as e:

router_maestro/config/__init__.py

@@ -8,7 +8,6 @@ from router_maestro.config.paths import (
     PRIORITIES_FILE,
     PROVIDERS_FILE,
     SERVER_CONFIG_FILE,
-    STATS_DB_FILE,
     get_config_dir,
     get_data_dir,
 )
@@ -45,7 +44,6 @@ __all__ = [
     "PROVIDERS_FILE",
     "PRIORITIES_FILE",
     "CONTEXTS_FILE",
-    "STATS_DB_FILE",
     "LOG_FILE",
     # Provider models
     "ModelConfig",

router_maestro/config/paths.py

@@ -46,5 +46,4 @@ SERVER_CONFIG_FILE = get_data_dir() / "server.json"
 PROVIDERS_FILE = get_config_dir() / "providers.json"
 PRIORITIES_FILE = get_config_dir() / "priorities.json"
 CONTEXTS_FILE = get_config_dir() / "contexts.json"
-STATS_DB_FILE = get_data_dir() / "stats.db"
 LOG_FILE = get_data_dir() / "router-maestro.log"

router_maestro/server/routes/admin.py

@@ -1,9 +1,7 @@
 """Admin API routes for remote management."""
 
-from typing import Annotated
-
 import httpx
-from fastapi import APIRouter, BackgroundTasks, HTTPException, Query
+from fastapi import APIRouter, BackgroundTasks, HTTPException
 
 from router_maestro.auth import AuthManager, AuthType
 from router_maestro.auth.github_oauth import (
@@ -29,9 +27,7 @@ from router_maestro.server.schemas.admin import (
     OAuthStatusResponse,
     PrioritiesResponse,
     PrioritiesUpdateRequest,
-    StatsResponse,
 )
-from router_maestro.stats import StatsStorage
 
 router = APIRouter(prefix="/api/admin", tags=["admin"])
 
@@ -288,71 +284,3 @@ async def update_priorities(request: PrioritiesUpdateRequest) -> PrioritiesRespo
         priorities=config.priorities,
         fallback=config.fallback.model_dump(),
     )
-
-
-# ============================================================================
-# Stats endpoints
-# ============================================================================
-
-
-@router.get("/stats", response_model=StatsResponse)
-async def get_stats(
-    days: Annotated[int, Query(ge=1, le=365)] = 7,
-    provider: str | None = None,
-    model: str | None = None,
-) -> StatsResponse:
-    """Get usage statistics."""
-    storage = StatsStorage()
-
-    # Get total stats
-    total = storage.get_total_usage(days=days)
-
-    # Get stats by model (which includes provider info)
-    by_model_raw = storage.get_usage_by_model(days=days)
-
-    # Aggregate by provider
-    by_provider: dict[str, dict] = {}
-    by_model: dict[str, dict] = {}
-
-    for record in by_model_raw:
-        provider_name = record["provider"]
-        model_name = record["model"]
-        model_key = f"{provider_name}/{model_name}"
-
-        # Filter if requested
-        if provider and provider_name != provider:
-            continue
-        if model and model_name != model:
-            continue
-
-        # Aggregate by provider
-        if provider_name not in by_provider:
-            by_provider[provider_name] = {
-                "total_tokens": 0,
-                "prompt_tokens": 0,
-                "completion_tokens": 0,
-                "request_count": 0,
-            }
-
-        by_provider[provider_name]["total_tokens"] += record.get("total_tokens", 0) or 0
-        by_provider[provider_name]["prompt_tokens"] += record.get("prompt_tokens", 0) or 0
-        by_provider[provider_name]["completion_tokens"] += record.get("completion_tokens", 0) or 0
-        by_provider[provider_name]["request_count"] += record.get("request_count", 0) or 0
-
-        # Store by model
-        by_model[model_key] = {
-            "total_tokens": record.get("total_tokens", 0) or 0,
-            "prompt_tokens": record.get("prompt_tokens", 0) or 0,
-            "completion_tokens": record.get("completion_tokens", 0) or 0,
-            "request_count": record.get("request_count", 0) or 0,
-            "avg_latency_ms": record.get("avg_latency_ms", 0) or 0,
-        }
-
-    return StatsResponse(
-        total_requests=total.get("request_count", 0) or 0,
-        total_tokens=total.get("total_tokens", 0) or 0,
-        prompt_tokens=total.get("prompt_tokens", 0) or 0,
-        completion_tokens=total.get("completion_tokens", 0) or 0,
-        by_provider=by_provider,
-        by_model=by_model,
-    )

router_maestro/server/schemas/__init__.py

@@ -10,8 +10,6 @@ from router_maestro.server.schemas.admin import (
     OAuthStatusResponse,
     PrioritiesResponse,
     PrioritiesUpdateRequest,
-    StatsQuery,
-    StatsResponse,
 )
 from router_maestro.server.schemas.openai import (
     ChatCompletionChoice,
@@ -39,8 +37,6 @@ __all__ = [
     "OAuthStatusResponse",
     "PrioritiesResponse",
     "PrioritiesUpdateRequest",
-    "StatsQuery",
-    "StatsResponse",
     # OpenAI schemas
     "ChatCompletionChoice",
     "ChatCompletionChunk",

router_maestro/server/schemas/admin.py

@@ -66,22 +66,3 @@ class PrioritiesUpdateRequest(BaseModel):
 
     priorities: list[str] = Field(..., description="New priority list")
     fallback: dict | None = Field(default=None, description="Optional fallback config update")
-
-
-class StatsQuery(BaseModel):
-    """Query parameters for stats."""
-
-    days: int = Field(default=7, ge=1, le=365, description="Number of days to query")
-    provider: str | None = Field(default=None, description="Filter by provider")
-    model: str | None = Field(default=None, description="Filter by model")
-
-
-class StatsResponse(BaseModel):
-    """Response for usage statistics."""
-
-    total_requests: int = Field(default=0)
-    total_tokens: int = Field(default=0)
-    prompt_tokens: int = Field(default=0)
-    completion_tokens: int = Field(default=0)
-    by_provider: dict[str, dict] = Field(default_factory=dict)
-    by_model: dict[str, dict] = Field(default_factory=dict)

{router_maestro-0.1.2.dist-info → router_maestro-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: router-maestro
-Version: 0.1.2
+Version: 0.1.3
 Summary: Multi-model routing and load balancing system with OpenAI-compatible API
 Author-email: Kanwen Li <likanwen@icloud.com>
 License-Expression: MIT
@@ -52,7 +52,6 @@ Router-Maestro acts as a proxy that gives you access to models from multiple pro
 - **Dual API compatibility**: Both OpenAI (`/v1/...`) and Anthropic (`/v1/messages`) API formats
 - **Cross-provider translation**: Seamlessly route OpenAI requests to Anthropic providers and vice versa
 - **Configuration hot-reload**: Auto-reload config files every 5 minutes without server restart
-- **Usage tracking**: Token usage statistics with heatmap visualization
 - **CLI management**: Full command-line interface for configuration and server control
 - **Docker ready**: Production-ready Docker images with Traefik integration
 
@@ -60,6 +59,11 @@ Router-Maestro acts as a proxy that gives you access to models from multiple pro
 
 - [Quick Start](#quick-start)
 - [Core Concepts](#core-concepts)
+  - [Model Identification](#model-identification)
+  - [Auto-Routing](#auto-routing)
+  - [Priority & Fallback](#priority--fallback)
+  - [Cross-Provider Translation](#cross-provider-translation)
+  - [Contexts](#contexts)
 - [CLI Reference](#cli-reference)
 - [API Reference](#api-reference)
 - [Configuration](#configuration)
@@ -70,20 +74,36 @@ Router-Maestro acts as a proxy that gives you access to models from multiple pro
 
 Get up and running in 4 steps:
 
-### 1. Install
+### 1. Start the Server
+
+#### Docker (recommended)
 
 ```bash
-pip install router-maestro
-# or
-uv pip install router-maestro
+docker run -d -p 8080:8080 \
+  -v ~/.local/share/router-maestro:/home/maestro/.local/share/router-maestro \
+  -v ~/.config/router-maestro:/home/maestro/.config/router-maestro \
+  likanwen/router-maestro:latest
 ```
 
-### 2. Start the Server
+#### Install locally
 
 ```bash
+pip install router-maestro
 router-maestro server start --port 8080
 ```
 
+### 2. Set Context (for Docker or Remote)
+
+When running via Docker in remote VPS, set up a context to communicate with the containerized server:
+
+```bash
+pip install router-maestro  # Install CLI locally
+router-maestro context add docker --endpoint http://localhost:8080
+router-maestro context set docker
+```
+
+> **What's a context?** A context is a named connection profile (endpoint + API key) that lets you manage local or remote Router-Maestro servers. See [Contexts](#contexts) for details.
+
 ### 3. Authenticate with GitHub Copilot
 
 ```bash
@@ -171,6 +191,27 @@ POST /v1/messages  {"model": "openai/gpt-4o", ...}
 POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
 ```
 
+### Contexts
+
+A **context** is a named connection profile that stores an endpoint URL and API key. Contexts let you manage multiple Router-Maestro deployments from a single CLI.
+
+| Context | Use Case |
+|---------|----------|
+| `local` | Default context for `router-maestro server start` |
+| `docker` | Connect to a local Docker container |
+| `my-vps` | Connect to a remote VPS deployment |
+
+```bash
+# Add a context
+router-maestro context add my-vps --endpoint https://api.example.com --api-key xxx
+
+# Switch contexts
+router-maestro context set my-vps
+
+# All CLI commands now target the remote server
+router-maestro model list
+```
+
 ## CLI Reference
 
 ### Server
@@ -214,8 +255,6 @@ POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
 | Command | Description |
 |---------|-------------|
 | `config claude-code` | Generate Claude Code settings |
-| `stats --days 7` | Show usage statistics |
-| `stats --days 30 --heatmap` | Show heatmap visualization |
 
 ## API Reference
 
@@ -271,7 +310,6 @@ Following XDG Base Directory specification:
 | **Data** | `~/.local/share/router-maestro/` | |
 | | `auth.json` | OAuth tokens |
 | | `server.json` | Server state |
-| | `stats.db` | Usage statistics |
 
 ### Custom Providers
 
@@ -360,7 +398,6 @@ router-maestro context set my-vps
 
 # Now all commands target the VPS
 router-maestro model list
-router-maestro stats --days 7
 ```
 
 ### HTTPS with Traefik

{router_maestro-0.1.2.dist-info → router_maestro-0.1.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-router_maestro/__init__.py,sha256=DjSxTt-117MUK3rqehh5MME5nt25J3uPF88_sJGhvBk,92
+router_maestro/__init__.py,sha256=uL361mf7XE2DqHpdJ9tIuNVF8iku3OIPbWlNADxwL5s,92
 router_maestro/__main__.py,sha256=cUHr8B7JBiv5HhnN6l2iayDkGSBpI5Kf4I3jv9I_I3o,121
 router_maestro/auth/__init__.py,sha256=0JgD1w2gtGSkj809kgSKQanYYkncg6eF-hHoz-jQPgo,353
 router_maestro/auth/github_oauth.py,sha256=acQlAA2Zh6c8KQYdzXbC4ww0EJ41AgvbI5ixpFuNoRg,5060
@@ -6,16 +6,15 @@ router_maestro/auth/manager.py,sha256=OQjdofmjVndTQQIrAU7O-hJAL-w_ijYRU09fZNU8E3
 router_maestro/auth/storage.py,sha256=TCLxgQ1lWcWD4xJXJzx5OMpvuAun_LSRItK0zhR6H0Y,2755
 router_maestro/cli/__init__.py,sha256=yIAshaHpLL0WrDFmRpoMRM2EUe75x0wmM5NlGW3C89s,37
 router_maestro/cli/auth.py,sha256=eq5LBUohbMnHS4dZeyvq4OQAjzdrJ-StP2FGuUhkKa0,5940
-router_maestro/cli/client.py,sha256=f1Q4vuS0N7Vfmy1LVavVcTpsKEprjonX4EPVH4SG-zo,10448
+router_maestro/cli/client.py,sha256=mRzpsA_Dxn-Xq7W1_t6EiyddMI0a3cvuTL6-2JuV4mE,9383
 router_maestro/cli/config.py,sha256=lVmMlUASUynbqOQawuQQhi8C3h2OvGScZvaeIArZ2ns,4662
 router_maestro/cli/context.py,sha256=EPbT7fReIW17veU76CSAcv8QjzMsCIPm1QDBlGsV8fQ,4549
-router_maestro/cli/main.py,sha256=L08B23nM-DCC_wgUAk7Dt6TZmYY03t2pbo1Rh2Bzugc,1360
+router_maestro/cli/main.py,sha256=5yiK4Q149goSB2KKzgMuF5EpcC8FBzOUCkEt8wY5NAU,1314
 router_maestro/cli/model.py,sha256=2IG3IpQWh8Ejdv5Htcgr90O2v2UAa80TU15oOniPdvk,9054
-router_maestro/cli/server.py,sha256=iOEOuug8MvPtY5vCL8KubOkHNt35H6R1nI73dStI7Wc,3697
-router_maestro/cli/stats.py,sha256=MPRMNbGbXDnb1tIn_jyyJxoHEHLEN1vANLMj1cImkeg,2746
-router_maestro/config/__init__.py,sha256=rATq3PIA8vKLpunsCLeCA7GbKjqyzBvlBgI7OwM-6FI,1664
+router_maestro/cli/server.py,sha256=k2OOBBDob55jsQ7XmJ1Tk4_aJgrmFCu4rZPbZuMfmPQ,3696
+router_maestro/config/__init__.py,sha256=-eiXX97Kbd5eIJvbpLbtD6Xrh7XmyFGM_485h6uBokc,1624
 router_maestro/config/contexts.py,sha256=ujaH5I3xa3Eg_KlRaF5KlmsACuUqoKqsp1-i1J2kQz4,923
-router_maestro/config/paths.py,sha256=xaAi9LuTFSag7yGJp9oCnrcTpnXcaPTMKU5yAIYkCT8,1617
+router_maestro/config/paths.py,sha256=F-Q37bGOnQq32MNNbUbvm_ZfZp6-Ik9nVmroEnNNVC8,1573
 router_maestro/config/priorities.py,sha256=wEBs6CmLQiw0ehuA-kh7topyac6APopxaR83CpnHhDQ,2669
 router_maestro/config/providers.py,sha256=yMU_DFh4_eQXMT8jGImqwzAPHp0L3fR34gG2r-4Zhnw,1158
 router_maestro/config/server.py,sha256=Mr7Axbo8b1z3OFEe_G8VuO7wvx_pA32-ZBbT4nSRdX0,3049
@@ -35,23 +34,19 @@ router_maestro/server/translation.py,sha256=TrYfIb5M5MAUC4TD5By8X3RONSZ6cV1YS_Jw
 router_maestro/server/middleware/__init__.py,sha256=PhtP2E04wApnOUBLE76mrOa0sSHp7reHmIl7PaCAylY,187
 router_maestro/server/middleware/auth.py,sha256=Ak3k5cC8m4qPGUIheuOB--QiFvs6GIAcTRJqtCGCjAA,2018
 router_maestro/server/routes/__init__.py,sha256=eGEpNCnSRVQC1pFL7_evDmZfkMrviuI-n1okAS-YnhM,397
-router_maestro/server/routes/admin.py,sha256=5xr0D-9SKuz0T48b7pRs9hueHPHTN-WlsBq5r_VCb2s,11500
+router_maestro/server/routes/admin.py,sha256=oub4hDrYaytuorXkJzmz0YZ4Z2rcyNuwKcK_4IGvcDY,8942
 router_maestro/server/routes/anthropic.py,sha256=T5-rHBPDyPxP4Cs0yzm7Kvvn-zgV6jspnZdoSVDeH2w,8041
 router_maestro/server/routes/chat.py,sha256=vyYX1ILhgAb9HYD87h1U3c5btpplqkTaejA81pWg4Oo,4752
 router_maestro/server/routes/models.py,sha256=PTSXojNFN9j90Bke74ZO6sEsfIc8u_4A69eW1QzFIbc,716
-router_maestro/server/schemas/__init__.py,sha256=rNGneAw3A3MKdCwdbXURjZcWAjQotgwMvJNRXXp0Lwo,1250
-router_maestro/server/schemas/admin.py,sha256=ITmXy9xWhVnZk0T3TSOOMQKgcHzou9fsc8DS30fo2rU,3052
+router_maestro/server/schemas/__init__.py,sha256=VmJZoTMLb-bF33m79urhbejVdLfjDGMqCJP5QvWbHsU,1176
+router_maestro/server/schemas/admin.py,sha256=DuUojkCcq9n8pDhWG6L0SpzQooh91lmHjCRzgZ4AMwk,2369
 router_maestro/server/schemas/anthropic.py,sha256=hNl6rZ7AX-HdLxtsd0cWpZjpIyK1AkEBcuiQpZQqPYc,6136
 router_maestro/server/schemas/openai.py,sha256=s2487RYIn1h-CIaUpLue9BScDaTsafbVg5yc-kKhfME,2141
-router_maestro/stats/__init__.py,sha256=igFtk7xFgvxk_AQsbQlzz8KBubvrmgnNfe-BS9ufuGM,403
-router_maestro/stats/heatmap.py,sha256=G_yerQcLOdP6cND-KTlhXBBNaRdcOBxy6HzGyUlDj6A,5255
-router_maestro/stats/storage.py,sha256=WsFrhmgs9eWKcAPRGDrhT4Ft1-Uzuiz3Q0fYNfgVvQs,7676
-router_maestro/stats/tracker.py,sha256=iutAfdm6JL2rUTBLUnLbUiSaBEAxkzXmi8d5iEllCcI,1984
 router_maestro/utils/__init__.py,sha256=oSQyV--FueMPggRfjWWVnAKtjkcZWFOm9hCTymu0oZU,409
 router_maestro/utils/logging.py,sha256=gJWoRYibAxCWn4VmTmnrwpBRzQ7Uu5YIEk5zDiF9X_k,2393
 router_maestro/utils/tokens.py,sha256=t2E5BrrE5X3VCgw-rYFMkic7heJ0huj9rrOXAIlKq8o,1330
-router_maestro-0.1.2.dist-info/METADATA,sha256=1qwn774LuxcaBm_iiszi5ZcPTS_F7-mRQWi2VgD-5m0,10033
-router_maestro-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-router_maestro-0.1.2.dist-info/entry_points.txt,sha256=zoFUxxvNcFe0nTgpRbIdygIDEOla3KbvW6HbOCOlgv4,63
-router_maestro-0.1.2.dist-info/licenses/LICENSE,sha256=Ea86BSGu7_tpLAuzif_JmM9zjMoKQEf95VVF9sZw3Jo,1084
-router_maestro-0.1.2.dist-info/RECORD,,
+router_maestro-0.1.3.dist-info/METADATA,sha256=vk_n3Hqc8v9d6uBHNcZgjlA5oSvfcLZSwhD2sMXai1o,11343
+router_maestro-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+router_maestro-0.1.3.dist-info/entry_points.txt,sha256=zoFUxxvNcFe0nTgpRbIdygIDEOla3KbvW6HbOCOlgv4,63
+router_maestro-0.1.3.dist-info/licenses/LICENSE,sha256=Ea86BSGu7_tpLAuzif_JmM9zjMoKQEf95VVF9sZw3Jo,1084
+router_maestro-0.1.3.dist-info/RECORD,,

router_maestro/cli/stats.py

@@ -1,76 +0,0 @@
-"""Token usage statistics command."""
-
-import asyncio
-
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from router_maestro.cli.client import AdminClientError, get_admin_client
-
-console = Console()
-
-
-def stats(
-    days: int = typer.Option(7, "--days", "-d", help="Number of days to show"),
-    provider: str = typer.Option(None, "--provider", "-p", help="Filter by provider"),
-    model: str = typer.Option(None, "--model", "-m", help="Filter by model"),
-) -> None:
-    """Show token usage statistics."""
-    client = get_admin_client()
-
-    try:
-        data = asyncio.run(client.get_stats(days=days, provider=provider, model=model))
-    except AdminClientError as e:
-        console.print(f"[red]{e}[/red]")
-        raise typer.Exit(1)
-    except Exception as e:
-        console.print(f"[red]Failed to get stats: {e}[/red]")
-        raise typer.Exit(1)
-
-    if data.get("total_requests", 0) == 0:
-        console.print("[dim]No usage data available.[/dim]")
-        return
-
-    # Summary table
-    console.print(f"\n[bold]Token Usage Summary (Last {days} Days)[/bold]\n")
-
-    summary_table = Table(show_header=False, box=None)
-    summary_table.add_column("Metric", style="cyan")
-    summary_table.add_column("Value", style="green", justify="right")
-
-    summary_table.add_row("Total Requests", f"{data.get('total_requests', 0):,}")
-    summary_table.add_row("Total Tokens", f"{data.get('total_tokens', 0):,}")
-    summary_table.add_row("  Prompt", f"{data.get('prompt_tokens', 0):,}")
-    summary_table.add_row("  Completion", f"{data.get('completion_tokens', 0):,}")
-
-    console.print(summary_table)
-
-    # By model table
-    by_model = data.get("by_model", {})
-    if by_model:
-        console.print("\n[bold]Usage by Model[/bold]\n")
-
-        model_table = Table()
-        model_table.add_column("Model", style="cyan")
-        model_table.add_column("Provider", style="magenta")
-        model_table.add_column("Requests", justify="right")
-        model_table.add_column("Total Tokens", justify="right", style="green")
-        model_table.add_column("Avg Latency", justify="right")
-
-        for model_key, record in by_model.items():
-            parts = model_key.split("/", 1)
-            provider_name = parts[0] if len(parts) > 1 else "-"
-            model_name = parts[1] if len(parts) > 1 else model_key
-
-            avg_latency = record.get("avg_latency_ms")
-            latency = f"{avg_latency:.0f} ms" if avg_latency else "-"
-            model_table.add_row(
-                model_name,
-                provider_name,
-                f"{record.get('request_count', 0):,}",
-                f"{record.get('total_tokens', 0):,}",
-                latency,
-            )
-
-        console.print(model_table)

router_maestro/stats/__init__.py

@@ -1,14 +0,0 @@
-"""Stats module for router-maestro."""
-
-from router_maestro.stats.heatmap import display_stats_summary, generate_heatmap
-from router_maestro.stats.storage import StatsStorage, UsageRecord
-from router_maestro.stats.tracker import RequestTimer, UsageTracker
-
-__all__ = [
-    "StatsStorage",
-    "UsageRecord",
-    "UsageTracker",
-    "RequestTimer",
-    "generate_heatmap",
-    "display_stats_summary",
-]

router_maestro/stats/heatmap.py

@@ -1,154 +0,0 @@
-"""Terminal heatmap generation for token usage."""
-
-from datetime import datetime, timedelta
-
-import plotext as plt
-from rich.console import Console
-from rich.table import Table
-
-from router_maestro.stats.storage import StatsStorage
-
-console = Console()
-
-
-def generate_heatmap(days: int = 7, provider: str | None = None, model: str | None = None) -> None:
-    """Generate and display a terminal heatmap of token usage.
-
-    Args:
-        days: Number of days to show
-        provider: Filter by provider (optional)
-        model: Filter by model (optional)
-    """
-    storage = StatsStorage()
-    hourly_data = storage.get_usage_by_hour(days=days, provider=provider, model=model)
-
-    if not hourly_data:
-        console.print("[dim]No usage data available for the specified period.[/dim]")
-        return
-
-    # Build a matrix for the heatmap: rows = days, columns = hours
-    # Initialize with zeros
-    today = datetime.now().date()
-    dates = [(today - timedelta(days=i)) for i in range(days - 1, -1, -1)]
-
-    # Create a 2D matrix (days x 24 hours)
-    matrix = [[0 for _ in range(24)] for _ in range(len(dates))]
-    date_to_idx = {d: i for i, d in enumerate(dates)}
-
-    for record in hourly_data:
-        date = datetime.fromisoformat(record["date"]).date()
-        hour = record["hour"]
-        tokens = record["total_tokens"]
-
-        if date in date_to_idx:
-            matrix[date_to_idx[date]][hour] = tokens
-
-    # Display using plotext
-    plt.clear_figure()
-    plt.title(f"Token Usage Heatmap (Last {days} Days)")
-
-    # Create a simple bar chart by day since plotext doesn't have heatmap
-    daily_data = storage.get_usage_by_day(days=days, provider=provider, model=model)
-
-    if daily_data:
-        dates_str = [record["date"] for record in daily_data]
-        tokens = [record["total_tokens"] for record in daily_data]
-
-        plt.bar(dates_str, tokens)
-        plt.xlabel("Date")
-        plt.ylabel("Total Tokens")
-        plt.show()
-
-    # Also show a text-based heatmap using Rich
-    _display_text_heatmap(dates, matrix)
-
-
-def _display_text_heatmap(dates: list, matrix: list[list[int]]) -> None:
-    """Display a text-based heatmap using Rich.
-
-    Args:
-        dates: List of dates
-        matrix: 2D matrix of token counts (days x hours)
-    """
-    console.print("\n[bold]Hourly Activity Heatmap:[/bold]")
-
-    # Find max value for scaling
-    max_val = max(max(row) for row in matrix) if matrix else 1
-    if max_val == 0:
-        max_val = 1
-
-    # Create intensity characters
-    intensity_chars = " ░▒▓█"
-
-    # Build the heatmap
-    hour_labels = "    " + "".join(f"{h:2d}" for h in range(0, 24, 2))
-    console.print(f"[dim]{hour_labels}[/dim]")
-
-    for i, date in enumerate(dates):
-        row_str = f"{date.strftime('%m/%d')} "
-        for h in range(24):
-            value = matrix[i][h]
-            intensity = int((value / max_val) * (len(intensity_chars) - 1))
-            char = intensity_chars[intensity]
-            row_str += char
-        console.print(row_str)
-
-    # Legend
-    console.print(f"\n[dim]Legend: {' '.join(intensity_chars)} (low to high)[/dim]")
-
-
-def display_stats_summary(days: int = 7) -> None:
-    """Display a summary of token usage statistics.
-
-    Args:
-        days: Number of days to summarize
-    """
-    storage = StatsStorage()
-    total = storage.get_total_usage(days=days)
-    by_model = storage.get_usage_by_model(days=days)
-
-    if not total or total.get("total_tokens") is None:
-        console.print("[dim]No usage data available.[/dim]")
-        return
-
-    # Summary table
-    console.print(f"\n[bold]Token Usage Summary (Last {days} Days)[/bold]\n")
-
-    summary_table = Table(show_header=False, box=None)
-    summary_table.add_column("Metric", style="cyan")
-    summary_table.add_column("Value", style="green", justify="right")
-
-    summary_table.add_row("Total Requests", f"{total.get('request_count', 0):,}")
-    summary_table.add_row("Successful", f"{total.get('success_count', 0):,}")
-    summary_table.add_row("Total Tokens", f"{total.get('total_tokens', 0):,}")
-    summary_table.add_row("  Prompt", f"{total.get('prompt_tokens', 0):,}")
-    summary_table.add_row("  Completion", f"{total.get('completion_tokens', 0):,}")
-
-    if total.get("avg_latency_ms"):
-        summary_table.add_row("Avg Latency", f"{total.get('avg_latency_ms', 0):.0f} ms")
-
-    console.print(summary_table)
-
-    # By model table
-    if by_model:
-        console.print("\n[bold]Usage by Model[/bold]\n")
-
-        model_table = Table()
-        model_table.add_column("Model", style="cyan")
-        model_table.add_column("Provider", style="magenta")
-        model_table.add_column("Requests", justify="right")
-        model_table.add_column("Total Tokens", justify="right", style="green")
-        model_table.add_column("Avg Latency", justify="right")
-
-        for record in by_model:
-            avg_latency = record.get("avg_latency_ms")
-            latency = f"{avg_latency:.0f} ms" if avg_latency else "-"
-            model_table.add_row(
-                record["model"],
-                record["provider"],
-                f"{record['request_count']:,}",
-                f"{record['total_tokens']:,}",
-                latency,
-            )
-
-        console.print(model_table)

router_maestro/stats/storage.py

@@ -1,228 +0,0 @@
-"""SQLite storage for token usage statistics."""
-
-import sqlite3
-from collections.abc import Iterator
-from contextlib import contextmanager
-from datetime import datetime
-from pathlib import Path
-
-from pydantic import BaseModel
-
-from router_maestro.config import STATS_DB_FILE
-
-
-class UsageRecord(BaseModel):
-    """A single token usage record."""
-
-    id: int | None = None
-    timestamp: datetime
-    provider: str
-    model: str
-    prompt_tokens: int
-    completion_tokens: int
-    total_tokens: int
-    success: bool
-    latency_ms: int | None = None
-
-
-class StatsStorage:
-    """SQLite storage for token usage statistics."""
-
-    def __init__(self, db_path: Path = STATS_DB_FILE) -> None:
-        self.db_path = db_path
-        self._init_db()
-
-    def _init_db(self) -> None:
-        """Initialize the database schema."""
-        self.db_path.parent.mkdir(parents=True, exist_ok=True)
-
-        with self._get_connection() as conn:
-            conn.execute("""
-                CREATE TABLE IF NOT EXISTS usage (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    timestamp TEXT NOT NULL,
-                    provider TEXT NOT NULL,
-                    model TEXT NOT NULL,
-                    prompt_tokens INTEGER NOT NULL,
-                    completion_tokens INTEGER NOT NULL,
-                    total_tokens INTEGER NOT NULL,
-                    success INTEGER NOT NULL,
-                    latency_ms INTEGER
-                )
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_usage_timestamp ON usage(timestamp)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_usage_provider ON usage(provider)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_usage_model ON usage(model)
-            """)
-            conn.commit()
-
-    @contextmanager
-    def _get_connection(self) -> Iterator[sqlite3.Connection]:
-        """Get a database connection."""
-        conn = sqlite3.connect(self.db_path)
-        conn.row_factory = sqlite3.Row
-        try:
-            yield conn
-        finally:
-            conn.close()
-
-    def record(self, record: UsageRecord) -> None:
-        """Record a usage event."""
-        with self._get_connection() as conn:
-            conn.execute(
-                """
-                INSERT INTO usage (
-                    timestamp, provider, model,
-                    prompt_tokens, completion_tokens, total_tokens,
-                    success, latency_ms
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    record.timestamp.isoformat(),
-                    record.provider,
-                    record.model,
-                    record.prompt_tokens,
-                    record.completion_tokens,
-                    record.total_tokens,
-                    1 if record.success else 0,
-                    record.latency_ms,
-                ),
-            )
-            conn.commit()
-
-    def get_usage_by_day(
-        self, days: int = 7, provider: str | None = None, model: str | None = None
-    ) -> list[dict]:
-        """Get usage aggregated by day.
-
-        Args:
-            days: Number of days to look back
-            provider: Filter by provider (optional)
-            model: Filter by model (optional)
-
-        Returns:
-            List of dicts with date, total_tokens, request_count
-        """
-        with self._get_connection() as conn:
-            query = """
-                SELECT
-                    DATE(timestamp) as date,
-                    SUM(total_tokens) as total_tokens,
-                    SUM(prompt_tokens) as prompt_tokens,
-                    SUM(completion_tokens) as completion_tokens,
-                    COUNT(*) as request_count,
-                    SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count
-                FROM usage
-                WHERE timestamp >= datetime('now', ?)
-            """
-            params: list = [f"-{days} days"]
-
-            if provider:
-                query += " AND provider = ?"
-                params.append(provider)
-            if model:
-                query += " AND model = ?"
-                params.append(model)
-
-            query += " GROUP BY DATE(timestamp) ORDER BY date"
-
-            cursor = conn.execute(query, params)
-            return [dict(row) for row in cursor.fetchall()]
-
-    def get_usage_by_hour(
-        self, days: int = 7, provider: str | None = None, model: str | None = None
-    ) -> list[dict]:
-        """Get usage aggregated by hour.
-
-        Args:
-            days: Number of days to look back
-            provider: Filter by provider (optional)
-            model: Filter by model (optional)
-
-        Returns:
-            List of dicts with date, hour, total_tokens, request_count
-        """
-        with self._get_connection() as conn:
-            query = """
-                SELECT
-                    DATE(timestamp) as date,
-                    CAST(strftime('%H', timestamp) AS INTEGER) as hour,
-                    SUM(total_tokens) as total_tokens,
-                    COUNT(*) as request_count
-                FROM usage
-                WHERE timestamp >= datetime('now', ?)
-            """
-            params: list = [f"-{days} days"]
-
-            if provider:
-                query += " AND provider = ?"
-                params.append(provider)
-            if model:
-                query += " AND model = ?"
-                params.append(model)
-
-            query += " GROUP BY DATE(timestamp), hour ORDER BY date, hour"
-
-            cursor = conn.execute(query, params)
-            return [dict(row) for row in cursor.fetchall()]
-
-    def get_usage_by_model(self, days: int = 7) -> list[dict]:
-        """Get usage aggregated by model.
-
-        Args:
-            days: Number of days to look back
-
-        Returns:
-            List of dicts with model, provider, total_tokens, request_count
-        """
-        with self._get_connection() as conn:
-            cursor = conn.execute(
-                """
-                SELECT
-                    model,
-                    provider,
-                    SUM(total_tokens) as total_tokens,
-                    SUM(prompt_tokens) as prompt_tokens,
-                    SUM(completion_tokens) as completion_tokens,
-                    COUNT(*) as request_count,
-                    AVG(latency_ms) as avg_latency_ms
-                FROM usage
-                WHERE timestamp >= datetime('now', ?)
-                GROUP BY model, provider
-                ORDER BY total_tokens DESC
-                """,
-                (f"-{days} days",),
-            )
-            return [dict(row) for row in cursor.fetchall()]
-
-    def get_total_usage(self, days: int = 7) -> dict:
-        """Get total usage statistics.
-
-        Args:
-            days: Number of days to look back
-
-        Returns:
-            Dict with total statistics
-        """
-        with self._get_connection() as conn:
-            cursor = conn.execute(
-                """
-                SELECT
-                    SUM(total_tokens) as total_tokens,
-                    SUM(prompt_tokens) as prompt_tokens,
-                    SUM(completion_tokens) as completion_tokens,
-                    COUNT(*) as request_count,
-                    SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count,
-                    AVG(latency_ms) as avg_latency_ms
-                FROM usage
-                WHERE timestamp >= datetime('now', ?)
-                """,
-                (f"-{days} days",),
-            )
-            row = cursor.fetchone()
-            return dict(row) if row else {}

router_maestro/stats/tracker.py

@@ -1,73 +0,0 @@
-"""Token usage tracker."""
-
-import time
-from datetime import datetime
-
-from router_maestro.stats.storage import StatsStorage, UsageRecord
-
-
-class UsageTracker:
-    """Tracks token usage for requests."""
-
-    _instance: "UsageTracker | None" = None
-
-    def __init__(self) -> None:
-        self.storage = StatsStorage()
-
-    @classmethod
-    def get_instance(cls) -> "UsageTracker":
-        """Get the singleton instance."""
-        if cls._instance is None:
-            cls._instance = cls()
-        return cls._instance
-
-    def record(
-        self,
-        provider: str,
-        model: str,
-        prompt_tokens: int,
-        completion_tokens: int,
-        success: bool = True,
-        latency_ms: int | None = None,
-    ) -> None:
-        """Record a usage event.
-
-        Args:
-            provider: Provider name
-            model: Model name
-            prompt_tokens: Number of prompt tokens
-            completion_tokens: Number of completion tokens
-            success: Whether the request was successful
-            latency_ms: Latency in milliseconds
-        """
-        record = UsageRecord(
-            timestamp=datetime.now(),
-            provider=provider,
-            model=model,
-            prompt_tokens=prompt_tokens,
-            completion_tokens=completion_tokens,
-            total_tokens=prompt_tokens + completion_tokens,
-            success=success,
-            latency_ms=latency_ms,
-        )
-        self.storage.record(record)
-
-
-class RequestTimer:
-    """Context manager for timing requests."""
-
-    def __init__(self) -> None:
-        self.start_time: float = 0
-        self.end_time: float = 0
-
-    def __enter__(self) -> "RequestTimer":
-        self.start_time = time.perf_counter()
-        return self
-
-    def __exit__(self, *args) -> None:
-        self.end_time = time.perf_counter()
-
-    @property
-    def elapsed_ms(self) -> int:
-        """Get elapsed time in milliseconds."""
-        return int((self.end_time - self.start_time) * 1000)