uncommon-route 0.5.0

Local LLM router that cuts premium-model spend with adaptive 3-tier routing, OpenAI + Anthropic compatible

English | 简体中文

UncommonRoute

Cut your LLM costs by 77% with automatic model routing.

Most of your LLM budget goes to simple tasks that don't need a premium model. UncommonRoute picks the cheapest model that still gets the job done — automatically.

Quick Start · How It Works · Benchmarks · Dashboard · Configuration

---

Quick Start

pip install uncommon-route

export UNCOMMON_ROUTE_UPSTREAM="https://api.openai.com/v1"  # or any OpenAI-compatible API
export UNCOMMON_ROUTE_API_KEY="your-key"
uncommon-route serve

Point your client at the proxy — one line change:

client = OpenAI(base_url="http://localhost:8403/v1")
resp = client.chat.completions.create(model="uncommon-route/auto", messages=msgs)
# → simple tasks → cheap model, complex tasks → premium model

Works with Codex, Claude Code, Cursor, the OpenAI SDK, and OpenClaw.

Client-specific setup

Client	Change
Codex / Cursor / OpenAI SDK	export OPENAI_BASE_URL="http://localhost:8403/v1"
Claude Code	export ANTHROPIC_BASE_URL="http://localhost:8403"
OpenClaw	Plugin — see openclaw.ai

---

How It Works

Every request is analyzed by three independent signals, then routed to the cheapest capable model:

"hello"                              → 🟢 nano         $0.0008
"fix the typo on line 3"             → 🟢 deepseek     $0.0012
"refactor this 500-line module"      → 🟠 sonnet       $0.0337
"design a distributed scheduler"     → 🔴 opus         $0.0562

Signal	What it does	Speed
Metadata	Conversation structure, tool usage, depth	<1ms
Embedding	Semantic similarity to known task patterns	~10ms
Structural	Text complexity features (shadow mode)	<1ms

Signals vote. The ensemble picks the tier. The router selects the cheapest model in that tier. If uncertain, it leans conservative — better to spend a little more than to fail the task.

It gets smarter over time. Signal weights adjust from routing outcomes. The embedding index grows with usage. Low-confidence predictions automatically escalate.

---

Why v2

Our v1 classifier hit 88.5% accuracy on clean benchmark data. We shipped it.

Then we tested on real agent conversations — multi-turn, tool-calling, messy context — and accuracy dropped to 43%. More than half the routing decisions were wrong.

We didn't patch it. We rebuilt from scratch.

	v1	v2
Accuracy	43%	72.7%
Task pass rate	100% (cheated — always chose most expensive)	90.3% (real routing)
Cost savings	0%	77%

We're telling you this because we'd rather you trust our numbers than be impressed by them.

---

Benchmarks

Tested on CommonRouterBench — 762 real agent task traces. All numbers measured end-to-end through the production code path.

Metric	Value
Cost savings	77% vs always-premium
Task pass rate	90.3%
Routing overhead	<10ms
Accuracy	72.7% tier match

python scripts/eval_v2.py  # reproduce it yourself

---

Dashboard

uncommon-route serve
# → http://localhost:8403/dashboard/

Real-time monitoring, interactive playground, cost tracking, and model routing configuration — all in a Nothing Design-inspired interface.

---

Configuration

Routing modes

Mode	Model ID	Behavior
auto	uncommon-route/auto	Balanced — best quality-per-dollar
fast	uncommon-route/fast	Cost-first — cheapest acceptable
best	uncommon-route/best	Quality-first — strongest available

Spend limits

uncommon-route spend set daily 20.00
uncommon-route spend status

BYOK (Bring Your Own Key)

uncommon-route provider add openai sk-your-key
uncommon-route provider add anthropic sk-ant-your-key

All environment variables

Variable	Meaning
UNCOMMON_ROUTE_UPSTREAM	Upstream OpenAI-compatible API URL
UNCOMMON_ROUTE_API_KEY	API key for the upstream
UNCOMMON_ROUTE_PORT	Local proxy port (default 8403)

---

Privacy

Runs entirely on your machine. No data leaves unless you opt in.

uncommon-route telemetry status

---

Development

git clone https://github.com/CommonstackAI/UncommonRoute.git
cd UncommonRoute && pip install -e ".[dev]"
python -m pytest tests -v

---

License

MIT — see LICENSE.