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

router_maestro-0.1.4/.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "MD013": false,
+  "MD060": false
+}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: router-maestro
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -112,8 +132,8 @@ router-maestro config claude-code
 
 Models are identified using the format `{provider}/{model-id}`:
 
-| Example | Description |
-|---------|-------------|
+| Example                           | Description                         |
+| --------------------------------- | ----------------------------------- |
 | `github-copilot/gpt-4o` | GPT-4o via GitHub Copilot |
 | `github-copilot/claude-sonnet-4` | Claude Sonnet 4 via GitHub Copilot |
 | `openai/gpt-4-turbo` | GPT-4 Turbo via OpenAI |
@@ -144,8 +164,8 @@ router-maestro model priority list
 
 **Fallback** triggers when a request fails with a retryable error (429, 5xx):
 
-| Strategy | Behavior |
-|----------|----------|
+| Strategy     | Behavior                             |
+| ------------ | ------------------------------------ |
 | `priority` | Try next model in priorities list |
 | `same-model` | Try same model on different provider |
 | `none` | Fail immediately |
@@ -171,29 +191,50 @@ 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
 
-| Command | Description |
-|---------|-------------|
-| `server start --port 8080` | Start the server |
+| Command                    | Description        |
+| -------------------------- | ------------------ |
+| `server start --port 8080` | Start the server   |
 | `server stop` | Stop the server |
 | `server info` | Show server status |
 
 ### Authentication
 
-| Command | Description |
-|---------|-------------|
-| `auth login [provider]` | Authenticate with a provider |
+| Command                 | Description                    |
+| ----------------------- | ------------------------------ |
+| `auth login [provider]` | Authenticate with a provider   |
 | `auth logout <provider>` | Remove authentication |
 | `auth list` | List authenticated providers |
 
 ### Models
 
-| Command | Description |
-|---------|-------------|
-| `model list` | List available models |
+| Command                            | Description            |
+| ---------------------------------- | ---------------------- |
+| `model list`                       | List available models  |
 | `model refresh` | Refresh models cache |
 | `model priority list` | Show priorities |
 | `model priority <model> --position <n>` | Set priority |
@@ -201,9 +242,9 @@ POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
 
 ### Contexts (Remote Management)
 
-| Command | Description |
-|---------|-------------|
-| `context show` | Show current context |
+| Command                                              | Description          |
+| ---------------------------------------------------- | -------------------- |
+| `context show`                                       | Show current context |
 | `context list` | List all contexts |
 | `context set <name>` | Switch context |
 | `context add <name> --endpoint <url> --api-key <key>` | Add remote context |
@@ -211,11 +252,9 @@ POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
 
 ### Other
 
-| Command | Description |
-|---------|-------------|
+| Command              | Description                   |
+| -------------------- | ----------------------------- |
 | `config claude-code` | Generate Claude Code settings |
-| `stats --days 7` | Show usage statistics |
-| `stats --days 30 --heatmap` | Show heatmap visualization |
 
 ## API Reference
 
@@ -262,8 +301,8 @@ POST /api/admin/models/refresh   # Refresh model cache
 
 Following XDG Base Directory specification:
 
-| Type | Path | Contents |
-|------|------|----------|
+| Type       | Path                               | Contents                     |
+| ---------- | ---------------------------------- | ---------------------------- |
 | **Config** | `~/.config/router-maestro/` | |
 | | `providers.json` | Custom provider definitions |
 | | `priorities.json` | Model priorities and fallback |
@@ -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
 
@@ -302,8 +340,8 @@ export OLLAMA_API_KEY="sk-..."
 
 Configuration files are automatically reloaded every 5 minutes:
 
-| File | Auto-Reload |
-|------|-------------|
+| File               | Auto-Reload      |
+| ------------------ | ---------------- |
 | `priorities.json` | ✓ (5 min) |
 | `providers.json` | ✓ (5 min) |
 | `auth.json` | Requires restart |
@@ -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
@@ -368,6 +405,7 @@ router-maestro stats --days 7
 The Docker Compose setup includes Traefik for automatic HTTPS via Let's Encrypt with DNS challenge.
 
 For detailed configuration options including:
+
 - Other DNS providers (Route53, DigitalOcean, etc.)
 - HTTP challenge setup
 - Traefik dashboard configuration

{router_maestro-0.1.2 → router_maestro-0.1.4}/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
@@ -75,8 +95,8 @@ router-maestro config claude-code
 
 Models are identified using the format `{provider}/{model-id}`:
 
-| Example | Description |
-|---------|-------------|
+| Example                           | Description                         |
+| --------------------------------- | ----------------------------------- |
 | `github-copilot/gpt-4o` | GPT-4o via GitHub Copilot |
 | `github-copilot/claude-sonnet-4` | Claude Sonnet 4 via GitHub Copilot |
 | `openai/gpt-4-turbo` | GPT-4 Turbo via OpenAI |
@@ -107,8 +127,8 @@ router-maestro model priority list
 
 **Fallback** triggers when a request fails with a retryable error (429, 5xx):
 
-| Strategy | Behavior |
-|----------|----------|
+| Strategy     | Behavior                             |
+| ------------ | ------------------------------------ |
 | `priority` | Try next model in priorities list |
 | `same-model` | Try same model on different provider |
 | `none` | Fail immediately |
@@ -134,29 +154,50 @@ 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
 
-| Command | Description |
-|---------|-------------|
-| `server start --port 8080` | Start the server |
+| Command                    | Description        |
+| -------------------------- | ------------------ |
+| `server start --port 8080` | Start the server   |
 | `server stop` | Stop the server |
 | `server info` | Show server status |
 
 ### Authentication
 
