> For the complete documentation index, see [llms.txt](https://docs.commonstack.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commonstack.ai/user-guide/smart-routing.md).

# Smart Routing (UncommonRoute)

UncommonRoute is an open-source local routing layer that sits between your AI client and your upstream API. Instead of sending every request to the same model, it scores each prompt by difficulty and routes it to the most cost-effective model that can handle it well.

Easy turns go cheap. Hard turns go strong. The result is significantly lower spend with no change to your existing client setup.

```
Your client
  (Claude Code / Codex / Cursor / OpenAI SDK / OpenClaw)
            |
            v
     UncommonRoute
   (runs on your machine)
            |
            v
    Your upstream API
 (Commonstack / OpenAI / Ollama / vLLM / ...)
```

UncommonRoute does not host models. It makes a fast local routing decision, then forwards the request to your configured upstream.

***

### How It Works

#### Difficulty scoring, not keyword matching

UncommonRoute uses a local ML classifier (structural features + character n-grams) to estimate a continuous difficulty score from 0.0 to 1.0 for each prompt. There are no hardcoded keyword lists or rule sets. The score drives model selection through a quality prediction formula.

Tiers (`SIMPLE` / `MEDIUM` / `COMPLEX`) appear in logs and the dashboard as display labels derived from the score, but they are not routing decisions themselves.

Importantly, tool presence in an agentic request does not inflate difficulty. A simple prompt sent through Claude Code still routes as `SIMPLE`.

#### Routing modes

Set your preferred routing mode using a virtual model ID:

| Model ID              | Optimizes for                                   |
| --------------------- | ----------------------------------------------- |
| `uncommon-route/auto` | Best quality-per-dollar, adapts with difficulty |
| `uncommon-route/fast` | Cheapest acceptable model                       |
| `uncommon-route/best` | Highest quality, cost nearly ignored            |

Only these virtual IDs trigger routing. Explicit real model IDs pass through unchanged.

#### Benchmark-driven model selection

Model quality scores come from [PinchBench](https://pinchbench.com/) agent task benchmarks, not price assumptions. The selector uses Thompson Sampling (Beta distribution per model) for exploration-exploitation balance, and blends benchmark priors with observed real-world performance through Bayesian updating.

#### Three layers of feedback

| Layer             | Source                                               | What it learns                                  |
| ----------------- | ---------------------------------------------------- | ----------------------------------------------- |
| Benchmark prior   | PinchBench + seed data                               | Model quality baselines                         |
| Implicit feedback | HTTP failures, retrial detection, logprob confidence | Automatic quality signals from every request    |
| Explicit feedback | User ok / weak / strong signals                      | Direct corrections (3 clicks to change routing) |

***

### Quick Start

#### 1. Install

```bash
pip install uncommon-route
```

#### 2. Test the classifier locally

This step does not require an upstream or API key.

```bash
uncommon-route route "write a Python function that validates email addresses"
uncommon-route debug "prove that sqrt(2) is irrational"
```

This confirms the package is installed and the local classifier is working. It does not test your upstream connection.

#### 3. Configure your upstream

```bash
# Commonstack: one key, access to models from multiple providers
export UNCOMMON_ROUTE_UPSTREAM="https://api.commonstack.ai/v1"
export UNCOMMON_ROUTE_API_KEY="csk-..."
```

```bash
# OpenAI direct
export UNCOMMON_ROUTE_UPSTREAM="https://api.openai.com/v1"
export UNCOMMON_ROUTE_API_KEY="sk-..."
```

```bash
# Local OpenAI-compatible server (Ollama, vLLM, etc.)
export UNCOMMON_ROUTE_UPSTREAM="http://127.0.0.1:11434/v1"
```

#### 4. Start the proxy

```bash
uncommon-route serve
```

The startup banner shows the upstream host, local proxy URL, dashboard URL, and a quick health-check command. If the upstream is not configured, it tells you which variables to set.

#### 5. Connect your client

**Claude Code**

```bash
uncommon-route setup claude-code
```

Or manually:

```bash
export ANTHROPIC_BASE_URL="http://localhost:8403"
export ANTHROPIC_API_KEY="not-needed"
```

Note: `ANTHROPIC_BASE_URL` should point at the router root, not `/v1`.

**Codex / Cursor / OpenAI SDK**

```bash
uncommon-route setup codex
```

Or manually:

```bash
export OPENAI_BASE_URL="http://localhost:8403/v1"
export OPENAI_API_KEY="not-needed"
```

Note: `OPENAI_BASE_URL` must end with `/v1`.

Python example:

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8403/v1",
    api_key="not-needed",
)

response = client.chat.completions.create(
    model="uncommon-route/auto",
    messages=[{"role": "user", "content": "hello"}],
)
```

For Cursor, point "OpenAI Base URL" to `http://localhost:8403/v1`.

**OpenClaw**

```bash
openclaw plugins install @anjieyang/uncommon-route
openclaw gateway restart
```

#### 6. Verify

```bash
uncommon-route doctor
curl http://127.0.0.1:8403/health
```

`uncommon-route doctor` is the recommended first step whenever something feels off.

***

### Dashboard

After starting the proxy, open `http://127.0.0.1:8403/dashboard/` to monitor:

* Request counts, latency, cost, and savings
* Mode, tier, and model distribution
* Selector state and stored routing overrides
* Recent traffic, spend limits, and feedback state

***

### Spend Controls

```bash
uncommon-route spend set per_request 0.10
uncommon-route spend set hourly 5.00
uncommon-route spend set daily 20.00
uncommon-route spend status
```

When a limit is hit, the proxy returns HTTP `429` with `reset_in_seconds`.

***

### Further Reading

* [UncommonRoute on GitHub](https://github.com/CommonstackAI/UncommonRoute)
* [PinchBench](https://pinchbench.com/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commonstack.ai/user-guide/smart-routing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.