UncommonRoute

UncommonRoute is a local, purpose-built router that sits between your client and your upstream API, redefining how you allocate costly AI model power across a workflow. It is designed to route requests by difficulty rather than habit, ensuring that easy turns stay inexpensive while hard turns receive stronger computational support when it truly matters. It is a lightweight, model-agnostic layer that does not host models itself; instead, it makes fast local routing decisions, forwards requests to your chosen upstream provider, and maintains a resilient fallback strategy so your system remains robust even when model names shift or availability fluctuates.

In the header of the project’s documentation, you’ll notice a curated set of badges that visually communicate the project’s status and compatibility: a badge indicating Python 3.11+ compatibility, a Modified MIT license badge, a CI status badge, and readiness indicators for Claude Code, Codex, Cursor, and OpenClaw. These visuals aren’t just decorative; they signal to developers at a glance which ecosystems and runtimes are supported and how actively the project is maintained. The presence of OpenClaw as a plugin highlights the broader ecosystem integrations possible with UncommonRoute, signaling a concrete path for teams that want to weave the router into their existing agent frameworks or tooling.

The core premise is simple but powerful: maintain one local endpoint and let the router decide when a strong model is genuinely worth paying for. The readme paints a clear picture of the “Expensive Default” problem—most AI toolchains assume every request deserves the strongest model, and that assumption inflates costs through routine turns that may not materially improve outcomes. UncommonRoute proposes a counter-model: a fast, local decision layer that assigns a difficulty-informed routing path to each request, forwards the payload to an upstream provider, and keeps a cautious set of fallbacks to recover when the chosen model is unavailable or misaligned with the task.

The routing logic is not about hard rules or keyword lists. It is a data-driven, continuous signal system. A local classifier estimates a difficulty score on a 0.0 to 1.0 scale by analyzing structural features and patterns of the user’s prompt, including short-term n-gram signals. This score feeds a quality prediction formula that determines the downstream model selection. Tiers such as SIMPLE, MEDIUM, and COMPLEX exist as display labels in logs, headers, and dashboards, but the routing decisions themselves hinge on the continuous score. This avoids rigid tier boundaries and promotes a smoother, more adaptive balance between cost and quality.

Three routing modes shape the behavior you’ll see in practice: auto, fast, and best. In auto mode, UncommonRoute aims for the best quality per dollar, adjusting its preference as difficulty increases. In fast mode, cost dominates, selecting the cheapest model that still meets a minimum threshold of usefulness. In best mode, the priority is maximal quality, with cost largely secondary. Virtual model IDs like uncommon-route/auto, uncommon-route/fast, and uncommon-route/best trigger the router’s decision logic, while explicit real model IDs pass through unchanged. The system automatically amplifies the weight of quality versus cost as tasks become harder, ensuring that tougher prompts are more likely to see higher-quality, more expensive models when it makes sense.

Quality is benchmark-driven rather than price-based. UncommonRoute leverages real benchmark data from PinchBench to anchor model quality expectations. This is blended with observed experience via Bayesian updating, so the system starts with vetted benchmarks and then adapts as real-world performance accumulates. The live selector uses Thompson Sampling, a principled method to balance exploration and exploitation across the pool of models. Models with fewer observations are assigned broader distributions, giving them a fair opportunity to prove their merit over time. This approach helps avoid premature conclusions about a model’s worth solely on price or initial impressions.

Learning within the system happens on three layers. The benchmark prior comes from PinchBench data and seed information, providing baseline quality expectations for the model pool. Implicit feedback is gathered automatically from HTTP failures, retrial patterns, and log-probability confidences, turning every request into a signal about how well a model is performing in practice. Explicit feedback is user-driven: a simple three-click feedback loop can alter routing decisions, enabling immediate corrections if the selected path proves unsatisfactory. This combination of data sources supports a robust, evolving routing strategy that improves with experience while remaining anchored to verified performance benchmarks.

In practice, UncommonRoute is designed to be easy to prove locally before connecting to live upstreams. The Quick Start guide walks through a staged approach. First, install the package with a straightforward command, then validate local routing without any real API keys or upstreams. This proves that the package is installed correctly, the local classifier can produce a tier and a model choice, and the fallback chain logic operates as intended. The next step is to point the router at a real upstream: export the appropriate environment variables for your provider (such as Commonstack, OpenAI, or a local OpenAI-compatible server like Ollama or vLLM). With the upstream configured, you start the proxy and observe health indicators, a dashboard URL, and a health-check command to verify end-to-end readiness.

