diff --git a/README.md b/README.md index 92ba87e..1e18151 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@

- NadirClaw — Cut LLM & Agent Costs 40-70% + NadirClaw — the lowest viable model, verified.

NadirClaw

- Your simple prompts are burning premium tokens.
- NadirClaw routes them to cheaper models automatically. Save 40-70% on AI API costs. + The lowest viable model, verified.
+ NadirClaw routes every prompt to the cheapest model that can reliably answer, verifies the + output, and escalates only when it has to. Better answers, lower cost — 40–70% lower.

@@ -59,7 +60,23 @@ SIMPLE "Write a docstring" → gemini-flash $0.0002 > **Your keys. Your models. No middleman.** NadirClaw runs locally and routes directly to providers. No third-party proxy, no subsidized tokens, no platform that can pull the plug on you. [Why this matters.](docs/vs-clawrouter.md) -## Benchmarks +## How NadirClaw works + +

+ How NadirClaw works — Route, Verify, Escalate +

+ +Three moves, on every request: + +1. **Route** — a ~10ms embedding classifier predicts the *smallest* model likely to answer and sends the prompt there first. Routing modifiers (agentic tool loops, reasoning markers, vision content, long context) can override the score and force a stronger tier. +2. **Verify** — the cheap answer is scored against quality heuristics (refusals, truncation, JSON-format failures) before it ships. Pro swaps the heuristic for a trained DeBERTa cross-encoder. +3. **Escalate** — if the answer falls below the acceptance threshold (τ = 0.80), NadirClaw steps up to the next-best model automatically. You only pay for the big model when the small one wasn't enough. + +## Benchmarks — proof, not promises + +

+ NadirClaw benchmarks — −60% cost, 98.3% quality preserved, 0.961 verifier AUROC, ~10ms overhead +

NadirClaw and Nadir Pro share the same routing architecture. The numbers below are from the trained classifier + DeBERTa verifier in Nadir Pro; @@ -198,10 +215,6 @@ Monitor your routing in real-time with `nadirclaw dashboard`: Install the dashboard extras: `pip install nadirclaw[dashboard]` -

- NadirClaw Architecture -

- ## Prerequisites - **Python 3.10+** @@ -933,7 +946,7 @@ curl http://localhost:8856/v1/chat/completions \ ## Routing Intelligence — How NadirClaw Classifies Prompts

- Routing flow + Routing intelligence — how NadirClaw classifies a prompt

Beyond basic simple/complex classification, NadirClaw applies routing modifiers that can override the base decision: @@ -1215,33 +1228,16 @@ nadirclaw test --timeout 10 ## How It Works -NadirClaw sits between your application and the LLM provider as a transparent proxy: - -``` -┌─────────────────┐ -│ Your App │ -│ (Claude Code, │ -│ Cursor, etc) │ -└────────┬────────┘ - │ OpenAI API request - ▼ -┌─────────────────┐ -│ NadirClaw │ -│ Classifier │ -└────────┬────────┘ - │ Route decision (10ms) - ▼ -┌─────────────────┐ -│ LLM Provider │ -│ (Claude, GPT, │ -│ Gemini, etc) │ -└─────────────────┘ -``` +NadirClaw sits between your application and the LLM provider as a transparent local proxy. Your tools talk to it on `localhost`; it classifies, optimizes, verifies, and routes each request directly to the provider with your own keys — nothing passes through a third party. + +

+ NadirClaw architecture — a drop-in local proxy between your tools and the providers +

Most LLM usage doesn't need a premium model. NadirClaw routes each prompt to the right tier automatically:

- Typical LLM usage distribution + Where the prompts go — typical complexity mix

