claude-model-router 0.2.0__tar.gz

claude_model_router-0.2.0/LICENSE

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

claude_model_router-0.2.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: claude-model-router
+Version: 0.2.0
+Summary: Cost-aware model routing for the Claude API — reference implementation with a Claude Code subagent hook
+Author: Juno Seong
+License: MIT
+Project-URL: Homepage, https://github.com/junoseong/claude-model-router
+Project-URL: Repository, https://github.com/junoseong/claude-model-router
+Project-URL: Issues, https://github.com/junoseong/claude-model-router/issues
+Keywords: claude,anthropic,llm,model-routing,cost-optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.115
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# claude-model-router
+
+Reference implementation of cost-aware model routing for the Claude API —
+plus a Claude Code hook that stops subagents from silently inheriting your
+most expensive model.
+
+A cheap Haiku 4.5 call classifies each prompt's complexity; the prompt then
+executes on the cheapest capable tier. Small, tested, and built around the
+parts naive routers get wrong.
+
+## Why naive Claude routers break
+
+Most routing examples treat model IDs as interchangeable strings. On the
+Claude 5 family they are not:
+
+| Trap | What actually happens | Where handled |
+|---|---|---|
+| Refusals are not exceptions | Fable 5 refusals return **HTTP 200** with `stop_reason: "refusal"` — a try/except fallback never fires | server-side fallback beta + explicit `stop_reason` check ([router.py](model_router/router.py)) |
+| `thinking` differs per model | Fable 5: always on, explicit config → 400. Opus 4.8: omitted = **off**. Sonnet 5: omitted = adaptive. Haiku 4.5: adaptive → 400 | per-model request shape in `build_request()` |
+| `effort` is not universal | `output_config: {"effort": ...}` → 400 on Haiku 4.5 | effort omitted on the trivial tier |
+| `content[0].text` crashes | refusals ship empty `content`; thinking blocks precede text blocks | block-type-filtered extraction |
+| Small `max_tokens` + high effort = truncation | thinking tokens spend from `max_tokens`; xhigh turns run minutes | 64K `max_tokens` + streaming everywhere |
+| Cache dies on model switch | prompt caches are **model-scoped**; per-turn routing invalidates the cache every turn | route once per conversation, reuse via `execute()` |
+| Context windows differ | Haiku 4.5 = 200K; every other tier model = 1M | trivial bumped to low above 180K context tokens |
+
+## Tiers
+
+| Tier | Model | Effort | Notes |
+|------|-------|--------|-------|
+| trivial | `claude-haiku-4-5` | — | reformatting, extraction, classification |
+| low  | `claude-sonnet-5`  | medium | summaries, single-function edits, simple Q&A |
+| mid  | `claude-opus-4-8`  | high   | debugging, security review, single-file refactors |
+| high | `claude-fable-5`   | xhigh  | multi-file refactors, migrations, architecture |
+
+The keyword-heuristic fallback (used when the classifier call fails) never
+assigns trivial — misrouting real work to Haiku costs more in retries than
+the tier saves, so only the classifier may pick it.
+
+## Usage
+
+```python
+import anthropic
+from model_router import run, execute
+
+client = anthropic.Anthropic()
+
+result = run(client, "Refactor the auth module across services")
+print(result.route.model, result.route.source)  # claude-fable-5 classifier
+print(result.served_by)                          # may be opus-4-8 after a fallback
+print(result.text)
+```
+
+Multi-turn: prompt caches are model-scoped, so route once per conversation
+and reuse the route for follow-ups —
+
+```python
+route = result.route
+result2 = execute(client, route, full_message_history)
+```
+
+## Cost model
+
+1,000 prompts, mixed workload (30% trivial / 40% low / 20% mid / 10% high),
+list pricing, output token counts held equal across models (conservative —
+Fable at xhigh thinks longer than smaller models on the same prompt):
+
+| Tier | Prompts | Routed model | Routed cost | All-Fable cost |
+|---|---|---|---|---|
+| trivial | 300 | `claude-haiku-4-5` | $0.54 | $5.40 |
+| low | 400 | `claude-sonnet-5` | $6.60 | $22.00 |
+| mid | 200 | `claude-opus-4-8` | $18.50 | $37.00 |
+| high | 100 | `claude-fable-5` | $80.00 | $80.00 |
+| classifier overhead | 1000 | `claude-haiku-4-5` | $0.72 | — |
+| **total** | | | **$106.36** | **$144.40** |
+
+**26% saved** on this mix — and the mix is the whole story: the 10% of
+prompts that legitimately need Fable dominate the bill. A support-bot-shaped
+workload (mostly trivial/low) saves 70%+. Rerun with your own shape:
+
+```bash
+python benchmarks/cost_model.py
+```
+
+This is a pricing calculation, not a live benchmark — it spends no tokens
+and its assumptions are at the top of the script.
+
+### Live benchmark (real tokens, real dollars)
+
+[`benchmarks/live_bench.py`](benchmarks/live_bench.py) runs a 17-prompt
+mixed workload through both arms — routed vs. all-Fable — with **real API
+calls**, and prices each call from the `usage` block the API actually
+returned (by the model that actually served it, which matters after a
+fallback). Classifier overhead is metered from real Haiku usage, not
+estimated.
+
+```bash
+ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --tiers trivial,low  # cheap smoke run
+ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --out live_results.md  # full run, ~$2-6
+```
+
+It spends real money (the all-Fable arm at xhigh dominates), refuses to
+start without a key, and flags every prompt where the classifier's tier
+disagreed with the expected tier — so you can audit misroutes instead of
+trusting a single savings number. `RoutedResult.usage` exposes the same
+real token counts in your own code.
+
+This is the honest version of the standard methodology: the same
+cost-quality comparison RouterBench and RouteLLM run offline, at a scale
+one person can afford to reproduce.
+
+## Claude Code hook: stop subagents from burning Fable tokens
+
+Separate deliverable, same philosophy. In Claude Code, **subagents inherit
+the session model by default** — run your session on an expensive model and
+every spawned agent (including greps and file listings) bills at that rate.
+
+[`hooks/subagent-router.py`](hooks/subagent-router.py) is a PreToolUse hook
+that denies any Agent spawn missing an explicit `model` param. The deny
+reason carries a routing table, so the session model immediately re-issues
+the spawn with the cheapest capable tier. Self-correcting, one file, no
+dependencies.
+
+Install:
+
+```bash
+cp hooks/subagent-router.py ~/.claude/hooks/
+```
+
+Then add to `~/.claude/settings.json`:
+
+```json
+"hooks": {
+  "PreToolUse": [
+    {
+      "matcher": "Agent",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "python3 ~/.claude/hooks/subagent-router.py"
+        }
+      ]
+    }
+  ]
+}
+```
+
+New sessions then enforce: unrouted spawn → denied with policy → re-spawned
+with explicit `model` (haiku for greps/locates, sonnet for single-file work
+and reviews, opus for multi-file/hard debugging, session model only for
+judgment-critical synthesis).
+
+## Install
+
+```bash
+pip install claude-model-router
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/junoseong/claude-model-router
+cd claude-model-router
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+## Notes
+
+- Fable 5 requires 30-day data retention; zero-data-retention orgs get 400s
+  on the high tier — remap `high` to `claude-opus-4-8` in `_TIER_ROUTES`.
+- Sonnet 5 has intro pricing ($2/$10 per MTok) through 2026-08-31; the cost
+  model uses sticker prices ($3/$15).
+
+MIT licensed.

claude_model_router-0.2.0/README.md

@@ -0,0 +1,174 @@
+# claude-model-router
+
+Reference implementation of cost-aware model routing for the Claude API —
+plus a Claude Code hook that stops subagents from silently inheriting your
+most expensive model.
+
+A cheap Haiku 4.5 call classifies each prompt's complexity; the prompt then
+executes on the cheapest capable tier. Small, tested, and built around the
+parts naive routers get wrong.
+
+## Why naive Claude routers break
+
+Most routing examples treat model IDs as interchangeable strings. On the
+Claude 5 family they are not:
+
+| Trap | What actually happens | Where handled |
+|---|---|---|
+| Refusals are not exceptions | Fable 5 refusals return **HTTP 200** with `stop_reason: "refusal"` — a try/except fallback never fires | server-side fallback beta + explicit `stop_reason` check ([router.py](model_router/router.py)) |
+| `thinking` differs per model | Fable 5: always on, explicit config → 400. Opus 4.8: omitted = **off**. Sonnet 5: omitted = adaptive. Haiku 4.5: adaptive → 400 | per-model request shape in `build_request()` |
+| `effort` is not universal | `output_config: {"effort": ...}` → 400 on Haiku 4.5 | effort omitted on the trivial tier |
+| `content[0].text` crashes | refusals ship empty `content`; thinking blocks precede text blocks | block-type-filtered extraction |
+| Small `max_tokens` + high effort = truncation | thinking tokens spend from `max_tokens`; xhigh turns run minutes | 64K `max_tokens` + streaming everywhere |
+| Cache dies on model switch | prompt caches are **model-scoped**; per-turn routing invalidates the cache every turn | route once per conversation, reuse via `execute()` |
+| Context windows differ | Haiku 4.5 = 200K; every other tier model = 1M | trivial bumped to low above 180K context tokens |
+
+## Tiers
+
+| Tier | Model | Effort | Notes |
+|------|-------|--------|-------|
+| trivial | `claude-haiku-4-5` | — | reformatting, extraction, classification |
+| low  | `claude-sonnet-5`  | medium | summaries, single-function edits, simple Q&A |
+| mid  | `claude-opus-4-8`  | high   | debugging, security review, single-file refactors |
+| high | `claude-fable-5`   | xhigh  | multi-file refactors, migrations, architecture |
+
+The keyword-heuristic fallback (used when the classifier call fails) never
+assigns trivial — misrouting real work to Haiku costs more in retries than
+the tier saves, so only the classifier may pick it.
+
+## Usage
+
+```python
+import anthropic
+from model_router import run, execute
+
+client = anthropic.Anthropic()
+
+result = run(client, "Refactor the auth module across services")
+print(result.route.model, result.route.source)  # claude-fable-5 classifier
+print(result.served_by)                          # may be opus-4-8 after a fallback
+print(result.text)
+```
+
+Multi-turn: prompt caches are model-scoped, so route once per conversation
+and reuse the route for follow-ups —
+
+```python
+route = result.route
+result2 = execute(client, route, full_message_history)
+```
+
+## Cost model
+
+1,000 prompts, mixed workload (30% trivial / 40% low / 20% mid / 10% high),
+list pricing, output token counts held equal across models (conservative —
+Fable at xhigh thinks longer than smaller models on the same prompt):
+
+| Tier | Prompts | Routed model | Routed cost | All-Fable cost |
+|---|---|---|---|---|
+| trivial | 300 | `claude-haiku-4-5` | $0.54 | $5.40 |
+| low | 400 | `claude-sonnet-5` | $6.60 | $22.00 |
+| mid | 200 | `claude-opus-4-8` | $18.50 | $37.00 |
+| high | 100 | `claude-fable-5` | $80.00 | $80.00 |
+| classifier overhead | 1000 | `claude-haiku-4-5` | $0.72 | — |
+| **total** | | | **$106.36** | **$144.40** |
+
+**26% saved** on this mix — and the mix is the whole story: the 10% of
+prompts that legitimately need Fable dominate the bill. A support-bot-shaped
+workload (mostly trivial/low) saves 70%+. Rerun with your own shape:
+
+```bash
+python benchmarks/cost_model.py
+```
+
+This is a pricing calculation, not a live benchmark — it spends no tokens
+and its assumptions are at the top of the script.
+
+### Live benchmark (real tokens, real dollars)
+
+[`benchmarks/live_bench.py`](benchmarks/live_bench.py) runs a 17-prompt
+mixed workload through both arms — routed vs. all-Fable — with **real API
+calls**, and prices each call from the `usage` block the API actually
+returned (by the model that actually served it, which matters after a
+fallback). Classifier overhead is metered from real Haiku usage, not
+estimated.
+
+```bash
+ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --tiers trivial,low  # cheap smoke run
+ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --out live_results.md  # full run, ~$2-6
+```
+
+It spends real money (the all-Fable arm at xhigh dominates), refuses to
+start without a key, and flags every prompt where the classifier's tier
+disagreed with the expected tier — so you can audit misroutes instead of
+trusting a single savings number. `RoutedResult.usage` exposes the same
+real token counts in your own code.
+
+This is the honest version of the standard methodology: the same
+cost-quality comparison RouterBench and RouteLLM run offline, at a scale
+one person can afford to reproduce.
+
+## Claude Code hook: stop subagents from burning Fable tokens
+
+Separate deliverable, same philosophy. In Claude Code, **subagents inherit
+the session model by default** — run your session on an expensive model and
+every spawned agent (including greps and file listings) bills at that rate.
+
+[`hooks/subagent-router.py`](hooks/subagent-router.py) is a PreToolUse hook
+that denies any Agent spawn missing an explicit `model` param. The deny
+reason carries a routing table, so the session model immediately re-issues
+the spawn with the cheapest capable tier. Self-correcting, one file, no
+dependencies.
+
+Install:
+
+```bash
+cp hooks/subagent-router.py ~/.claude/hooks/
+```
+
+Then add to `~/.claude/settings.json`:
+
+```json
+"hooks": {
+  "PreToolUse": [
+    {
+      "matcher": "Agent",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "python3 ~/.claude/hooks/subagent-router.py"
+        }
+      ]
+    }
+  ]
+}
+```
+
+New sessions then enforce: unrouted spawn → denied with policy → re-spawned
+with explicit `model` (haiku for greps/locates, sonnet for single-file work
+and reviews, opus for multi-file/hard debugging, session model only for
+judgment-critical synthesis).
+
+## Install
+
+```bash
+pip install claude-model-router
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/junoseong/claude-model-router
+cd claude-model-router
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+## Notes
+
+- Fable 5 requires 30-day data retention; zero-data-retention orgs get 400s
+  on the high tier — remap `high` to `claude-opus-4-8` in `_TIER_ROUTES`.
+- Sonnet 5 has intro pricing ($2/$10 per MTok) through 2026-08-31; the cost
+  model uses sticker prices ($3/$15).
+
+MIT licensed.

