Routing Safety: Challengers, Fallbacks, and Ratings - Tools for Enlightenment developer docs

cl-router separates two routing responsibilities. The policy package defines the allowed primary, challenger, and cross-provider fallback routes. Human ratings then decide whether a challenger becomes primary. This page covers the static safety helpers and the rating defaults that clients share with the router.

Cross-provider fallbacks

Some task families must always keep a fallback on a different provider than the primary, so a provider outage cannot take out the whole family:

query_reason requires QUERY_REASON_FALLBACK_MODEL.
Every extraction family (extraction, extraction_*, and *_extraction) requires COVERAGE_CLEANUP_MODEL.

The router preserves this boundary even when a caller’s static fallback snapshot is stale or points at the primary provider.

import {
  MODEL_TASK_ROUTES,
  findCrossProviderFallback,
  requiresCrossProviderFallback,
  safetyFallbackRoutes,
} from "@claritylabs/cl-router-policy";

const family = "query_reason";
const primary = MODEL_TASK_ROUTES.chat;

if (requiresCrossProviderFallback(family)) {
  const candidates = safetyFallbackRoutes(family);
  const fallback = findCrossProviderFallback(primary, candidates);
}

requiredCrossProviderFallback(taskFamily) returns the required route, or undefined when the family has no requirement.
safetyFallbackRoutes(taskFamily) returns the required route plus the shared FALLBACK_MODEL when they differ.
findCrossProviderFallback(primary, candidates) picks the first candidate on a different provider than the primary.

Static fallback candidates are reserved for deterministic recovery. They are never explored or promoted.

Challengers

recommendedChallengerRoutes(taskFamily) returns the reviewed static challenger set for a family:

query_reason evaluates OpenAI gpt-5.6-terra, Fireworks Muse Glimmer 30B, and Fireworks Inkling against the active primary.
Extraction families keep a separate OpenAI gpt-5.4 challenger.
All other families return an empty set.

Rating-based promotion

DEFAULT_RATING_ROUTING_CONFIG holds the promotion defaults the router applies to explicit human ratings:

Field	Default	Meaning
`minimumPromotionRatings`	`25`	A challenger needs at least this many ratings before promotion.
`promotionScoreMargin`	`0.03`	A challenger must beat the incumbent’s score by at least this margin. Cost breaks an exact score tie.
`defaultExplorationPct`	`0.05`	Challengers share this fraction of traffic unless routing is frozen.
`maximumExplorationPct`	`0.1`	The hard cap that `clampExplorationPct` enforces.

The score is (thumbs up + 5) / (all ratings + 10). Provider errors, timeouts, schema failures, and tool completion stay availability telemetry; they never become quality labels. clampExplorationPct(value, maximum?) clamps an exploration fraction to [0, maximum] and returns 0 for non-finite input.

Quality escalation helpers

Two helpers encode which extraction kinds run on the quality route:

primaryRouteForCall({ task, taskKind }) returns EXTRACTION_QUALITY_MODEL for extraction_source_tree and extraction_operational_profile when the call resolves to extraction, otherwise null.
fallbackRouteForCall({ task, taskKind, primaryRoute, allowFallback }) returns the fallback route for a call, or null when fallback is disabled, the fallback equals the primary, or the task is in the low-cost no-escalation set (LOW_COST_NO_ESCALATION_TASKS, which includes classification, extraction, and voice_transcription among others). Kinds in QUALITY_ESCALATION_TASK_KINDS, such as extraction_review, always keep their fallback.

​Cross-provider fallbacks

​Challengers

​Rating-based promotion

​Quality escalation helpers

Cross-provider fallbacks

Challengers

Rating-based promotion

Quality escalation helpers