router-maestro 0.1.2__py3-none-any.whl

router_maestro-0.1.2.dist-info/METADATA

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: router-maestro
+Version: 0.1.2
+Summary: Multi-model routing and load balancing system with OpenAI-compatible API
+Author-email: Kanwen Li <likanwen@icloud.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,copilot,llm,load-balancing,openai,routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: authlib>=1.3.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: plotext>=5.2.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pyinstaller>=6.3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Router-Maestro
+
+Multi-model routing router with OpenAI-compatible and Anthropic-compatible APIs. Route LLM requests across GitHub Copilot, OpenAI, Anthropic, and custom providers with intelligent fallback and priority-based selection.
+
+## TL;DR
+
+**Use GitHub Copilot's models (Claude, GPT-4o, o3-mini) with Claude Code or any OpenAI/Anthropic-compatible client.**
+
+Router-Maestro acts as a proxy that gives you access to models from multiple providers through a unified API. Authenticate once with GitHub Copilot, and use its models anywhere that supports OpenAI or Anthropic APIs.
+
+## Features
+
+- **Multi-provider support**: GitHub Copilot (OAuth), OpenAI, Anthropic, and custom OpenAI-compatible endpoints
+- **Intelligent routing**: Priority-based model selection with automatic fallback on failure
+- **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
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [CLI Reference](#cli-reference)
+- [API Reference](#api-reference)
+- [Configuration](#configuration)
+- [Deployment](#deployment)
+- [License](#license)
+
+## Quick Start
+
+Get up and running in 4 steps:
+
+### 1. Install
+
+```bash
+pip install router-maestro
+# or
+uv pip install router-maestro
+```
+
+### 2. Start the Server
+
+```bash
+router-maestro server start --port 8080
+```
+
+### 3. Authenticate with GitHub Copilot
+
+```bash
+router-maestro auth login github-copilot
+
+# Follow the prompts:
+#   1. Visit https://github.com/login/device
+#   2. Enter the displayed code
+#   3. Authorize "GitHub Copilot Chat"
+```
+
+### 4. Configure Claude Code
+
+```bash
+router-maestro config claude-code
+# Follow the wizard to select models
+```
+
+**Done!** Now run `claude` and your requests will route through Router-Maestro.
+
+> **For production deployment**, see the [Deployment](#deployment) section.
+
+## Core Concepts
+
+### Model Identification
+
+Models are identified using the format `{provider}/{model-id}`:
+
+| 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 |
+| `anthropic/claude-3-5-sonnet` | Claude 3.5 Sonnet via Anthropic |
+
+### Auto-Routing
+
+Use the special model name `router-maestro` for automatic provider selection:
+
+```json
+{"model": "router-maestro", "messages": [...]}
+```
+
+The router will try models in priority order and fall back to the next on failure.
+
+### Priority & Fallback
+
+**Priority** determines which model is tried first when using auto-routing.
+
+```bash
+# Set priorities
+router-maestro model priority github-copilot/claude-sonnet-4 --position 1
+router-maestro model priority github-copilot/gpt-4o --position 2
+
+# View priorities
+router-maestro model priority list
+```
+
+**Fallback** triggers when a request fails with a retryable error (429, 5xx):
+
+| Strategy | Behavior |
+|----------|----------|
+| `priority` | Try next model in priorities list |
+| `same-model` | Try same model on different provider |
+| `none` | Fail immediately |
+
+Configure in `~/.config/router-maestro/priorities.json`:
+
+```json
+{
+  "priorities": ["github-copilot/claude-sonnet-4", "github-copilot/gpt-4o"],
+  "fallback": {"strategy": "priority", "maxRetries": 2}
+}
+```
+
+### Cross-Provider Translation
+
+Router-Maestro automatically translates between OpenAI and Anthropic formats:
+
+```bash
+# Use Anthropic API with OpenAI provider
+POST /v1/messages  {"model": "openai/gpt-4o", ...}
+
+# Use OpenAI API with Anthropic provider
+POST /v1/chat/completions  {"model": "anthropic/claude-3-5-sonnet", ...}
+```
+
+## CLI Reference
+
+### 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 |
+| `auth logout <provider>` | Remove authentication |
+| `auth list` | List authenticated providers |
+
+### 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 |
+| `model fallback show` | Show fallback config |
+
+### Contexts (Remote Management)
+
+| 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 |
+| `context test` | Test connection |
+
+### Other
+
+| Command | Description |
+|---------|-------------|
+| `config claude-code` | Generate Claude Code settings |
+| `stats --days 7` | Show usage statistics |
+| `stats --days 30 --heatmap` | Show heatmap visualization |
+
+## API Reference
+
+### OpenAI-Compatible
+
+```bash
+# Chat completions
+POST /v1/chat/completions
+{
+  "model": "github-copilot/gpt-4o",
+  "messages": [{"role": "user", "content": "Hello"}],
+  "stream": false
+}
+
+# List models
+GET /v1/models
+```
+
+### Anthropic-Compatible
+
+```bash
+# Messages
+POST /v1/messages
+POST /api/anthropic/v1/messages
+{
+  "model": "github-copilot/claude-sonnet-4",
+  "max_tokens": 1024,
+  "messages": [{"role": "user", "content": "Hello"}]
+}
+
+# Count tokens
+POST /v1/messages/count_tokens
+```
+
+### Admin
+
+```bash
+POST /api/admin/models/refresh   # Refresh model cache
+```
+
+## Configuration
+
+### File Locations
+
+Following XDG Base Directory specification:
+
+| Type | Path | Contents |
+|------|------|----------|
+| **Config** | `~/.config/router-maestro/` | |
+| | `providers.json` | Custom provider definitions |
+| | `priorities.json` | Model priorities and fallback |
+| | `contexts.json` | Deployment contexts |
+| **Data** | `~/.local/share/router-maestro/` | |
+| | `auth.json` | OAuth tokens |
+| | `server.json` | Server state |
+| | `stats.db` | Usage statistics |
+
+### Custom Providers
+
+Add OpenAI-compatible providers in `~/.config/router-maestro/providers.json`:
+
+```json
+{
+  "providers": {
+    "ollama": {
+      "type": "openai-compatible",
+      "baseURL": "http://localhost:11434/v1",
+      "models": {
+        "llama3": {"name": "Llama 3"},
+        "mistral": {"name": "Mistral 7B"}
+      }
+    }
+  }
+}
+```
+
+Set API keys via environment variables (uppercase, hyphens → underscores):
+
+```bash
+export OLLAMA_API_KEY="sk-..."
+```
+
+### Hot-Reload
+
+Configuration files are automatically reloaded every 5 minutes:
+
+| File | Auto-Reload |
+|------|-------------|
+| `priorities.json` | ✓ (5 min) |
+| `providers.json` | ✓ (5 min) |
+| `auth.json` | Requires restart |
+
+Force immediate reload:
+
+```bash
+router-maestro model refresh
+```
+
+## Deployment
+
+### Docker Deployment
+
+Deploy to a VPS with Docker Compose:
+
+```bash
+# On your VPS
+git clone https://github.com/likanwen/router-maestro.git
+cd router-maestro
+cp .env.example .env  # Edit with your domain
+docker compose up -d
+```
+
+Configure `.env`:
+
+```bash
+DOMAIN=api.example.com
+CF_DNS_API_TOKEN=your_cloudflare_token  # For HTTPS
+ACME_EMAIL=your@email.com
+ROUTER_MAESTRO_API_KEY=$(openssl rand -hex 32)
+```
+
+Authenticate inside the container:
+
+```bash
+docker compose exec router-maestro /bin/sh
+router-maestro auth login github-copilot
+# Follow OAuth flow, then exit
+```
+
+### Remote Management
+
+Manage your VPS deployment from your local machine using contexts:
+
+```bash
+# Add remote context
+router-maestro context add my-vps \
+  --endpoint https://api.example.com \
+  --api-key your_api_key
+
+# Switch to remote
+router-maestro context set my-vps
+
+# Now all commands target the VPS
+router-maestro model list
+router-maestro stats --days 7
+```
+
+### HTTPS with Traefik
+
+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
+
+See [docs/deployment.md](docs/deployment.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

router_maestro-0.1.2.dist-info/RECORD

@@ -0,0 +1,57 @@
+router_maestro/__init__.py,sha256=DjSxTt-117MUK3rqehh5MME5nt25J3uPF88_sJGhvBk,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
+router_maestro/auth/manager.py,sha256=OQjdofmjVndTQQIrAU7O-hJAL-w_ijYRU09fZNU8E3g,4554
+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/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/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/config/contexts.py,sha256=ujaH5I3xa3Eg_KlRaF5KlmsACuUqoKqsp1-i1J2kQz4,923
+router_maestro/config/paths.py,sha256=xaAi9LuTFSag7yGJp9oCnrcTpnXcaPTMKU5yAIYkCT8,1617
+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
+router_maestro/config/settings.py,sha256=cEgE0XjdYMbB39wJDQiTurWSbfJwjAjLI8g7ZOiyd1o,2363
+router_maestro/providers/__init__.py,sha256=Cic08fXrcBPbxSLOqLg3edTThop6j--AqdcwI7wJSp8,759
+router_maestro/providers/anthropic.py,sha256=zhBDtPootCVCYfGyrsogdy3j8jC1aMwi01hWkg-uKmA,8077
+router_maestro/providers/base.py,sha256=2WvR-jjkYNkQUy6EBXvuOkv3v7xCvAfgVigvuKukG3o,3111
+router_maestro/providers/copilot.py,sha256=NieOXBecwymSnB1Nm_JKVvzeZyZnO8g6Y1kNaLHy3XE,12974
+router_maestro/providers/openai.py,sha256=Bsq5mzAVf4CawH2Tn80y3-MyLLVeZ3VsPxGDNH1t_Nk,7647
+router_maestro/providers/openai_compat.py,sha256=ef4RttKVZUTBiRed4BEuC2Jg8vr5GM7YqPUtFYeAhZo,6383
+router_maestro/routing/__init__.py,sha256=eCEQVbg1LAfcSVLQZpZtYf8ImbOhFIaR7POUb1pCbXM,169
+router_maestro/routing/router.py,sha256=4T-yBI9fCRKXeyjeVT6aSfALj2OMaNwsn11qXntno-o,20390
+router_maestro/server/__init__.py,sha256=YzExJfP0jw6hXx84lo0yPVU0wG17B16SfdyEpjstpxk,128
+router_maestro/server/app.py,sha256=rI2TuCS_STzmzdds5Tq2vzoP9y9bpRFJJwNs5e8uTbU,2707
+router_maestro/server/oauth_sessions.py,sha256=r_VM6vAtbo5HAmXjYt6XoECBcWGxqABKGbVmW8HoCz0,4625
+router_maestro/server/translation.py,sha256=TrYfIb5M5MAUC4TD5By8X3RONSZ6cV1YS_JwzIc-bVk,22170
+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/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/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.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

router_maestro-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+router-maestro = router_maestro.cli.main:app

router_maestro-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Router-Maestro Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.