Routing overview

A concise but current summary of how the reference router filters, scores, ties, and explains a decision.

Routing in role-model is deterministic and explainable.

The goal is not only to choose an endpoint, but to produce answers to two questions:

The routing order

The baseline router applies this order:

normalize request intent into an effective policy snapshot
reject candidates that fail hard constraints
score the remaining candidates across quality, latency, throughput, cost, reliability, and preference
redistribute weight when an entire metric is unknown for every eligible candidate
break near-ties by higher quality, lower latency, higher reliability, then stable endpoint_id
emit a RouterDecision with ranked fallbacks and reason codes

Before scoring, the router filters out endpoints that cannot legally or practically satisfy the request.

Baseline exclusion families include:

This matters because the router should never "score its way out of" a hard incompatibility.

After eligibility, the router prefers measured evidence when it exists:

Catalog-derived cost data and declared profiles still matter, but measured evidence wins when it is present.

The smoke request asks for:

The candidate set contains three endpoints:

Why the exclusions happen:

Both exclusions are recorded as CAPABILITY_MISSING.

That leaves cli.local.coder as the only eligible candidate. The router then records the final decision with selection reasons such as:

The decision is only one artifact in the routing story.

The baseline can also emit:

trace-spans.json to show routing phases such as eligibility, scoring, and selection
usage-events.jsonl to show request and accounting metadata
observed-performance.json to show measured endpoint behavior

That artifact set is what makes routing explainable after the fact.