Routing og politik

The router is a deterministic scoring function over the set of endpoints your policy allows. It is a pure function, and the tests in packages/router/test are the specification.

Order of operations

1. Normalise the requested model id (aliases, provider prefixes, date suffixes).
2. Load candidate endpoints that report up or degraded.
3. Apply the policy: residency, provider allow/deny, model allow/deny, partner flag, modality, context window, price cap, remaining budget.
4. Pin the model if one was named; otherwise keep the surviving set.
5. Score each candidate and pick the highest.

Score

score = task_fit        * 5
      + language_fit    * 3
      + docs_completeness * 1
      + sovereignty_bonus * 2
      - price_norm      * 2
      - latency_ewma    * 2
      - error_rate      * 3

Ties break on lower price, then lower latency, then a stable id — so the same request always routes the same way.

Residency is a filter, never a preference

A residency that no endpoint satisfies returns 409 no_endpoint_for_policy. The router does not fall back to a wider residency, and the failover path cannot step outside the already-filtered set. catalogue_unknown is not an addressable residency at all: a row that admits it does not know where it runs, so it can never win a route.

Failover

On a 5xx or a timeout the next-best candidate is tried, up to three attempts. Each attempt is recorded on the trace. A non-retryable error stops immediately.

Route reason

Every decision produces one sentence naming the region and the reason, shown verbatim in the console:

auto routing for task "coding" + residency eu-hosted + qwen3-coder-30b @ de-ber (EU-owned, EU-operated); 4 endpoint(s) excluded; partner endpoints not allowed.