@blockrun/clawrouter 0.12.249 → 0.12.251
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -21
- package/dist/cli.js +946 -451
- package/dist/index.js +946 -451
- package/dist/router/index.js +910 -422
- package/docs/architecture.md +64 -50
- package/docs/configuration.md +63 -42
- package/docs/routing-profiles.md +90 -41
- package/package.json +2 -2
- package/skills/clawrouter/SKILL.md +11 -5
package/README.md
CHANGED
|
@@ -46,10 +46,10 @@ Every other LLM router was built for **human developers** — create an account,
|
|
|
46
46
|
|
|
47
47
|
ClawRouter is built for the agent-first world:
|
|
48
48
|
|
|
49
|
-
- **Starts at $0** — <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA models are free forever (incl.
|
|
49
|
+
- **Starts at $0** — <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA models are free forever (incl. reasoning-grade Step 3.7 Flash + a vision-capable Nemotron Omni)
|
|
50
50
|
- **No accounts** — a wallet is generated locally, no signup
|
|
51
51
|
- **No API keys** — your wallet signature IS authentication
|
|
52
|
-
- **No model selection** — <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension scoring picks the right model automatically
|
|
52
|
+
- **No model selection** — <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension scoring + constraint-first ranking ([router-core](https://github.com/BlockRunAI/router-core)) picks the right model automatically
|
|
53
53
|
- **No credit cards** — agents pay per-request with USDC via [x402](https://x402.org)
|
|
54
54
|
- **No trust required** — runs locally, <1ms routing, zero external dependencies
|
|
55
55
|
|
|
@@ -188,14 +188,12 @@ response = client.chat.completions.create(model="blockrun/auto", messages=[...])
|
|
|
188
188
|
|
|
189
189
|
Choose your routing strategy with `/model <profile>`:
|
|
190
190
|
|
|
191
|
-
| Profile
|
|
192
|
-
|
|
|
193
|
-
| `/model free`
|
|
194
|
-
| `/model auto`
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
| `/model eco` | Cheapest possible | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Maximum savings |
|
|
198
|
-
| `/model premium` | Best quality | 0% | Mission-critical |
|
|
191
|
+
| Profile | Strategy | Savings | Best For |
|
|
192
|
+
| ---------------- | ------------------ | ---------------------------------------------------------------------------------- | -------------------- |
|
|
193
|
+
| `/model free` | Free NVIDIA models | **100%** | $0 balance, learning |
|
|
194
|
+
| `/model auto` | Balanced (default) | **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->%** | General use |
|
|
195
|
+
| `/model eco` | Cheapest possible | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Maximum savings |
|
|
196
|
+
| `/model premium` | Best quality | 0% | Mission-critical |
|
|
199
197
|
|
|
200
198
|
**Shortcuts:** `/model grok`, `/model br-sonnet`, `/model gpt5`, `/model o3`
|
|
201
199
|
|
|
@@ -205,18 +203,31 @@ Choose your routing strategy with `/model <profile>`:
|
|
|
205
203
|
|
|
206
204
|
**100% local routing. <1ms latency. Zero external API calls.**
|
|
207
205
|
|
|
208
|
-
|
|
206
|
+
Routing decisions come from [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) — Router Core **V3.5**, the constraint-first portfolio router shared by every BlockRun product (ClawRouter, Franklin, the `@blockrun/llm` SDKs, ClawRouter-Hermes). ClawRouter inlines it at build time, pinned to an exact commit, and injects its live model catalog at startup.
|
|
209
207
|
|
|
210
208
|
```
|
|
211
|
-
Request →
|
|
209
|
+
Request → 15-dimension scorer → tier + task shape
|
|
210
|
+
→ hard filters (tools · vision · context · max-output · structured output)
|
|
211
|
+
→ rank survivors (quality · capability · cost · speed · reliability)
|
|
212
|
+
→ winner + ordered fallback chain → Response
|
|
212
213
|
```
|
|
213
214
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
|
215
|
+
1. **Classify** — a <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension weighted scorer picks a tier (`SIMPLE` / `MEDIUM` / `COMPLEX` / `REASONING`); a task classifier labels the shape of the work (`code_agent`, `tool_agent`, `reasoning_math`, `long_context`, `vision`, …). Turns that actually need their tools switch to agent-tuned tiers automatically.
|
|
216
|
+
2. **Filter** — every model that cannot satisfy the request is dropped _before_ anything is scored. A model that can't call tools, can't read the image, or can't hold the conversation never gets to win on price.
|
|
217
|
+
3. **Rank** — survivors are scored on task quality, capability, estimated cost, speed and reliability, with per-profile weights (`eco` leans on cost, `premium` on quality and reliability).
|
|
218
|
+
4. **Recover** — the whole ranked list rides along as the fallback chain, so a provider timeout or 5xx costs a retry, not the task.
|
|
219
|
+
|
|
220
|
+
| Tier | ECO Model | AUTO Model | PREMIUM Model | AGENTIC Model ‡ |
|
|
221
|
+
| --------- | ------------------------------- | ------------------------------- | ---------------------------- | ------------------------- |
|
|
222
|
+
| SIMPLE | step-3.7-flash (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | gemini-3.5-flash ($1.50/$9) | gpt-4o-mini ($0.15/$0.60) |
|
|
223
|
+
| MEDIUM | glm-5.3-flash ($0.15/$0.50) | gemini-3.5-flash ($1.50/$9) | gpt-5.3-codex ($1.75/$14.00) | gpt-5-mini ($0.25/$2) |
|
|
224
|
+
| COMPLEX | glm-5.3-flash ($0.15/$0.50) | gemini-3.1-pro ($2/$12) | claude-fable-5 ($10/$50) | claude-sonnet-5 ($3/$15) |
|
|
225
|
+
| REASONING | deepseek-reasoner ($0.14/$0.28) | deepseek-reasoner ($0.14/$0.28) | claude-sonnet-5 ($3/$15) | claude-sonnet-5 ($3/$15) |
|
|
226
|
+
|
|
227
|
+
† Withheld from `/v1/models` — since Router Core V3.5 no chain names such a model: every primary and every fallback rung above is a model you can find on the public pricing page. [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json) prices the published savings claim on the same visible models.
|
|
228
|
+
‡ Auto-selected in any profile when the turn actually needs its attached tools; prefers models that keep going instead of stopping to ask.
|
|
229
|
+
|
|
230
|
+
These are the curated primaries; every tier carries a benchmark-ordered fallback chain — full chains and per-profile ranking weights in [docs/routing-profiles.md](docs/routing-profiles.md). On router-core's frozen three-arm agent benchmark (τ-bench, BrowseComp, Terminal-Bench) the V3.4 policy (the last one benchmarked; V3.5 is a catalog refresh on the same scorer and weights) completed **57%** of tasks vs **49%** for the previous rules router, at **6.4%** lower cost per successful task — and spent **8.9%** of the tokens a pinned flagship would have.
|
|
220
231
|
|
|
221
232
|
**<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5** for the same traffic, on `auto`; **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** on `eco`.
|
|
222
233
|
|
|
@@ -227,6 +238,8 @@ answer. Models withheld from `/v1/models` are excluded from the mix — pricing
|
|
|
227
238
|
public claim on a model you cannot look up is not defensible — which makes the
|
|
228
239
|
number conservative.
|
|
229
240
|
|
|
241
|
+
Rollback lever: `routing.strategy: "rules"` restores the V2 primary-first selector; `routing.shadow` compares both locally without a second paid call.
|
|
242
|
+
|
|
230
243
|
---
|
|
231
244
|
|
|
232
245
|
## Image Generation
|
|
@@ -434,7 +447,6 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
434
447
|
| google/gemini-3-flash-preview | $0.50 | $3.00 | $0.0018 | 1M | vision |
|
|
435
448
|
| moonshot/kimi-k2.5 | $0.60 | $3.00 | $0.0018 | 262K | reasoning, vision, agentic, tools |
|
|
436
449
|
| moonshot/kimi-k2.7 | $0.95 | $4.00 | $0.0025 | 262K | reasoning, vision, agentic, tools |
|
|
437
|
-
| moonshot/kimi-k3 | $3.00 | $15.00 | $0.0110 | 1M | reasoning, vision, agentic, tools |
|
|
438
450
|
|
|
439
451
|
### Mid-Range Models ($0.001–$0.01/request)
|
|
440
452
|
|
|
@@ -478,13 +490,14 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
478
490
|
| openai/gpt-5.6-sol | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
|
|
479
491
|
| openai/gpt-5.6-sol-pro | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
|
|
480
492
|
| openai/gpt-5.5 | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
|
|
493
|
+
| moonshot/kimi-k3 | $3.00 | $15.00 | $0.0110 | 1M | reasoning, vision, agentic, tools |
|
|
481
494
|
| openai/chat-latest | $5.00 | $30.00 | $0.0175 | 128K | vision, tools |
|
|
482
495
|
| openai/o1 | $15.00 | $60.00 | $0.0375 | 200K | reasoning, tools |
|
|
483
496
|
| openai/gpt-5.2-pro | $21.00 | $168.00 | $0.0945 | 400K | reasoning, tools |
|
|
484
497
|
| openai/gpt-5.4-pro | $30.00 | $180.00 | $0.1050 | 400K | reasoning, tools |
|
|
485
498
|
| openai/gpt-5.5-pro | $30.00 | $180.00 | $0.1050 | 1M | reasoning, vision, tools |
|
|
486
499
|
|
|
487
|
-
> **Free tier:**
|
|
500
|
+
> **Free tier:** <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA-hosted models cost nothing — `/model free` pins the free default (`step-3.7-flash`, with the other four as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model nemotron-omni` for vision, `/model step-flash` for reasoning, `/model mistral-nemotron` for instruction following).
|
|
488
501
|
> **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.
|
|
489
502
|
|
|
490
503
|
---
|
|
@@ -700,7 +713,7 @@ Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:m
|
|
|
700
713
|
| [Documentation](https://blockrun.ai/docs) | Full docs |
|
|
701
714
|
| [Model Pricing](https://blockrun.ai/models) | All models & prices |
|
|
702
715
|
| [Image Generation & Editing](docs/image-generation.md) | API examples, <!-- br:models.image -->9<!-- /br:models.image --> models |
|
|
703
|
-
| [Routing Profiles](docs/routing-profiles.md) | ECO/AUTO/PREMIUM
|
|
716
|
+
| [Routing Profiles](docs/routing-profiles.md) | ECO/AUTO/PREMIUM/AGENTIC tiers, fallback chains, ranking weights |
|
|
704
717
|
| [Architecture](docs/architecture.md) | Technical deep dive |
|
|
705
718
|
| [Configuration](docs/configuration.md) | Environment variables |
|
|
706
719
|
| [Troubleshooting](docs/troubleshooting.md) | Common issues |
|