-| Command | Description |
-|---------|-------------|
-| `auth login [provider]` | Authenticate with a provider |
+| Command                 | Description                    |
+| ----------------------- | ------------------------------ |
+| `auth login [provider]` | Authenticate with a provider   |
 | `auth logout <provider>` | Remove authentication |
 | `auth list` | List authenticated providers |
 
 ### Models
 
-| Command | Description |
-|---------|-------------|
-| `model list` | List available models |
+| Command                            | Description            |
+| ---------------------------------- | ---------------------- |
+| `model list`                       | List available models  |
 | `model refresh` | Refresh models cache |
 | `model priority list` | Show priorities |
 | `model priority <model> --position <n>` | Set priority |
@@ -164,9 +205,9 @@ POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
 
 ### Contexts (Remote Management)
 
-| Command | Description |
-|---------|-------------|
-| `context show` | Show current context |
+| Command                                              | Description          |
+| ---------------------------------------------------- | -------------------- |
+| `context show`                                       | Show current context |
 | `context list` | List all contexts |
 | `context set <name>` | Switch context |
 | `context add <name> --endpoint <url> --api-key <key>` | Add remote context |
@@ -174,11 +215,9 @@ POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
 
 ### Other
 
-| Command | Description |
-|---------|-------------|
+| Command              | Description                   |
+| -------------------- | ----------------------------- |
 | `config claude-code` | Generate Claude Code settings |
-| `stats --days 7` | Show usage statistics |
-| `stats --days 30 --heatmap` | Show heatmap visualization |
 
 ## API Reference
 
@@ -225,8 +264,8 @@ POST /api/admin/models/refresh   # Refresh model cache
 
 Following XDG Base Directory specification:
 
-| Type | Path | Contents |
-|------|------|----------|
+| Type       | Path                               | Contents                     |
+| ---------- | ---------------------------------- | ---------------------------- |
 | **Config** | `~/.config/router-maestro/` | |
 | | `providers.json` | Custom provider definitions |
 | | `priorities.json` | Model priorities and fallback |
@@ -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
 
@@ -265,8 +303,8 @@ export OLLAMA_API_KEY="sk-..."
 
 Configuration files are automatically reloaded every 5 minutes:
 
-| File | Auto-Reload |
-|------|-------------|
+| File               | Auto-Reload      |
+| ------------------ | ---------------- |
 | `priorities.json` | ✓ (5 min) |
 | `providers.json` | ✓ (5 min) |
 | `auth.json` | Requires restart |
@@ -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
@@ -331,6 +368,7 @@ router-maestro stats --days 7
 The Docker Compose setup includes Traefik for automatic HTTPS via Let's Encrypt with DNS challenge.
 
 For detailed configuration options including:
+
 - Other DNS providers (Route53, DigitalOcean, etc.)
 - HTTP challenge setup
 - Traefik dashboard configuration

{router_maestro-0.1.2 → router_maestro-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "router-maestro"
-version = "0.1.2"
+version = "0.1.4"
 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.4}/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.4"

{router_maestro-0.1.2 → router_maestro-0.1.4}/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.4}/src/router_maestro/cli/config.py

@@ -15,9 +15,17 @@ from rich.table import Table
 from router_maestro.cli.client import ServerNotRunningError, get_admin_client
 from router_maestro.config.server import get_current_context_api_key
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(invoke_without_command=True)
 console = Console()
 
+# Available CLI tools for configuration
+CLI_TOOLS = {
+    "claude-code": {
+        "name": "Claude Code",
+        "description": "Generate settings.json for Claude Code CLI",
+    },
+}
+
 
 def get_claude_code_paths() -> dict[str, Path]:
     """Get Claude Code settings paths."""
@@ -27,6 +35,33 @@ def get_claude_code_paths() -> dict[str, Path]:
     }
 
 
+@app.callback(invoke_without_command=True)
+def config_callback(ctx: typer.Context) -> None:
+    """Generate configuration for CLI tools (interactive selection if not specified)."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # Interactive selection
+    console.print("\n[bold]Available CLI tools:[/bold]")
+    tools = list(CLI_TOOLS.items())
+    for i, (key, info) in enumerate(tools, 1):
+        console.print(f"  {i}. {info['name']} - {info['description']}")
+
+    console.print()
+    choice = Prompt.ask(
+        "Select tool to configure",
+        choices=[str(i) for i in range(1, len(tools) + 1)],
+        default="1",
+    )
+
+    idx = int(choice) - 1
+    tool_key = tools[idx][0]
+
+    # Dispatch to the appropriate command
+    if tool_key == "claude-code":
+        claude_code_config()
+
+
 @app.command(name="claude-code")
 def claude_code_config() -> None:
     """Generate Claude Code CLI settings.json for router-maestro."""

{router_maestro-0.1.2 → router_maestro-0.1.4}/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.4}/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.4}/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.4}/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.4}/src/router_maestro/routing/router.py

@@ -382,7 +382,7 @@ class Router:
         try:
             await provider.ensure_token()
             if is_stream:
-                stream = provider.chat_completion_stream(actual_request)
+                stream = await provider.chat_completion_stream(actual_request)
                 logger.info("Stream request routed to %s", provider_name)
                 return stream, provider_name
             else:
@@ -417,7 +417,7 @@ class Router:
                 try:
                     await other_provider.ensure_token()
                     if is_stream:
-                        stream = other_provider.chat_completion_stream(fallback_request)
+                        stream = await other_provider.chat_completion_stream(fallback_request)
                         logger.info("Stream fallback succeeded via %s", other_name)
                         return stream, other_name
                     else: