Route bundle reference

One YAML file per route under the routes directory (default modelrig/routes/). Files are loaded, structurally validated, and frozen at createRig() time; any invalid bundle throws a RouteConfigError naming the file and every problem.

Top-level fields

dimensions live in modelrig/rig.yaml, not the bundle. Project-level cost dimensions ({ key, label, required }) that back /costs and the required-tag hygiene warning are declared once in the rig manifest — see Tags, dimensions, and the graph.

JSON Schema dialect

The schema file is validated with Ajv, configured for JSON Schema 2020-12 as the primary dialect with draft-07 also accepted — a schema declaring "$schema": "…/2020-12/schema" or "…/draft-07/schema" both compile (the draft-07 meta-schema is registered explicitly). Author 2020-12 for new schemas; existing draft-07 schemas keep working.

Two properties of the configuration are load-bearing when you author a schema:

• Non-strict, union types allowed. Unknown keywords do not fail compilation, and "type": ["string", "null"] is accepted.
• format is annotation-only — it is NOT asserted. Neither dialect enforces format without ajv-formats, which is not registered, so an email, uri, or date-time format documents intent but never rejects a value. If you need a value constrained, express it with pattern / enum / minimum / maxLength, not format.

The gateway and the probe harness (packages/modelrig-probes) build an identical Ajv instance by design, so a fixture scores exactly as it serves.

policy

policy:
  timeout_ms: 60000
  tier: standard
  json: native
  sampling: { temperature: 0.1, max_output_tokens: 8192 }   # preserve the original call's sampling

Gemini 3 note. Google recommends temperature: 1.0 for Gemini 3 and warns that sub-1.0 values can loop / degrade on complex reasoning tasks (classification and extraction are typically fine). Declaring a sub-1.0 temperature on a Gemini-3 candidate loads and is sent as declared, with a load-time advisory naming the model and value.

Variants (bundle format v2 — Phase 3)

A route may declare variants — named bindings served via rig.run(route, { variant: "name" }). Omitting variant (or passing "default") serves the route's base config exactly as v1 did; v1 bundles remain valid unchanged. Every telemetry row records served_variant.

variants:
  - name: cheap
    candidates:               # narrowing ONLY — must be ⊆ the route's list
      - provider: openai
        model: gpt-5.4-mini
    json: json_mode           # rung override for this variant
    repair:
      max_repairs: 2
      repair_model: openai/gpt-5.4-mini
  - name: scaffolded
    scaffold: |               # reasoning scaffold, appended before coaching
      Think through the drivers step by step before emitting JSON.
  - name: reworded
    prompt_override: ./prompts/echo-v2.system.md   # inline text also accepted

repair (the repair rung of the candidate ladder — Phase 3)

repair:
  max_repairs: 2                     # 1 = retry-with-errors only; 2 adds the repair model
  repair_model: deepseek/deepseek-chat   # required when max_repairs is 2; must be a declared candidate

This is the repair rung of the candidate ladder — the ladder's rungs (resolve → render → dispatch → validate → repair → fall-through) are named in full on Routing & reliability.

On a schema-invalid output with repair enabled: attempt 1 re-asks the SAME model with the ajv error summary appended; attempt 2 hands {invalid output, errors, schema} to the designated repair model with a fixed repair prompt. Repair attempts draw from their own repair budget (never the content_invalid budget), and repaired rows carry repaired_by in telemetry — repair cost is visible, not hidden.

Requirement → capability mapping (registry-wired since Phase 3)

