claude-code-llm-router 0.2.0__tar.gz

claude_code_llm_router-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "ypollak2",
+  "owner": {
+    "name": "Yali Pollak"
+  },
+  "plugins": [
+    {
+      "name": "llm-router",
+      "description": "Route text, image, video, and audio tasks to 20+ AI providers with smart routing, budget control, and multi-step orchestration",
+      "version": "0.1.0",
+      "source": {
+        "source": "github",
+        "repo": "ypollak2/llm-router"
+      }
+    }
+  ]
+}

claude_code_llm_router-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "llm-router",
+  "version": "0.2.0",
+  "description": "Smart LLM routing with Claude subscription monitoring, Codex desktop integration, complexity-first model selection, and 20+ AI providers",
+  "author": {
+    "name": "ypollak2"
+  },
+  "homepage": "https://github.com/ypollak2/llm-router",
+  "repository": "https://github.com/ypollak2/llm-router",
+  "license": "MIT"
+}

claude_code_llm_router-0.2.0/.env.example

@@ -0,0 +1,27 @@
+# LLM Router — API Keys
+# Copy to .env and fill in keys. Run `llm-router-onboard` for interactive setup.
+# Start with Gemini's free tier: https://aistudio.google.com/apikey
+
+# ── Text LLM Providers ──
+OPENAI_API_KEY=                  # https://platform.openai.com/api-keys
+GEMINI_API_KEY=                  # https://aistudio.google.com/apikey (FREE tier available!)
+PERPLEXITY_API_KEY=              # https://www.perplexity.ai/settings/api
+ANTHROPIC_API_KEY=               # https://console.anthropic.com/settings/keys
+MISTRAL_API_KEY=                 # https://console.mistral.ai/api-keys
+DEEPSEEK_API_KEY=                # https://platform.deepseek.com/api_keys
+GROQ_API_KEY=                    # https://console.groq.com/keys (FREE tier!)
+TOGETHER_API_KEY=                # https://api.together.xyz/settings/api-keys
+XAI_API_KEY=                     # https://console.x.ai/
+COHERE_API_KEY=                  # https://dashboard.cohere.com/api-keys
+
+# ── Media Providers ──
+FAL_KEY=                         # https://fal.ai/dashboard/keys (Flux, Kling, etc.)
+STABILITY_API_KEY=               # https://platform.stability.ai/account/keys
+ELEVENLABS_API_KEY=              # https://elevenlabs.io/app/settings/api-keys
+RUNWAY_API_KEY=                  # https://dev.runwayml.com/
+REPLICATE_API_TOKEN=             # https://replicate.com/account/api-tokens
+
+# ── Router Config ──
+LLM_ROUTER_PROFILE=balanced     # budget | balanced | premium
+LLM_ROUTER_MONTHLY_BUDGET=0     # USD monthly limit (0 = unlimited)
+LLM_ROUTER_TIER=free            # free | pro | team

claude_code_llm_router-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --ignore=tests/test_integration.py
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.11
+      - run: uv sync --extra dev
+      - run: uv run ruff check src/ tests/

claude_code_llm_router-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+__pycache__/
+*.pyc
+.ruff_cache/
+.pytest_cache/
+dist/
+*.egg-info/
+.venv/

claude_code_llm_router-0.2.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "llm-router": {
+      "command": "uv",
+      "args": ["run", "--directory", ".", "llm-router"]
+    }
+  }
+}

