Skip to main content
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: 
{
  "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: 
{
  "routing": {
    "reason": "customer_preference",
    "customer_preference": {
      "id": "<uuid>",
      "name": "ContractIQ Legal",
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}
See the Routing Studio guide for the full ContractIQ walkthrough and the SDK reference 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: 
{
  "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

curl https://www.hitheo.ai/api/v1/models \
  -H "Authorization: Bearer $THEO_API_KEY"
Returns the full engine registry with status and availability.