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

# Engine Routing & Fallbacks

> How Theo selects the best engine and handles failures.

Theo doesn't use a single model. The engine router selects the optimal engine for each task based on the resolved mode, with automatic failover if the primary engine is unavailable.

## Engine Table

|| Mode | Engine ID | Description |
||------|-----------|-------------|
|| fast / auto | `theo-1-flash` | Fast, lightweight completions |
|| think | `theo-1-reason` | Deep reasoning and analysis |
|| code | `theo-1-code` | Production-quality code generation |
|| image | `theo-1-create` | Image generation |
|| video | `theo-1-motion` | Video generation |
|| research | `theo-1-research` | Multi-step web research and synthesis |
|| roast | `theo-1-edge` | Unfiltered humor |
|| genui | `theo-1-genui` | Generative UI components |
|| domain analysis | `theo-1-analyze` | Domain-specific analysis (business, operations, etc.) |
|| data extraction | `theo-1-extract` | Document OCR and structured data extraction |

Theo has access to 300+ models and automatically selects the best one for each engine.

## Automatic Failover

Every engine has a built-in failover mechanism. If the primary model is unavailable or performing below quality thresholds, Theo automatically routes to a backup — you never see a broken response. Failover is transparent and logged in the audit trail.

## Engine IDs in Responses

API responses always use Theo-branded engine identifiers:

```json theme={null}
{
  "model": {
    "id": "theo-1-reason",
    "label": "Theo Reason",
    "engine": "theo-core"
  }
}
```

## Skill Engine Preferences

Skills can recommend a preferred engine via the `enginePreference` field in their manifest. When a skill's preferred engine differs from the mode default, Theo uses the skill's preference if available.

## Per-Customer Override Stage (Routing Studio)

Between the skill exclusive override and the global intent classifier, the routing engine consults the caller's bound **Routing Studio preference** — a customer-authored bundle of keyword rules, few-shot examples, and per-mode confidence-floor overrides. Preferences let your domain win on ambiguous prompts without retraining the global classifier.

The order, first match wins:

1. Agentic locks (`insurance_*`, `data_extraction`) — never promoted.
2. Attachments → vision.
3. Skill exclusive override (intensity-100 skill with a `modelPreference`).
4. **Routing Studio rule.** Customer-authored rule fast-path.
5. Intent classifier (with customer few-shot examples + per-mode confidence floor).
6. Stealth family preservation.
7. Conversation hint (for `auto` callers).
8. Requested mode.

Customer rules cannot escape stealth or agentic family locks. When a rule targets a stealth-incompatible mode for a stealth caller, the engine silently remaps to the stealth equivalent.

When a preference contributes to the resolution, the `routing` block carries a `customer_preference` field with the preference id, name, the rule id that matched (if any), and the count of few-shot examples injected into the classifier:

```json theme={null}
{
  "routing": {
    "reason": "customer_preference",
    "customer_preference": {
      "id": "<uuid>",
      "name": "ContractIQ Legal",
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}
```

See the [Routing Studio guide](/guides/routing-studio) for the full ContractIQ walkthrough and the [SDK reference](/sdk-reference/routing-studio) for `theo.routingPreferences.*` and `theo.keys.setRoutingPreference()`.

## Routing Receipts in the Playground

Every completion already includes a structured `routing` block on both the SSE `meta` and `done` events:

```json theme={null}
{
  "routing": {
    "requested_mode": "fast",
    "resolved_mode": "image",
    "promoted": true,
    "reason": "intent_promotion",
    "explanation": "Detected an image generation intent in a text-mode caller.",
    "classification": {
      "mode": "image",
      "confidence": 0.93,
      "used_fast_path": true,
      "reasoning": "Keyword 'draw me' matched image-generation pattern."
    },
    "image_routing": {
      "resolved_engine": "theo-1-rapid",
      "auto_selected": true,
      "quality": "standard"
    }
  }
}
```

The playground renders this as an inline **routing receipt** under every assistant turn: a compact `requested → resolved` line, a `Promoted` chip when the routing engine overrode the caller's mode, the engine's `explanation`, and a click-to-expand panel that surfaces classifier confidence, skill overrides, locked families, and the image sub-engine. A four-dot pipeline (CRL → Skill → Route → Dispatch) highlights the stage that drove the decision.

This is the same data your own apps receive over the wire — point your SDK at the `meta` event's `routing` field to render the same affordance in your product.

## Check Engine Availability

```bash theme={null}
curl https://www.hitheo.ai/api/v1/models \
  -H "Authorization: Bearer $THEO_API_KEY"
```

Returns the full engine registry with status and availability.