Routing rules

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.

• Few-shot examples — prompt / expected-mode pairs injected into the classifier’s system prompt (up to 8 per request).
• Confidence-floor overrides — per-mode replacements for Theo’s global 0.85 promotion floor. Lower a floor to make intent promotion easier; raise it to be conservative.

​

Edit rules on a key

• Inherited context — if no per-key rules are set, the panel tells you whether the key currently inherits the team default, your personal default, or nothing.
• Rules — one row per rule. Each row has a keyword chip input, a destination combobox, and a Gentle / Balanced / Strict toggle. The empty state offers a few one-click starter templates (Pricing questions, Customer complaints, Legal review, Photo & image requests) and a Blank rule chip for power users.
• More options — a small caret on each row reveals a note field, a raw regex textarea, an optional Theo engine pin, and a raw confidence slider for fine-grained control.
• Try a prompt — a compact input appears once you’ve started editing. Type a sample customer prompt and the panel renders a one-line diff (baseline mode → with-rules mode) so you can see exactly what would change before saving.

​

Advanced: hand-written regex

​

ContractIQ — a complete walkthrough

​

1. Set rules on the API key

curl -X PUT https://www.hitheo.ai/api/v1/keys/$KEY_ID/routing-rules \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "pattern": "\\\\b(clause|provision|indemnity|warranty)\\\\b",
        "target_mode": "think",
        "confidence": 0.92,
        "description": "Contract terms get the analytical engine."
      }
    ],
    "examples": [
      { "prompt": "Look at this clause", "expected_mode": "think" },
      { "prompt": "Compare these two indemnity sections", "expected_mode": "think" }
    ]
  }'

{
  "key_id": "22222222-2222-4222-8222-222222222222",
  "rules": [
    {
      "id": "r_a4b8c01x9y",
      "pattern": "\\\\b(clause|provision|indemnity|warranty)\\\\b",
      "target_mode": "think",
      "confidence": 0.92,
      "description": "Contract terms get the analytical engine."
    }
  ],
  "examples": [...],
  "active": true,
  "shared_binding": null
}

​

2. Send a completion

curl -X POST https://www.hitheo.ai/api/v1/completions \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Look at this indemnity clause", "mode": "auto", "stream": true }'

{
  "routing": {
    "requested_mode": "auto",
    "resolved_mode": "think",
    "promoted": true,
    "reason": "customer_preference",
    "explanation": "Routing Studio rule matched: \"indemnity clause\".",
    "customer_preference": {
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}

​

3. Test changes before they ship

curl -X POST "https://www.hitheo.ai/api/v1/routing-preferences/$PREF_ID/test" \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Compare these two warranty sections", "mode": "auto" }'

​

Testing an unsaved draft

curl -X POST https://www.hitheo.ai/api/v1/routing-preferences/test \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Look at this clause",
    "mode": "auto",
    "draft": {
      "name": "ContractIQ Legal (draft)",
      "rules": [
        { "pattern": "\\b(clause|provision)\\b", "target_mode": "think", "confidence": 0.92 }
      ],
      "examples": []
    }
  }'

​

Order of precedence

1. Agentic locks (insurance_*, data_extraction) — never promoted.
2. Attachments → vision — image attachments on a non-media caller route to vision.
3. Skill exclusive override — a skill with intensity: 100 and a modelPreference wins.
4. Routing Studio rule — your rules fire here.
5. Intent classifier — runs with your few-shot examples injected and uses your per-mode confidence-floor overrides.
6. Stealth family preservation — promotions from a stealth_* caller stay inside the stealth family.
7. Conversation hint — falls back to the prior-turn artifact type when the caller used auto.
8. Requested mode — default.

​

Confidence-floor overrides

{
  "name": "Legal Default",
  "confidence_floor_overrides": {
    "think": 0.65
  }
}

{
  "name": "Cost-Sensitive",
  "confidence_floor_overrides": {
    "image": 0.95,
    "video": 0.95
  }
}

​

Brand-safety contract

​

Limits

​

Team vs. personal scope

await theo.routingPreferences.create({
  name: "ACME Legal Default",
  scope: "team",
  is_default: true,
  rules: [...],
});

​

Common patterns

• Domain vocabulary biasing. Use rules for hard keywords (“policy”, “claim”, “rune”), use examples for phrasings (“draft me a response to this complaint” → think).
• Cost containment. Raise floors on image/video for personal keys; let team keys keep the defaults.
• Speed bias. Lower the fast floor and add examples like { prompt: "thanks!", expected_mode: "fast" } so short replies don’t escalate to think.

​

Per-key vs. shared sets — when to use which

• You want one rule list to span many API keys (e.g. every key on your team uses the same legal vocabulary).
• You want a team default that new keys inherit automatically.
• You’re scripting bulk changes and would rather author rules in source control once than mirror them across keys.

​

Next steps

• /api/v1/routing-preferences reference — full request/response schemas for every endpoint.
• Routing Studio SDK reference — theo.routingPreferences.*, theo.routingRules.*, and the per-key binding helpers.
• Engine Routing & Fallbacks — where Routing Studio fits inside Theo’s broader routing engine.