> ## Documentation Index
> Fetch the complete documentation index at: https://claritylabs.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing Safety: Challengers, Fallbacks, and Ratings

> Use static challenger sets, required cross-provider fallbacks, and human-rating promotion defaults to keep cl-router clients safe and consistent.

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.

```typescript theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.