router-maestro 0.1.2__tar.gz → 0.1.3__tar.gz

{router_maestro-0.1.2 → router_maestro-0.1.3}/PKG-INFO

@@ -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 → router_maestro-0.1.3}/README.md

@@ -15,7 +15,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
 
@@ -23,6 +22,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)
@@ -33,20 +37,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
@@ -134,6 +154,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
@@ -177,8 +218,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
 
@@ -234,7 +273,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
 
@@ -323,7 +361,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 → router_maestro-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "router-maestro"
-version = "0.1.2"
+version = "0.1.3"
 description = "Multi-model routing and load balancing system with OpenAI-compatible API"
 readme = "README.md"
 license = "MIT"

{router_maestro-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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-0.1.2 → router_maestro-0.1.3}/src/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 → router_maestro-0.1.3}/uv.lock

@@ -925,7 +925,7 @@ wheels = [
 
 [[package]]
 name = "router-maestro"
-version = "0.1.1"
+version = "0.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },

router_maestro-0.1.2/src/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-0.1.2/src/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",
-]