Capability flags are resolved from registry facts (the packaged registry/registry.json, env-overridable via MODELRIG_REGISTRY_PATH) with per-flag precedence capabilityOverrides > probed > declared — a probed-false trumps a declared-true (DeepSeek's declared schema support is revoked because every probed sample served via json_mode coaching). Models absent from the registry fall back to the adapter-static baseline below. This table is the registry-absent fallback for gemini, openai, and deepseek; a provider not shown here falls back to its own adapter's declared capability set.

Overridable per provider via RigConfig.capabilityOverrides (replaces the whole flag set for that provider — useful for pinning a route to one candidate in tests).

Templates

• {{var}} — substituted from RunOptions.input. Strings verbatim; objects and arrays are JSON.stringifyed; missing values throw.
• {{#if capability.X}}…{{/if}} / {{#unless capability.X}}…{{/unless}} — resolved against the SERVING candidate's flags before variable substitution. Flat only (nesting is a load-time error); unknown flags are load-time errors.
• The rendered template is sent as the system prompt; the user turn is a fixed terse trigger. Everything the task needs belongs in the template.

Versioning discipline

The (route, version) pair keys the compiled validator cache, telemetry rows, and the console's routes mirror. Editing a bundle without bumping version makes telemetry lie across the change — bump every time.

When it doesn't work

These are the load-time and first-run failures a bundle actually hits, in the loader's own words. The first three fail LOUDLY (the bundle won't load); the last fails SILENTLY (it loads and then behaves unlike the code it replaced) — which is why it is the one to be most careful about.

• schema file not found: <path> — schema: names a JSON Schema file that isn't at that path. Paths resolve relative to the bundle file. Create the file there, or set schema: null for a genuinely free-form task.
• prompt.system file not found: <path> — same shape for the prompt template. Point prompt.system at where the file actually is.
• references undeclared variable "<name>" — the template (or grounding.query) uses a {{name}} that prompt.variables doesn't declare. Add it to the list, or fix the typo. This is caught at load so an empty slot can't ship silently. Note the ONLY conditional blocks the template engine supports are {{#if capability.X}} / {{#unless capability.X}} — a {{#if <variable>}} is not a feature and will not render.
• A wrong json: native — the bundle loads, then the run behaves unlike the code it replaced. json: native is a claim about the MODEL: set it only for a candidate whose registry entry shows probed native strict enforcement (structured_native). Otherwise omit it and let the emulation ladder handle structure. Check the probed registry (llms.txt or the MCP oracle) rather than recalling — declared and probed behaviour differ, which is the whole point.

Still stuck? Open an issue at <https://github.com/modelrig/modelrig/issues> — a human reads them.

Raw-lane defaults (rig.runRaw)

What the raw lane sends when you omit a knob. Each knob is additive — absent ⇒ byte-identical dispatch. The one default with teeth is timeoutMs, which is tier-aware (since 0.5.0): a passthrough should not be shorter-fused than the tier it advertises, so standard/priority target 5 min and flex targets the 15-minute budget ModelRig advertises. An explicit timeoutMs always wins (no pre-dispatch rejection — a short deadline is a choice), and a timeout failure on the raw lane carries a fixHint naming the tier, its budget, and the two fixes (raise timeoutMs, or drop to serviceTier: "standard"). On flex, set timeoutMs in minutes. This table is generated from the RAW_DEFAULTS constant, so it cannot drift from what the runtime resolves.

Raw-lane provider × knob support (rig.runRaw)

Since 0.4.0: reasoning beyond gemini, responseFormat, and the DeepInfra/Fireworks prompt_cache_key mapping. The openai/grok prompt-cache hints were already true on 0.3.0.

The Lane-B rig.runRaw seam forwards a set of provider knobs beyond the core prompt/sampling ones. Each is ADDITIVE — absent ⇒ byte-identical dispatch — and a knob a provider cannot honor FAILS CLOSED pre-dispatch (RigFailureError, class invariant_violation; no meter, no provider call, no telemetry row), never a silent drop. This table is the single source of truth: the runtime guard (assertRawKnobsSupported) and this matrix are both generated from the same RAW_KNOB_SUPPORT table, so what you read here is exactly what the guard enforces.

Fail-closed is discoverable, not a surprise. A knob a provider cannot honor throws RigFailureError invariant_violation PRE-DISPATCH (no meter, no provider call, no telemetry row) — read this table before you call, not after. reasoning has NO per-model allowlist outside gemini. openai/deepinfra/fireworks forward level verbatim and let the provider enforce; a rejection surfaces as a classified failure that names the fix. grok coarsens (disclosed above). deepseek reasoning is model selection (deepseek-reasoner); anthropic extended thinking is unwired. responseFormat is mime-shaping, not schema enforcement. json_object forces syntactic JSON only — the raw lane still never validates or repairs, and meta.validated stays false (F4). §3.2 flex degrade is customer-side. ModelRig does not replicate the gemini direct-path infra-retry wrapper on the raw lane; under flex a capacity rejection surfaces classified (capacity_shed) for your own → standard retry ladder — a NAMED difference for your migration record, not a silent one. destination is UNRELEASED. The serving-destination column names which providers can be modelrig-served (reached on ModelRig's own key) vs direct only. Managed serving is gated behind a config flag (config.managedServing, default off, set in code — not an env var) and remains UNRELEASED (no GA); until it is enabled every call is direct (ABSENT ⇒ byte-identical).

Ask it in code instead of duplicating this table: rawKnobSupport(provider) returns the row above, and GEMINI_THINKING_CAPABLE_MODELS is the exported set the gemini reasoning gate uses (both from the package root).

Hosted proxy — /v1/chat/completions message handling

The OpenAI-compatible proxy accepts a messages[] array. Two rules keep an untrusted caller turn from being mistaken for a trusted instruction:

• Role enum. Each message role must be one of system, developer (normalised to the system slot), user, assistant, or tool. Any other value is rejected before the request reaches the pipeline with a teaching message (HTTP 422, the gateway's validation status) — an arbitrary role is never forwarded.
• Unambiguous turn encoding (raw lane). When a raw-lane request carries a genuine multi-turn transcript, the non-system turns are flattened into the adapter's single user prompt as a **JSON-encoded block — one JSON object per line** ({"role":"user","content":"…"}, `{"role":"tool","tool_call_id":"…", "content":"…"}), not as role: content text lines. JSON.stringify` escapes any embedded newline, so a crafted turn whose content contains `"\n\nsystem: …" stays inside its content` field and can never read as a synthetic system line. system turns are still joined into the system prompt as before, and the common single-user-turn case is passed through verbatim (byte-identical).