claude_code_llm_router-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## v0.2.0 — Intelligence Layer (2026-03-29)
+
+### Added
+
+- **Complexity-first routing** — simple tasks → haiku, moderate → sonnet, complex → opus. Budget downshifting is now a late safety net at 85%+, not the primary mechanism.
+- **Live Claude subscription monitoring** — fetches session/weekly usage from claude.ai internal JSON API via Playwright `browser_evaluate(fetch(...))`.
+- **Time-aware budget pressure** — `effective_pressure` reduces downshift urgency when session reset is imminent (< 30 min away).
+- **Codex desktop integration** — routes tasks to local Codex CLI (`/Applications/Codex.app`), free via OpenAI subscription.
+- **Unified usage dashboard** (`llm_usage`) — single view of Claude subscription %, Codex status, API spend per provider, and routing savings.
+- **`llm_setup` tool** — discover existing API keys on the laptop, add new providers with validation, view setup guides. All operations local-only with key masking and `.gitignore` checks.
+- **Per-provider budget limits** — `LLM_ROUTER_BUDGET_OPENAI`, `LLM_ROUTER_BUDGET_GEMINI`, etc.
+- **Gemini media routing** — Imagen 3 (images) and Veo 2 (video) added to all routing profiles.
+- **`llm_classify` tool** — classify task complexity and see the routing recommendation with model/cost details.
+- **`llm_check_usage` / `llm_update_usage`** — fetch and store Claude subscription data for routing decisions.
+- **`llm_track_usage`** — record usage for a specific provider.
+- **External fallback ranking** — when Claude quota is tight, rank available external models by quality (descending) and cost (ascending).
+
+### Changed
+
+- Dashboard output switched to **ASCII box-drawing** (`+`, `-`, `|`, `=`, `.`) for reliable rendering in Claude Code's MCP output.
+- Pressure thresholds updated from 50%/80% to **85%/95%** safety net — complexity routing handles the rest.
+- Classification headers use text tags (`[S]`, `[M]`, `[C]`) instead of emoji.
+- Budget bars use ASCII (`[====........]`) instead of Unicode blocks.
+- Tool count increased from 17 to 20.
+
+### Fixed
+
+- MCP tool output rendering issues (Unicode blocks, markdown, emoji all garbled in collapsed JSON view).
+- f-string backslash errors in dashboard formatting code.
+
+## v0.1.0 — Foundation (2026-03-15)
+
+### Added
+
+- Text LLM routing via LiteLLM (10 providers)
+- Three routing profiles: budget, balanced, premium
+- Cost tracking with SQLite
+- Health checks with circuit breaker pattern
+- Image generation (DALL-E, Flux, Stable Diffusion)
+- Video generation (Runway, Kling, minimax)
+- Audio/voice routing (ElevenLabs, OpenAI TTS)
+- Monthly budget enforcement with hard limits
+- Multi-step orchestration with pipeline templates
+- Claude Code plugin with `/route` skill
+- Freemium tier gating (free / pro)
+- CI with GitHub Actions

claude_code_llm_router-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to LLM Router
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/ypollak2/llm-router.git
+cd llm-router
+uv sync --extra dev
+cp .env.example .env
+# Add at least one API key to .env
+```
+
+## Running Tests
+
+```bash
+# Unit tests (no API keys needed)
+uv run pytest tests/ -v --ignore=tests/test_integration.py
+
+# Integration tests (requires API keys in .env)
+uv run pytest tests/test_integration.py -v
+
+# Full suite
+uv run pytest -v
+
+# Lint
+uv run ruff check src/
+```
+
+## Adding a New Provider
+
+1. Add the model mapping to `src/llm_router/profiles.py`
+2. Add the provider's API key to `src/llm_router/config.py`
+3. Add the provider to `_PROVIDER_REGISTRY` in `src/llm_router/server.py` (for `llm_setup`)
+4. Update the onboarding wizard in `src/llm_router/onboard.py`
+5. Add integration tests in `tests/test_integration.py`
+6. Update `docs/PROVIDERS.md` with setup instructions
+
+Most providers work through LiteLLM with zero custom code — just add the model string and key.
+
+## Key Modules
+
+| Module | Purpose |
+|--------|---------|
+| `server.py` | MCP tool definitions (20 tools), `llm_setup` provider registry |
+| `router.py` | Complexity classification and model selection logic |
+| `profiles.py` | Model lists per routing profile (budget/balanced/premium) |
+| `config.py` | Environment-based configuration, provider detection |
+| `claude_usage.py` | Claude subscription usage parsing, time-aware pressure |
+| `codex_agent.py` | Codex desktop CLI integration (local, free via OpenAI sub) |
+| `provider_budget.py` | Per-provider budget tracking and enforcement |
+| `orchestrator.py` | Multi-step pipeline execution across providers |
+| `cost_tracker.py` | SQLite-based cost and token tracking |
+| `health.py` | Provider health checks with circuit breaker pattern |
+
+## Pull Request Guidelines
+
+- One concern per PR
+- Include tests for new functionality
+- Run `uv run ruff check src/` before submitting
+- Follow existing code style (Pydantic models, async/await, type hints)
+- Update the README if adding user-facing features
+
+## Code Style
+
+- Python 3.10+ with type hints
+- `snake_case` for functions/variables, `PascalCase` for classes
+- Pydantic for config and external data
+- Async/await throughout (MCP server is async)
+- Keep files under 400 lines
+
+## Commit Messages
+
+```
+feat: add Runway video generation support
+fix: circuit breaker not resetting after cooldown
+docs: add ElevenLabs setup guide
+test: add integration tests for image routing
+```
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

claude_code_llm_router-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLM Router 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.