claude_model_router-0.2.0/claude_model_router.egg-info/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: claude-model-router
+Version: 0.2.0
+Summary: Cost-aware model routing for the Claude API — reference implementation with a Claude Code subagent hook
+Author: Juno Seong
+License: MIT
+Project-URL: Homepage, https://github.com/junoseong/claude-model-router
+Project-URL: Repository, https://github.com/junoseong/claude-model-router
+Project-URL: Issues, https://github.com/junoseong/claude-model-router/issues
+Keywords: claude,anthropic,llm,model-routing,cost-optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.115
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# claude-model-router
+
+Reference implementation of cost-aware model routing for the Claude API —
+plus a Claude Code hook that stops subagents from silently inheriting your
+most expensive model.
+
+A cheap Haiku 4.5 call classifies each prompt's complexity; the prompt then
+executes on the cheapest capable tier. Small, tested, and built around the
+parts naive routers get wrong.
+
+## Why naive Claude routers break
+
+Most routing examples treat model IDs as interchangeable strings. On the
+Claude 5 family they are not:
+
+| Trap | What actually happens | Where handled |
+|---|---|---|
+| Refusals are not exceptions | Fable 5 refusals return **HTTP 200** with `stop_reason: "refusal"` — a try/except fallback never fires | server-side fallback beta + explicit `stop_reason` check ([router.py](model_router/router.py)) |
+| `thinking` differs per model | Fable 5: always on, explicit config → 400. Opus 4.8: omitted = **off**. Sonnet 5: omitted = adaptive. Haiku 4.5: adaptive → 400 | per-model request shape in `build_request()` |
+| `effort` is not universal | `output_config: {"effort": ...}` → 400 on Haiku 4.5 | effort omitted on the trivial tier |
+| `content[0].text` crashes | refusals ship empty `content`; thinking blocks precede text blocks | block-type-filtered extraction |
+| Small `max_tokens` + high effort = truncation | thinking tokens spend from `max_tokens`; xhigh turns run minutes | 64K `max_tokens` + streaming everywhere |
+| Cache dies on model switch | prompt caches are **model-scoped**; per-turn routing invalidates the cache every turn | route once per conversation, reuse via `execute()` |
+| Context windows differ | Haiku 4.5 = 200K; every other tier model = 1M | trivial bumped to low above 180K context tokens |
+
+## Tiers
+
+| Tier | Model | Effort | Notes |
+|------|-------|--------|-------|
+| trivial | `claude-haiku-4-5` | — | reformatting, extraction, classification |
+| low  | `claude-sonnet-5`  | medium | summaries, single-function edits, simple Q&A |
+| mid  | `claude-opus-4-8`  | high   | debugging, security review, single-file refactors |
+| high | `claude-fable-5`   | xhigh  | multi-file refactors, migrations, architecture |
+
+The keyword-heuristic fallback (used when the classifier call fails) never
+assigns trivial — misrouting real work to Haiku costs more in retries than
+the tier saves, so only the classifier may pick it.
+
+## Usage
+
+```python
+import anthropic
+from model_router import run, execute
+
+client = anthropic.Anthropic()
+
+result = run(client, "Refactor the auth module across services")
+print(result.route.model, result.route.source)  # claude-fable-5 classifier
+print(result.served_by)                          # may be opus-4-8 after a fallback
+print(result.text)
+```
+
+Multi-turn: prompt caches are model-scoped, so route once per conversation
+and reuse the route for follow-ups —
+
+```python
+route = result.route
+result2 = execute(client, route, full_message_history)
+```
+
+## Cost model
+
+1,000 prompts, mixed workload (30% trivial / 40% low / 20% mid / 10% high),
+list pricing, output token counts held equal across models (conservative —
+Fable at xhigh thinks longer than smaller models on the same prompt):
+
+| Tier | Prompts | Routed model | Routed cost | All-Fable cost |
+|---|---|---|---|---|
+| trivial | 300 | `claude-haiku-4-5` | $0.54 | $5.40 |
+| low | 400 | `claude-sonnet-5` | $6.60 | $22.00 |
+| mid | 200 | `claude-opus-4-8` | $18.50 | $37.00 |
+| high | 100 | `claude-fable-5` | $80.00 | $80.00 |
+| classifier overhead | 1000 | `claude-haiku-4-5` | $0.72 | — |
+| **total** | | | **$106.36** | **$144.40** |
+
+**26% saved** on this mix — and the mix is the whole story: the 10% of
+prompts that legitimately need Fable dominate the bill. A support-bot-shaped
+workload (mostly trivial/low) saves 70%+. Rerun with your own shape:
+
+```bash
+python benchmarks/cost_model.py
+```
+
+This is a pricing calculation, not a live benchmark — it spends no tokens
+and its assumptions are at the top of the script.
+
+### Live benchmark (real tokens, real dollars)
+
+[`benchmarks/live_bench.py`](benchmarks/live_bench.py) runs a 17-prompt
+mixed workload through both arms — routed vs. all-Fable — with **real API
+calls**, and prices each call from the `usage` block the API actually
+returned (by the model that actually served it, which matters after a
+fallback). Classifier overhead is metered from real Haiku usage, not
+estimated.
+
+```bash
+ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --tiers trivial,low  # cheap smoke run
+ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --out live_results.md  # full run, ~$2-6
+```
+
+It spends real money (the all-Fable arm at xhigh dominates), refuses to
+start without a key, and flags every prompt where the classifier's tier
+disagreed with the expected tier — so you can audit misroutes instead of
+trusting a single savings number. `RoutedResult.usage` exposes the same
+real token counts in your own code.
+
+This is the honest version of the standard methodology: the same
+cost-quality comparison RouterBench and RouteLLM run offline, at a scale
+one person can afford to reproduce.
+
+## Claude Code hook: stop subagents from burning Fable tokens
+
+Separate deliverable, same philosophy. In Claude Code, **subagents inherit
+the session model by default** — run your session on an expensive model and
+every spawned agent (including greps and file listings) bills at that rate.
+
+[`hooks/subagent-router.py`](hooks/subagent-router.py) is a PreToolUse hook
+that denies any Agent spawn missing an explicit `model` param. The deny
+reason carries a routing table, so the session model immediately re-issues
+the spawn with the cheapest capable tier. Self-correcting, one file, no
+dependencies.
+
+Install:
+
+```bash
+cp hooks/subagent-router.py ~/.claude/hooks/
+```
+
+Then add to `~/.claude/settings.json`:
+
+```json
+"hooks": {
+  "PreToolUse": [
+    {
+      "matcher": "Agent",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "python3 ~/.claude/hooks/subagent-router.py"
+        }
+      ]
+    }
+  ]
+}
+```
+
+New sessions then enforce: unrouted spawn → denied with policy → re-spawned
+with explicit `model` (haiku for greps/locates, sonnet for single-file work
+and reviews, opus for multi-file/hard debugging, session model only for
+judgment-critical synthesis).
+
+## Install
+
+```bash
+pip install claude-model-router
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/junoseong/claude-model-router
+cd claude-model-router
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+## Notes
+
+- Fable 5 requires 30-day data retention; zero-data-retention orgs get 400s
+  on the high tier — remap `high` to `claude-opus-4-8` in `_TIER_ROUTES`.
+- Sonnet 5 has intro pricing ($2/$10 per MTok) through 2026-08-31; the cost
+  model uses sticker prices ($3/$15).
+
+MIT licensed.

claude_model_router-0.2.0/claude_model_router.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+claude_model_router.egg-info/PKG-INFO
+claude_model_router.egg-info/SOURCES.txt
+claude_model_router.egg-info/dependency_links.txt
+claude_model_router.egg-info/requires.txt
+claude_model_router.egg-info/top_level.txt
+model_router/__init__.py
+model_router/classifier.py
+model_router/router.py
+tests/test_classifier.py
+tests/test_router.py

claude_model_router-0.2.0/claude_model_router.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

claude_model_router-0.2.0/claude_model_router.egg-info/requires.txt

@@ -0,0 +1,4 @@
+anthropic>=0.115
+
+[dev]
+pytest>=8

claude_model_router-0.2.0/claude_model_router.egg-info/top_level.txt

@@ -0,0 +1 @@
+model_router

claude_model_router-0.2.0/model_router/__init__.py

@@ -0,0 +1,25 @@
+"""Cost-aware model routing for the Claude API.
+
+Classifies prompt complexity with a cheap Haiku call (keyword heuristic
+as fallback) and executes on the cheapest capable model tier:
+
+    trivial -> claude-haiku-4-5 (no thinking; bumped to low if context > 180K)
+    low     -> claude-sonnet-5  @ medium effort
+    mid     -> claude-opus-4-8  @ high effort (adaptive thinking)
+    high    -> claude-fable-5   @ xhigh effort (server-side fallback to Opus 4.8)
+"""
+
+from .classifier import Route, Tier, classify, heuristic_tier
+from .router import RefusalError, RoutedResult, build_request, execute, run
+
+__all__ = [
+    "Route",
+    "Tier",
+    "classify",
+    "heuristic_tier",
+    "RefusalError",
+    "RoutedResult",
+    "build_request",
+    "execute",
+    "run",
+]

claude_model_router-0.2.0/model_router/classifier.py

@@ -0,0 +1,123 @@
+"""Prompt-complexity classification for model routing.
+
+Two stages: a cheap Haiku 4.5 call for semantic tiering, with a
+keyword/size heuristic as fallback when the API call fails or returns
+something unparseable. The classifier call costs a few hundred tokens
+at $1/$5 per MTok — noise next to the downstream call it's routing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import anthropic
+
+Tier = Literal["trivial", "low", "mid", "high"]
+
+CLASSIFIER_MODEL = "claude-haiku-4-5"
+
+# Haiku 4.5 has a 200K context window (every other tier model has 1M);
+# trivial-tier work that arrives with more context than this gets bumped
+# to the low tier instead. Margin left for output and system prompt.
+_HAIKU_CONTEXT_LIMIT = 180_000
+
+# Complexity is judged from the head of the prompt plus size metadata;
+# feeding the whole prompt to the classifier would defeat its purpose.
+_CLASSIFY_SNIPPET_CHARS = 2000
+
+_CLASSIFIER_SYSTEM = """\
+You route coding prompts to one of four capability tiers. Reply with exactly one word.
+
+trivial - reformatting, extraction, classification, lookups with obvious answers
+low     - summaries, single-function edits, boilerplate, simple Q&A
+mid     - debugging, security review, tricky edge cases, single-file refactors
+high    - multi-file refactors, migrations, architecture design, codebase-wide optimization
+
+Reply with: trivial, low, mid, or high. Nothing else."""
+
+_HIGH_KEYWORDS = (
+    "migration",
+    "architecture",
+    "multi-file",
+    "optimize codebase",
+    "refactor across",
+)
+_MID_KEYWORDS = (
+    "debug",
+    "security audit",
+    "edge case",
+    "race condition",
+    "fuzzing",
+    "regex",
+)
+
+# effort None = model predates output_config.effort; omit the param.
+_TIER_ROUTES: dict[Tier, tuple[str, str | None]] = {
+    "trivial": ("claude-haiku-4-5", None),
+    "low": ("claude-sonnet-5", "medium"),
+    "mid": ("claude-opus-4-8", "high"),
+    "high": ("claude-fable-5", "xhigh"),
+}
+
+
+@dataclass(frozen=True)
+class Route:
+    model: str
+    effort: str | None
+    tier: Tier
+    source: str  # "classifier" | "heuristic" | "fixed" (caller-pinned route)
+
+
+def heuristic_tier(prompt: str, context_tokens: int = 0) -> Tier:
+    """Keyword/size fallback used when the classifier call fails.
+
+    Never returns "trivial": keywords can't reliably separate trivial
+    from low, and misrouting real work to Haiku costs more in retries
+    than the tier saves. Only the classifier may assign trivial.
+    """
+    p = prompt.lower()
+    if any(k in p for k in _HIGH_KEYWORDS) or context_tokens > 400_000:
+        return "high"
+    if any(k in p for k in _MID_KEYWORDS) or context_tokens > 100_000:
+        return "mid"
+    return "low"
+
+
+def classify(
+    client: anthropic.Anthropic, prompt: str, context_tokens: int = 0
+) -> Route:
+    """Classify a prompt into a route; never raises on classifier failure."""
+    tier: Tier | None = None
+    source = "classifier"
+    try:
+        response = client.messages.create(
+            model=CLASSIFIER_MODEL,
+            max_tokens=8,
+            system=_CLASSIFIER_SYSTEM,
+            messages=[
+                {
+                    "role": "user",
+                    "content": (
+                        f"context_tokens={context_tokens}\n---\n"
+                        f"{prompt[:_CLASSIFY_SNIPPET_CHARS]}"
+                    ),
+                }
+            ],
+        )
+        text = (
+            next((b.text for b in response.content if b.type == "text"), "")
+            .strip()
+            .lower()
+        )
+        if text in _TIER_ROUTES:
+            tier = text  # type: ignore[assignment]
+    except anthropic.AnthropicError:
+        pass
+    if tier is None:
+        tier = heuristic_tier(prompt, context_tokens)
+        source = "heuristic"
+    if tier == "trivial" and context_tokens > _HAIKU_CONTEXT_LIMIT:
+        tier = "low"
+    model, effort = _TIER_ROUTES[tier]
+    return Route(model=model, effort=effort, tier=tier, source=source)

claude_model_router-0.2.0/model_router/router.py

@@ -0,0 +1,97 @@
+"""Routed execution against the Messages API.
+
+Handles the per-model API differences a naive router misses:
+
+- Fable 5: thinking is always on (the param must be omitted), and
+  refusals arrive as HTTP 200 with stop_reason "refusal" — so requests
+  opt into the server-side fallback beta, which re-serves a declined
+  request on Opus 4.8 inside the same call.
+- Opus 4.8: thinking is OFF when omitted, so it is requested
+  explicitly as adaptive.
+- Sonnet 5: adaptive thinking is already the default when omitted;
+  sending it explicitly is harmless and keeps the code uniform.
+- All calls stream: xhigh turns can run minutes, and the SDK rejects
+  non-streaming requests at this max_tokens.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import anthropic
+
+from .classifier import Route, classify
+
+MAX_TOKENS = 64_000
+FALLBACK_BETA = "server-side-fallback-2026-06-01"
+FABLE_FALLBACK_MODEL = "claude-opus-4-8"
+
+
+class RefusalError(RuntimeError):
+    """Raised when a request is declined and no fallback rescued it."""
+
+    def __init__(self, stop_details: Any) -> None:
+        super().__init__(f"Request refused: {stop_details}")
+        self.stop_details = stop_details
+
+
+@dataclass(frozen=True)
+class RoutedResult:
+    text: str
+    route: Route
+    served_by: str  # actual model that answered; differs from route.model after a fallback
+    stop_reason: str | None
+    usage: Any = None  # response.usage — real token counts, for cost tracking
+
+
+def build_request(route: Route, messages: list[dict]) -> dict:
+    kwargs: dict = {
+        "model": route.model,
+        "max_tokens": MAX_TOKENS,
+        "messages": messages,
+    }
+    if route.effort is not None:
+        kwargs["output_config"] = {"effort": route.effort}
+    if route.model == "claude-fable-5":
+        kwargs["betas"] = [FALLBACK_BETA]
+        kwargs["fallbacks"] = [{"model": FABLE_FALLBACK_MODEL}]
+    elif route.model.startswith("claude-haiku"):
+        # Haiku 4.5 predates adaptive thinking and effort; sending either
+        # returns a 400. Thinking defaults off, which is right for trivial work.
+        pass
+    else:
+        kwargs["thinking"] = {"type": "adaptive"}
+    return kwargs
+
+
+def execute(
+    client: anthropic.Anthropic, route: Route, messages: list[dict]
+) -> RoutedResult:
+    kwargs = build_request(route, messages)
+    api = client.beta.messages if "betas" in kwargs else client.messages
+    with api.stream(**kwargs) as stream:
+        response = stream.get_final_message()
+    if response.stop_reason == "refusal":
+        raise RefusalError(getattr(response, "stop_details", None))
+    text = "".join(b.text for b in response.content if b.type == "text")
+    return RoutedResult(
+        text=text,
+        route=route,
+        served_by=response.model,
+        stop_reason=response.stop_reason,
+        usage=getattr(response, "usage", None),
+    )
+
+
+def run(
+    client: anthropic.Anthropic, prompt: str, context_tokens: int = 0
+) -> RoutedResult:
+    """Classify a prompt and execute it on the cheapest capable model.
+
+    Route once per conversation, not per turn: prompt caches are
+    model-scoped, so reuse the returned RoutedResult.route (via
+    execute()) for follow-up turns on the same conversation.
+    """
+    route = classify(client, prompt, context_tokens)
+    return execute(client, route, [{"role": "user", "content": prompt}])

claude_model_router-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "claude-model-router"
+version = "0.2.0"
+description = "Cost-aware model routing for the Claude API — reference implementation with a Claude Code subagent hook"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Juno Seong" }]
+requires-python = ">=3.10"
+dependencies = ["anthropic>=0.115"]
+keywords = ["claude", "anthropic", "llm", "model-routing", "cost-optimization"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/junoseong/claude-model-router"
+Repository = "https://github.com/junoseong/claude-model-router"
+Issues = "https://github.com/junoseong/claude-model-router/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["model_router"]

claude_model_router-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_model_router-0.2.0/tests/test_classifier.py

@@ -0,0 +1,94 @@
+import anthropic
+import pytest
+
+from model_router.classifier import CLASSIFIER_MODEL, classify, heuristic_tier
+from tests.conftest import FakeClient, FakeMessages, make_response, text_block, thinking_block
+
+
+class TestHeuristicTier:
+    def test_high_keyword(self):
+        assert heuristic_tier("plan the database migration to postgres") == "high"
+
+    def test_high_on_huge_context(self):
+        assert heuristic_tier("summarize this", context_tokens=500_000) == "high"
+
+    def test_mid_keyword(self):
+        assert heuristic_tier("debug this flaky test") == "mid"
+
+    def test_mid_on_large_context(self):
+        assert heuristic_tier("summarize this", context_tokens=150_000) == "mid"
+
+    def test_default_low(self):
+        assert heuristic_tier("what does this function return?") == "low"
+
+
+class TestTrivialTier:
+    def test_classifier_verdict_routes_to_haiku(self):
+        messages = FakeMessages(create_response=make_response([text_block("trivial")]))
+        route = classify(FakeClient(messages), "extract the date from this line")
+        assert (route.model, route.effort) == ("claude-haiku-4-5", None)
+        assert route.tier == "trivial"
+
+    def test_trivial_bumped_to_low_when_context_exceeds_haiku_window(self):
+        messages = FakeMessages(create_response=make_response([text_block("trivial")]))
+        route = classify(FakeClient(messages), "extract the date", context_tokens=190_000)
+        assert route.model == "claude-sonnet-5"
+        assert route.tier == "low"
+
+    def test_heuristic_never_assigns_trivial(self):
+        messages = FakeMessages(create_error=anthropic.AnthropicError("boom"))
+        route = classify(FakeClient(messages), "reformat this csv line")
+        assert route.source == "heuristic"
+        assert route.model == "claude-sonnet-5"
+
+
+class TestClassify:
+    def test_uses_classifier_verdict(self):
+        messages = FakeMessages(create_response=make_response([text_block("high")]))
+        route = classify(FakeClient(messages), "restructure everything")
+        assert (route.model, route.effort) == ("claude-fable-5", "xhigh")
+        assert route.source == "classifier"
+        assert messages.create_calls[0]["model"] == CLASSIFIER_MODEL
+
+    def test_verdict_whitespace_and_case_tolerated(self):
+        messages = FakeMessages(create_response=make_response([text_block("  Mid \n")]))
+        route = classify(FakeClient(messages), "anything")
+        assert (route.model, route.effort) == ("claude-opus-4-8", "high")
+
+    def test_skips_non_text_blocks(self):
+        messages = FakeMessages(
+            create_response=make_response([thinking_block(), text_block("low")])
+        )
+        route = classify(FakeClient(messages), "anything")
+        assert route.model == "claude-sonnet-5"
+
+    def test_garbage_verdict_falls_back_to_heuristic(self):
+        messages = FakeMessages(
+            create_response=make_response([text_block("extremely hard")])
+        )
+        route = classify(FakeClient(messages), "debug this crash")
+        assert route.source == "heuristic"
+        assert route.model == "claude-opus-4-8"
+
+    def test_empty_content_falls_back_to_heuristic(self):
+        messages = FakeMessages(create_response=make_response([]))
+        route = classify(FakeClient(messages), "quick question")
+        assert route.source == "heuristic"
+        assert route.model == "claude-sonnet-5"
+
+    def test_api_error_falls_back_to_heuristic(self):
+        messages = FakeMessages(create_error=anthropic.AnthropicError("boom"))
+        route = classify(FakeClient(messages), "plan the migration")
+        assert route.source == "heuristic"
+        assert route.model == "claude-fable-5"
+
+    def test_non_anthropic_errors_propagate(self):
+        messages = FakeMessages(create_error=ValueError("bug in caller"))
+        with pytest.raises(ValueError):
+            classify(FakeClient(messages), "anything")
+
+    def test_long_prompt_truncated_for_classifier(self):
+        messages = FakeMessages(create_response=make_response([text_block("low")]))
+        classify(FakeClient(messages), "x" * 50_000)
+        sent = messages.create_calls[0]["messages"][0]["content"]
+        assert len(sent) < 3_000

claude_model_router-0.2.0/tests/test_router.py

@@ -0,0 +1,127 @@
+import pytest
+
+from model_router.classifier import Route
+from model_router.router import (
+    FABLE_FALLBACK_MODEL,
+    FALLBACK_BETA,
+    MAX_TOKENS,
+    RefusalError,
+    build_request,
+    execute,
+    run,
+)
+from tests.conftest import FakeClient, FakeMessages, make_response, text_block, thinking_block
+
+FABLE_ROUTE = Route(model="claude-fable-5", effort="xhigh", tier="high", source="classifier")
+OPUS_ROUTE = Route(model="claude-opus-4-8", effort="high", tier="mid", source="classifier")
+SONNET_ROUTE = Route(model="claude-sonnet-5", effort="medium", tier="low", source="classifier")
+HAIKU_ROUTE = Route(model="claude-haiku-4-5", effort=None, tier="trivial", source="classifier")
+
+MSGS = [{"role": "user", "content": "hello"}]
+
+
+class TestBuildRequest:
+    def test_fable_gets_fallbacks_and_no_thinking(self):
+        kwargs = build_request(FABLE_ROUTE, MSGS)
+        assert kwargs["betas"] == [FALLBACK_BETA]
+        assert kwargs["fallbacks"] == [{"model": FABLE_FALLBACK_MODEL}]
+        assert "thinking" not in kwargs  # explicit thinking config 400s on Fable
+        assert kwargs["output_config"] == {"effort": "xhigh"}
+        assert kwargs["max_tokens"] == MAX_TOKENS
+
+    def test_opus_gets_adaptive_thinking_and_no_fallbacks(self):
+        kwargs = build_request(OPUS_ROUTE, MSGS)
+        assert kwargs["thinking"] == {"type": "adaptive"}
+        assert "betas" not in kwargs
+        assert "fallbacks" not in kwargs
+
+    def test_sonnet_gets_adaptive_thinking(self):
+        kwargs = build_request(SONNET_ROUTE, MSGS)
+        assert kwargs["thinking"] == {"type": "adaptive"}
+
+    def test_haiku_gets_no_thinking_no_effort_no_fallbacks(self):
+        kwargs = build_request(HAIKU_ROUTE, MSGS)
+        assert "thinking" not in kwargs  # adaptive thinking 400s on Haiku 4.5
+        assert "output_config" not in kwargs  # effort param 400s on Haiku 4.5
+        assert "betas" not in kwargs
+        assert "fallbacks" not in kwargs
+
+
+class TestExecute:
+    def test_fable_routes_through_beta_namespace(self):
+        beta = FakeMessages(
+            stream_response=make_response([text_block("answer")], model="claude-fable-5")
+        )
+        client = FakeClient(FakeMessages(), beta_messages=beta)
+        result = execute(client, FABLE_ROUTE, MSGS)
+        assert result.text == "answer"
+        assert len(beta.stream_calls) == 1
+        assert client.messages.stream_calls == []
+
+    def test_non_fable_uses_regular_namespace(self):
+        messages = FakeMessages(
+            stream_response=make_response([text_block("ok")], model="claude-opus-4-8")
+        )
+        client = FakeClient(messages)
+        result = execute(client, OPUS_ROUTE, MSGS)
+        assert result.text == "ok"
+        assert len(messages.stream_calls) == 1
+
+    def test_refusal_raises_with_details(self):
+        beta = FakeMessages(
+            stream_response=make_response(
+                [], stop_reason="refusal", stop_details={"category": "test"}
+            )
+        )
+        client = FakeClient(FakeMessages(), beta_messages=beta)
+        with pytest.raises(RefusalError) as exc:
+            execute(client, FABLE_ROUTE, MSGS)
+        assert exc.value.stop_details == {"category": "test"}
+
+    def test_text_extraction_skips_thinking_blocks(self):
+        messages = FakeMessages(
+            stream_response=make_response(
+                [thinking_block(), text_block("part1 "), text_block("part2")]
+            )
+        )
+        result = execute(FakeClient(messages), OPUS_ROUTE, MSGS)
+        assert result.text == "part1 part2"
+
+    def test_usage_passed_through_for_cost_tracking(self):
+        from types import SimpleNamespace
+
+        messages = FakeMessages(
+            stream_response=make_response(
+                [text_block("ok")],
+                usage=SimpleNamespace(input_tokens=123, output_tokens=456),
+            )
+        )
+        result = execute(FakeClient(messages), OPUS_ROUTE, MSGS)
+        assert result.usage.input_tokens == 123
+        assert result.usage.output_tokens == 456
+
+    def test_served_by_reports_fallback_model(self):
+        beta = FakeMessages(
+            stream_response=make_response(
+                [text_block("rescued")], model="claude-opus-4-8"
+            )
+        )
+        client = FakeClient(FakeMessages(), beta_messages=beta)
+        result = execute(client, FABLE_ROUTE, MSGS)
+        assert result.route.model == "claude-fable-5"
+        assert result.served_by == "claude-opus-4-8"
+
+
+class TestRun:
+    def test_classifies_then_executes(self):
+        messages = FakeMessages(
+            create_response=make_response([text_block("mid")]),
+            stream_response=make_response([text_block("done")], model="claude-opus-4-8"),
+        )
+        client = FakeClient(messages)
+        result = run(client, "debug this")
+        assert result.route.model == "claude-opus-4-8"
+        assert result.text == "done"
+        assert messages.stream_calls[0]["messages"] == [
+            {"role": "user", "content": "debug this"}
+        ]