Connecting your client—whether Codex, Claude Code, Cursor, or an OpenAI SDK-based workflow—follows a pattern. For Codex and Claude Code, the setup involves specialized commands or manual environment variable adjustments to align the client with a local OpenAI-compatible base URL or Anthropic-style endpoint. The router supports multiple client paradigms with concrete guidance for OpenAI SDKs and Cursor, plus a plugin pathway via OpenClaw. The OpenClaw pathway is particularly notable: a plugin-based integration that can install and restart a gateway, register a local OpenClaw provider, and synchronize upstream mappings into OpenClaw once a model mapping endpoint is available. This design makes it feasible to slot UncommonRoute into existing toolchains with minimal friction.

A central feature is the dashboard, accessible after the proxy is running, that provides human-friendly visibility into request counts, latency, cost savings, and mode distributions. The dashboard exposes the upstream transport, cache behavior, and the live routing state, alongside stored default modes and tier overrides. It also reveals recent traffic, spending patterns, and feedback results. When things go awry, the system offers a suite of diagnostic commands through a built-in doctor tool, enabling quick problem diagnosis. The configuration and operational commands emphasize observability and recoverability, with options to view and modify routing configurations, see current spending status, and inspect or reset recent activity.

Configuration that actually matters is primarily environmental. The upstream endpoint is declared through UNCOMMONROUTEUPSTREAM, with an optional API key UNCOMMONROUTEAPIKEY if the provider requires authentication. The local port is configurable, defaulting to 8403, and there is a policy hook for a composition policy via UNCOMMONROUTECOMPOSITIONCONFIG or its inline JSON counterpart. The system looks up the live primary upstream in a well-defined precedence: CLI flags, then environment variables, then file-based settings saved from the dashboard. This separation helps teams manage configuration across development, staging, and production without losing control over the primary connection.

A BYOK (Bring Your Own Key) workflow is supported for teams that want to constrain the router to use models backed by their own provider credentials. The process is explicit: add providers and associated keys, review the provider catalog, and inspect the live mapping to understand how virtual models align with upstream offerings. The router’s endpoint exposure and header signals provide rich visibility: routed requests may emit headers like x-uncommon-route-model, x-uncommon-route-tier, x-uncommon-route-mode, x-uncommon-route-step, and x-uncommon-route-reasoning. Non-virtual passthrough requests, which pass explicit non-virtual IDs, may not populate all of these headers, but the informational signals remain a strong guide for understanding how routing decisions were reached.

Spend control is an essential feature for cost management. UncommonRoute provides mechanisms to cap spending per request, hourly, daily, and per session. The system records spend history in a local file, and if a spend limit is breached, the proxy can respond with an HTTP 429 and a reset timer, ensuring that cost ceilings are not breached inadvertently. The spending data, as with other local state, is designed to be portable and inspectable, stored under a local data directory such as ~/.uncommon-route, with the exact directory configurable via environment variables.

For integration and developer workflows, UncommonRoute offers a compact set of endpoints and a clear base URL policy. Client types like OpenAI-compatible clients, Anthropic-style clients, and others have defined base URLs for interaction through the router, and virtual model IDs provide a simple way to trigger internal routing logic. Practical endpoints included in the suite cover health checks, model mappings, connections, routing configurations, statistics, selectors, and feedback, enabling a complete, end-to-end operational picture. In addition to health and status, useful headers on routed requests help track how a particular decision was made, including the model, tier, mode, and reasoning signals.

Beyond the core routing engine, there are advanced features that deepen the router’s capabilities. Model discovery and mapping reconcile different upstream model IDs with internal identifiers, building a live pool when possible and offering mapping insights through the v1/models/mapping endpoint. The composition pipeline handles large tool outputs gracefully, enabling the proxy to compact oversized content, offload results to artifacts locally, create semantic summaries, checkpoint long histories, and rehydrate artifact references on demand. Artifacts are stored locally, making large results more manageable while preserving access to original outputs when needed. The proxy even supports Anthropic-native transport semantics, enabling native handling for Anthropic-style requests while preserving the OpenAI-like interface.