### Step-by-Step diff --git a/docs/images/architecture.png b/docs/images/architecture.png deleted file mode 100644 index 8082bca..0000000 Binary files a/docs/images/architecture.png and /dev/null differ diff --git a/docs/images/architecture.svg b/docs/images/architecture.svg new file mode 100644 index 0000000..7dd78ef --- /dev/null +++ b/docs/images/architecture.svg @@ -0,0 +1,91 @@ + + NadirClaw architecture — a drop-in local proxy + + + + + + + + + + + + + + + ARCHITECTURE — A DROP-IN LOCAL PROXY + + + + + + YOUR MACHINE · LOCALHOST + + + + YOUR TOOLS + + + Claude Code + Cursor · Continue + Aider · Windsurf + OpenClaw · Codex + Open WebUI + + …any OpenAI / Anthropic client + + + + + + + NADIRCLAW + :8856 + + + + + 1 + Classify + ~10ms · embeddings + + + 2 + Optimize context + 30–70% fewer tokens + + + 3 + Verify · cascade + escalate if needed + + logs · metrics · budgets — local JSONL + SQLite + + + + direct + your keys + + + + PROVIDERS + + + Anthropic — Claude + OpenAI — GPT · Codex + Google — Gemini (native) + Ollama — local, free + + 100 more via LiteLLM + + vLLM · LM Studio · DeepSeek … + + + + no middleman, no subsidized tokens — nothing routes through us. + diff --git a/docs/images/banner.png b/docs/images/banner.png deleted file mode 100644 index 1d3b1df..0000000 Binary files a/docs/images/banner.png and /dev/null differ diff --git a/docs/images/banner.svg b/docs/images/banner.svg new file mode 100644 index 0000000..ab495ea --- /dev/null +++ b/docs/images/banner.svg @@ -0,0 +1,98 @@ + + NadirClaw — the lowest viable model, verified. + + + + + + + + + + + + + + + + + + + + + + + + + + + OPEN SOURCE · SELF-HOSTED · YOUR KEYS + + nadirclaw + + + The lowest viable model, + verified. + + + Routes every prompt to the cheapest model that can reliably + answer — then verifies the output. Runs local. Your keys. + + built to route what matters. + + + + + + + + VERIFICATION RECEIPT + + + + + + + + + + gemini-flash + simple + $0.0002 + + + + haiku-4.5 + mid + $0.02 + + + + + + sonnet-4.6 + VERIFIED ✓ + $0.06 + + + + + opus-4.6 + not needed + $0.60 + + escalate only if needed + + + + QUALITY 98% + · + COST −60% + · + OVERHEAD ~10ms + diff --git a/docs/images/how-it-works.svg b/docs/images/how-it-works.svg new file mode 100644 index 0000000..114cd6c --- /dev/null +++ b/docs/images/how-it-works.svg @@ -0,0 +1,68 @@ + + How NadirClaw works — Route, Verify, Escalate + + + + + + + + + + + + + HOW NADIRCLAW WORKS + + + + + + + + 01 + ROUTE + start low + Predict the smallest model likely to + answer, and try that one first. + + + + + + + + + + + + 02 + VERIFY + quality first + Score the answer against quality + heuristics before it ships. + + + + + + + + + + 03 + ESCALATE + only if needed + If it falls short, step up to the + next-best model — automatically. + + + + + + + diff --git a/docs/images/proof.svg b/docs/images/proof.svg new file mode 100644 index 0000000..91e25ae --- /dev/null +++ b/docs/images/proof.svg @@ -0,0 +1,49 @@ + + Proof, not promises — RouterBench held-out benchmarks + + + + + + + + + + + + PROOF, NOT PROMISES + + + + + + + + + −60% + COST VS ALWAYS-OPUS + composed system cost + + + 98.3% + QUALITY PRESERVED + vs the always-Opus baseline + + + 0.961 + VERIFIER AUROC + ECE 0.016 · well-calibrated + + + ~10ms + ROUTING OVERHEAD + binary classifier, warm encoder + + + + RouterBench held-out · n = 11,420 · pre-generation classifier + cascade verifier at τ = 0.80 · catastrophic-downgrade 1.7% · full τ-sweep in MODEL_CARD.md + diff --git a/docs/images/routing-flow.png b/docs/images/routing-flow.png deleted file mode 100644 index d27d868..0000000 Binary files a/docs/images/routing-flow.png and /dev/null differ diff --git a/docs/images/routing-flow.svg b/docs/images/routing-flow.svg new file mode 100644 index 0000000..978b226 --- /dev/null +++ b/docs/images/routing-flow.svg @@ -0,0 +1,93 @@ + + Routing intelligence — how NadirClaw classifies a prompt + + + + + + + + + + + + + + + + ROUTING INTELLIGENCE — HOW A PROMPT IS CLASSIFIED + + + + + PROMPT SPECIMEN + + “now add tests + for the auth module” + 9 turns · 3 tools + + + + + + + + + ~10ms + CLASSIFIER + embedding centroid + + + ROUTING MODIFIERS — CAN OVERRIDE THE SCORE + + + agentic + + reasoning + + vision + + long context + + + + + + + + + + 0.0 + 1.0 + SIMPLE + MID + COMPLEX + + + score 0.91 + tools → forced complex + + + + + + + + + SIMPLE + gemini-flash + + + + MID + haiku-4.5 + + + COMPLEX ✓ + sonnet-4.6 + diff --git a/docs/images/social-preview.png b/docs/images/social-preview.png new file mode 100644 index 0000000..0d2160f Binary files /dev/null and b/docs/images/social-preview.png differ diff --git a/docs/images/social-preview.svg b/docs/images/social-preview.svg index 88d557b..91edbaf 100644 --- a/docs/images/social-preview.svg +++ b/docs/images/social-preview.svg @@ -1,41 +1,47 @@ - - + + NadirClaw — the lowest viable model, verified. - - - - - - - - + + + + + + - - - - - - - Open Source • MIT License - - - 🪝 - - - NadirClaw - - - LLM Router for Cost Optimization - - - Save 60% on API costs without sacrificing quality - - - ⚡ - <10ms - overhead - - - 🔐 - Self-hosted + + + + + + + + + + + + + + VERIFIED + + + + OPEN-SOURCE LLM ROUTER · SELF-HOSTED + + nadirclaw + + + The lowest viable model, verified. + + + Routes every prompt to the cheapest model that can answer — then verifies it. + + + + getnadir.com + −60% cost · 98% quality preserved · ~10ms diff --git a/docs/images/usage-distribution.png b/docs/images/usage-distribution.png deleted file mode 100644 index 72587a8..0000000 Binary files a/docs/images/usage-distribution.png and /dev/null differ diff --git a/docs/images/usage-distribution.svg b/docs/images/usage-distribution.svg new file mode 100644 index 0000000..70fcc6c --- /dev/null +++ b/docs/images/usage-distribution.svg @@ -0,0 +1,54 @@ + + Where the prompts go — typical complexity mix + + + + + + + + + + + + + WHERE THE PROMPTS GO + + + + + + + + + + + + + 55% + 25% + 15% + 5% + + + + Simple + reads, formatting · gemini-flash + + Mid + focused edits · haiku-4.5 + + Complex · agentic + refactors, tool loops · sonnet-4.6 + + Reasoning + chain-of-thought · o-series + + + + Representative coding-assistant mix — roughly 6–7 of every 10 prompts clear on a cheap model. Your numbers vary by workload. +