Riven Ultra Router
LiveAlias resolution and failover for every inference request. Turns a stable model name into a healthy pool, on-prem first and cloud second.
Ultra Router sits between the API and the models. Its job is to accept a name your integration will never have to change, and resolve it to something that is actually healthy right now.
Alias resolution#
A model ID in a request is an *alias*, not a machine. riven-core names an intent — balanced quality and speed — and the router decides which concrete model serves it. That indirection is why Riven can upgrade a backend without asking anyone to edit code, and why alias IDs outnumber the 75 live models.
| You send | Router resolves to | Stability promise |
|---|---|---|
A tier alias such as riven-core or riven-best | Whichever pool currently serves that intent best | The name and intent are stable; the backend may be upgraded at any time |
An exact model ID such as claude-opus-4-7 | That model, or an error if it is unavailable | Pinned. Deprecated only with notice |
Explicit model picks are never silently rewritten. If a request pins a model, it gets that model or it gets an error — the router will not substitute quietly. When a *generic* alias is upgraded by smart routing, the response says so with an x-riven-smart-route header.
On-prem first#
Candidate pools are ordered with the on-prem fleet ahead of cloud providers. Cloud is overflow and reach, not the default path. This ordering is what makes a sovereign deployment a configuration change rather than a rebuild: disable cloud upstreams and the platform keeps answering from local hardware.
Failover#
- Resolve the alias to an ordered candidate list, filtered by the requesting plan.
- Attempt the first healthy candidate. Health comes from Telemetry and capacity from the Fleet Scheduler.
- On failure or timeout, advance to the next candidate. Retries are bounded so a request fails fast rather than hanging.
- If every candidate is exhausted, return
503 UPSTREAMS_EXHAUSTED— see Errors.
Attribution#
Routing is never invisible. Every completion reports the model that actually served it in the response body, plus the serving pool in a header, so traffic remains attributable after the fact.
x-riven-upstream: onprem-qwen36-a
x-riven-smart-route: riven-best -> riven-pro