Routing and failover#

Conduit classifies a task into a supported model family, then evaluates the operator's supply order for that family. Healthy prepaid and local lanes lead equivalent metered providers; circuit-breaker state can temporarily move a failing lane aside without rewriting policy.

Before you start#

Multiple lanes expose the same supported model identity.
Provider pricing, capability and context data are current.
Member limits allow the selected route.

Use the Providers page to test and order supply. Use /api/v1/router to inspect a decision without incurring an inference call. Pin a direct exposed model when classification is not desired.

What every request is checked against#

Tool support and context capacity are properties of the request, and Sugar checks them on every request before a lane is chosen — not only when Conduit model hysteresis or the Flex tier is on.

Check	Rule
Tool support	A lane takes a tool-bearing request only if its record declares tool support. Silence is a refusal.
Context capacity	A lane is excluded when its declared window is smaller than the prompt plus reserved output.
Unknown context window	The lane stays eligible for ordinary traffic; exclusion needs a declared window that is genuinely too small. Under Conduit model hysteresis or the Flex tier it is excluded instead.
Price	Under a finite cost ceiling, only a lane with an admissible price is eligible.

The two strict modes change only the unknown-window row. Tool support, a declared window that is too small and the price ceiling are applied the same way whether or not hysteresis or Flex is on. A window that was never declared is admitted for ordinary traffic and refused under either mode.

When the request's own requirements rule out every lane, Sugar answers 503 and names the lanes and the reason. Record a capability finding under Providers → the lane → Capabilities when a lane does support tools and its catalogue entry never said so.

Session affinity#

A derived conversation stays on the family and provider that already hold its warm prefix. On a request with no tools array a weak classifier change keeps the family, and a switch needs the classifier's own top pick with high confidence and a clear score advantage. On a request that carries tools those thresholds do not apply and the classifier's pick wins outright — tool-bearing work is treated as a capability signal rather than a cache-cost trade. Either way the switch is persisted only after that family succeeds.

Fallback#

Fallback can disclose the prompt to another configured provider after a failed or refused attempt. Use one provider for a family when that disclosure is not acceptable.

A terminal 4xx verdict is remembered against the endpoint that gave it: further candidates sharing that base URL are skipped, and candidates behind a different endpoint still get their turn. Provider-health fallback never changes family.

Author and promote a routing revision#

Routing revisions are immutable, and the live pointer moves only when a person moves it. Work in Admin → Conduit, under Author and promote a routing revision.

Author a candidate. It copies the live snapshot and changes only each family's exact stable release key and the upstream id it is served under.
Select the candidate as the canary candidate to gather evidence first. Authoring alone never changes live traffic.
Promote the revision when the evidence supports it. Promotion copies the revision forward into a new immutable revision and moves the pointer.
Roll back by promoting the previous revision the same way.

Important: this route is reachable only from an authenticated admin session. An sgr_admin_ automation token is refused admin_token_route_forbidden on every method, including reads, so promotion cannot be automated.

Sugar refuses a candidate that changes nothing, changes the classifier version or a family's public id, or names the active revision. It refuses a promotion that would leave a changed family with no eligible lane (conduit_routing_policy_supply_unavailable) — qualify the release, enable it for Conduit and admit it in the supply policy, then promote again. Rollback is exempt from that gate, because an emergency exit must not depend on current supply.

The GLM-5.2 revision stays gated behind SUGAR_CONDUIT_GLM52_CANDIDATE. While the switch is off, promoting it is refused rather than merely undocumented.

Verify#

Send a router inspection and a real request with the same model choice. Confirm the family, selected lane and response headers agree. Disable the leading lane in a maintenance window and verify the expected fallback, then restore policy. After promoting a revision, confirm the active version in the Conduit tab and send one request per family.

If it does not work#

503 naming lanes that do not declare tool support. Record the capability finding, or send the request without tools.
A promotion is refused. Read the named family and release key; the lane is unqualified, not enabled for Conduit, or not admitted by the active policy.
A family has no active source. Check the supply map for lanes waiting on qualification or admission.