Models and routing

Routing profiles are not models

oryvox-* model names are routing profiles ("virtual models"). They do not point at one model. For each request ORYVOX analyses the task (type, complexity, whether it needs tools, vision, JSON or reasoning), filters the models your project allows, and picks the best fit for the profile's mode.

Profile	Mode	Use it for
`oryvox-auto`	the project's default mode	Most traffic. Change the default in the project settings.
`oryvox-fast`	`economy`	High volume, latency- and cost-sensitive work.
`oryvox-balanced`	`balanced`	Good quality at a sensible price.
`oryvox-quality`	`quality`	Answers where quality matters more than price.
`oryvox-max`	`max`	The strongest available model, regardless of price.
`oryvox-reasoning`	`quality`, reasoning models only	Multi-step reasoning, maths, planning.
`oryvox-code`	`quality`, tuned for coding	Code generation, review, refactoring.

GET /models lists the profiles (with "oryvox": {"virtual": true}) and every real model.

Routing modes

Mode	Behaviour
`economy`	Cheapest model that meets the task's minimum quality.
`balanced`	Weighs quality, price and latency.
`quality`	Prefers higher quality; price is a tie-breaker.
`max`	Highest quality available.

Override per request:

{"model": "oryvox-auto", "routing": {"mode": "economy", "min_quality": 70}, "max_cost": 0.002, "input": "..."}

routing.mode overrides the profile's mode.
routing.min_quality raises the quality floor (0-100 scale, as in /models).
max_cost (USD) excludes models whose estimated cost for this request is higher.

Fixed models

Use a concrete id such as anthropic/claude-sonnet-5.5 or openai/gpt-5-mini to pin a model. ORYVOX still applies caching, optimisation, budgets, policy checks and provider failover for that model (another provider serving the same model), but it does not switch to a different model unless you configure fallbacks (see Fallbacks).

Project policy

Project settings constrain routing for every key in the project: allowed or denied providers, blocked models, a maximum price per million tokens, allowed data regions and "no training" or zero-data-retention requirements. A request that no allowed model can serve fails with 503 no_model_available.

How the router scores (router v1.1)

Each candidate is scored on quality, task fit, reasoning, cost, latency, reliability, cache affinity, live provider health and compliance. The weights depend on the workload (realtime, coding, batch, reasoning, content, support, default) and the mode moves weight between quality and cost. Signals you can send:

metadata.priority: realtime favours latency, batch favours cost.
oryvox.step / metadata.step: route an agent step as its job (Agents).
X-Oryvox-Session: a conversation prefers the model whose provider already caches its context (a small bonus, never a lock).
Ratings via POST /v1/requests/{id}/feedback feed the measured quality per model and task.

Unhealthy deployments are left out when another can run. Under a downgrade budget near its limit the router switches to economy (Billing).

Seeing why a model was chosen

GET /requests/{request_id} (key scope requests) returns the trace: detected task, required quality, weights, candidates with scores, reasons, every attempt and the spans (Observability).