Local training of the classifier is supported, allowing teams to adapt the routing behavior to their own benchmark data if desired. The training script can be invoked to produce a retrained model, with the resulting experience data stored locally. This underscores the system’s design philosophy: a local, privacy-preserving classifier that evolves with your data and use cases, without depending on external telemetry to function effectively.

Troubleshooting guidance in the documentation addresses common friction points. If a route decision appears correct but the app does not receive a response, the issue is likely upstream connectivity, credentials, or misconfiguration rather than a routing fault. For Codex or Cursor connections, ensuring that the base URL ends with /v1 is a frequent source of friction, while Anthropic-style clients should point to the router root rather than a /v1 path. The doctor command remains a handy first step in diagnosing misconfigurations, discovery gaps, or connectivity issues, and it is typically the fastest route to a resolution.

Benchmarks in the project emphasize two pillars: classifier accuracy and real-world cost savings. The v2 classifier, which blends structural features with n-gram signals, demonstrates impressive training and held-out accuracy, while still acknowledging that the classifier is not the sole determinant of routing decisions—the live quality signal comes from benchmark-based expectations and on-going observations. End-to-end testing with Claude Code and Commonstack upstream reports substantial cost reductions—estimates hover around 90-95% savings compared with always using premium models. The results also show high task success across a spectrum of difficulty levels, with multiple models engaged through Thompson Sampling, and a diverse set of models selected over numerous prompts. The project emphasizes reproducibility, with concrete steps to reproduce benchmark runs and to audit the evaluation pipeline.

From a structural perspective, the repository layout supports a clear separation of concerns. The core runtime lives in uncommon_route, which handles the proxying, routing, and calibration logic. A separate bench directory stores offline evaluation data and scripts, while a demo directory provides local comparison apps. The frontend directory contains dashboard and demo frontends, and the root-level API is kept for compatibility with the demo server while preserving a clean boundary around the runtime. This modular organization reflects the design intent: a focused, pluggable proxy with rich observability and a friendly developer experience for integration, testing, and benchmarking.

When you want to turn it off or remove it, UncommonRoute provides a straightforward path. You can stop the local proxy, clear local records, or fully uninstall, with clear steps to restore client configuration afterward. The documentation emphasizes that stopping or uninstalling the proxy does not automatically revert your client’s settings; you must switch your client back to its original base URL or directly adjust environment variables to point away from the local router. The guidance includes explicit commands for each mode of shutdown or removal, including how to handle local data directories, how to back them up, and how to perform a clean removal of plugins such as OpenClaw integration if you had wired them in.

For developers who want to contribute or explore further, the development workflow is clearly outlined. Cloning the repository, installing in editable mode, and running the test suite with pytest is the recommended path. The documentation notes that the current test suite comprises hundreds of passing tests, illustrating a mature and stable set of checks that cover behavior, performance, and integration concerns. The license remains MIT-style, with the “Modified MIT” label signaling practical permissiveness while acknowledging the project’s customization and added tooling.

In summary, UncommonRoute embodies a pragmatic philosophy for modern AI workflows: spend premium-model money where it truly affects the outcome, and conserve resources where inexpensive routes suffice. It combines a local, continuously learning classifier with a flexible routing policy, benchmark-driven quality signals, and explicit, auditable spending controls. It offers multiple client integration paths, sophisticated model discovery and mapping, an artifact-capable composition pipeline, and seamless plugin pathways through ecosystems like OpenClaw. The emphasis on visibility, control, and repeatable diagnostics makes it a compelling solution for teams seeking cost discipline without sacrificing the quality of their AI-assisted workflows.

The project’s emphasis on practical engineering—local routing, continuous learning, and user-driven feedback—resonates with teams building scalable, responsible AI systems. It delivers a robust framework for preserving budget while maintaining strong performance, especially in pipelines that routinely juggle simple queries with demanding tasks. This balance is the core value proposition: a single local router that intelligently chooses when to invest in stronger models, guided by real benchmarks, explicit feedback, and a transparent, auditable decision history. The result is a system that feels both principled and pragmatic—a tool designed to optimize the economics of AI use without compromising the flexibility and capability that modern language models provide.