ultrarouter docs
Concepts

The five products

Router, Evals, Scoring, Flywheel and Context — five capabilities on one outcome ledger and one evidence gate, reached through two parallel entry actions, each with its honest availability.

ultrarouter is five capabilities on one ledger and one gate, not five products you have to wire up. You pick a job — migrate a model, or build a data flywheel — and the capabilities sit behind it. This page names all five, says what each is for and how far each is built, and links to where each one is documented in depth.

Two ways in

Migration and Flywheel are parallel offers. Start with either; neither is a prerequisite for the other.

  • Plan a model migration — import your usage history, scope a swap, and get a decision pack with the config diff and rollout checklist. Built on the paired Scoring comparison, the qualified evaluators and the auto-rollback canary. See Plan a model migration.
  • Build your data flywheel — connect the outcomes your product already generates, confirm what "it worked" means for one workflow, and carry a learned improvement through your own CI and a live comparison you own. See The Flywheel.

The first complete correction-to-application-to-live learning loop is the primary new milestone — but a migration sale is never required to use or evaluate the Flywheel.

The five capabilities

CapabilityWhat it isAvailability
RouterOne OpenAI/OpenRouter-compatible URL across providers: BYOK, fallbacks, spend caps, streaming and tools, with a documented config-precedence chain.Available today
EvalsEvaluators generated from your traffic and proved to catch defects, gating every change from PR to canary to rollback.Available today
ScoringWhich model holds your quality bar at what cost per successful task — a paired, signed, refusable comparison (ultrarouter Bench).Available today
FlywheelThe outcome ledger: what happened next to every answer, learned into rules and examples behind a holdout, training-ready and customer-owned.Preview — local stack only; the mechanisms are built, see the guides for each milestone's boundary
ContextDeterministic context assembly with a manifest: modules, contracts, budgets and lazily loaded SOPs. The gateway is a witness of the manifest, never its author.Planned — documented separately as it ships

Every availability label is honest, and it is repeated wherever a capability appears. Any improvement claim we publish carries its scope, sample size and confidence interval, or it does not appear.

Router

The drop-in proxy. Point your existing OpenAI or OpenRouter SDK at the gateway base URL, keep your messages, and you are done: POST /v1/chat/completions (streaming and non-streaming), POST /v1/embeddings, GET /v1/models. Behind that one URL are BYOK provider keys, pinned / multi-offer / auto routing, a compression safety taxonomy (off by default), and a savings ledger that computes honest, procurement-defensible numbers. Every request records which layer decided each field.

Evals

Continuous, judge-backed evaluation. Evaluators are drafted from the shape of your traffic, qualified against a labeled set, and then used to gate changes — a candidate model or prompt has to clear them before a canary promotes it, and a dip rolls it back automatically. See Evals.

Scoring — ultrarouter Bench

A paired benchmark you can defend. Tag your own dev/test traffic with a suite, freeze an immutable weighted dataset, run your incumbent paired against challengers, and read an immutable evidence report — quality and all-in cost intervals, a trust class, and a keep / migrate / inconclusive verdict — then gate CI on it. The honesty rules (dataset cards, power plans, the estimate-vs-provider-reported distinction) are first-class. Start at the Bench quickstart.

Flywheel

Preview — not on the hosted service

The data flywheel and the learning loop run on the local stack only. They are off on the invite-only hosted gateway (the learning.enabled master switch), there is no hosted MCP endpoint, and whether learning improves a given agent is not yet demonstrated. See the evidence status.

The newest capability, and the one this documentation set completes. The Flywheel captures typed outcome events over six channels, joins each to the answer that produced it, and — only after you confirm what "it worked" means — turns consented, teaching-eligible outcomes into rules and examples your app can consult, tested behind a standing holdout and exported back to you as a training-ready dataset. We train models only for your own workspace — never a shared or cross-workspace one. The switches and the train_allowed enforcement are built; what is not built is a governed trainer, so no training run executes yet. Two laws make it trustworthy: a proposed objective never teaches (a compiler guarantee) and the holdout is sacred (no lever ever reads it). Read The Flywheel for the loop and the boundaries.

Context

A pure context runtime: deterministic assembly of context modules under contracts and token budgets, with SOP catalogs that load lazily instead of pasting everything into every prompt. It is the controlled-delivery path for the rules and examples the Flywheel learns. The gateway is a witness of the ur.manifest a request carries, never its author, and the exit function is pure — you can adopt the runtime in one file and leave it in one file. Context has its own concept and guide pages, published as that surface ships; this page names it so the set of five is complete and honest.

One ledger, one gate

What makes these five a system rather than a bundle is that they share one outcome ledger and one evidence gate. A Scoring comparison, an Evals qualification, a Flywheel live confirmation and a migration verdict all reference the same immutable cost and quality lineage — there is no parallel recomputation with a different cost basis, and a figure shown by a gate, a leaderboard, a report, a statement or an export always traces to the same evidence. Your data stays tenant-isolated and fully exportable, and raw items never cross a workspace; we train models only for your own workspace.

Next steps