Complexity Router

Automatically classify incoming LLM requests into complexity tiers and route them to the right model.

Overview

The Complexity Router analyzes incoming requests and assigns a tier - Simple, Medium, Complex, or Reasoning - when the latest user message contains a clear complexity signal. The result is exposed as a flat string variable (complexity_tier) in Bifrost’s CEL routing engine, so you can write routing rules like:

complexity_tier == "REASONING"
complexity_tier in ["COMPLEX", "REASONING"]

This lets you route simple greetings to a fast, cheap model and deep reasoning tasks to a frontier model — automatically, with no changes to your application code. When the latest user message does not match a configured signal, Bifrost leaves complexity_tier unknown and keeps the request on its existing routing path instead of guessing. The algorithm is fast and deterministic: it runs entirely in-process using pre-compiled literal and stemmed keyword matching, adds less than 1 ms to request latency, and makes zero external calls.

---

How it works

Scoring dimensions

Classified requests produce a score between 0.0 and 1.0. The analyzer starts with a weighted score across five dimensions detected by scanning the last user message:

Dimension	Weight	What it measures
Code presence	30%	Code, debugging, and programming artifacts
Reasoning markers	25%	Analytical and multi-step reasoning language
Technical terms	25%	Architecture, infra, and operational terminology
Word count	10%	Prompt length measured by whitespace-delimited words, used only after a signal or continuation is detected
Simple indicators	-5%	Greetings, definitions, translation requests, and other straightforward asks

Simple indicators are a small downward nudge, not an override. A simple-only request can classify as Simple with a 0.00 score, while a request that also has strong code, technical, or reasoning signals can still rise into a higher tier.

System prompt contribution

When the latest user message already has a code, technical, or reasoning signal, the system prompt is scanned for code and technical signals. Its contribution is weighted at 25% of the user-message signal for those dimensions. This provides soft lexical context — for example, a system prompt describing a coding assistant nudges code scores up — but it never creates a classification by itself.

Conversation context blending

For multi-turn conversations, prior context is used only when the latest user message has its own code, technical, or reasoning signal, or when the latest message is a configured continuation phrase such as “do it”, “try again”, “continue”, or “go ahead” and the prior-context score is at least 0.20. In those cases, the score blends the current message with history from up to the last 10 user turns (recency-weighted: earlier turns count less):

• Default blend: 60% last message + 40% conversation history
• Continuation blend: 35% last message + 65% conversation history

An explicit continuation phrase inherits most of its score from prior context rather than being classified on its own. A low-signal latest message that is not an explicit continuation does not inherit old context; complexity_tier remains unknown and routing falls through to the original model.

The final score is max(last_message_score, weighted_blend) — the current message always sets a floor.

Reasoning override

When two or more reasoning keywords are detected in the last user message, the tier is forced to Reasoning regardless of the numeric score. The same override applies when one strong reasoning keyword appears alongside strong code or technical signals.

This handles prompts like “step by step, explain why the authentication flow fails” that would score moderately on each individual dimension but clearly require deep reasoning.

Tier classification

The final score maps to a tier using configurable boundaries (defaults shown):

Tier	Score range (defaults)	Typical requests
Simple	< 0.15	Greetings, definitions, simple lookups
Medium	0.15 – 0.35	General questions, short explanations
Complex	0.35 – 0.60	Technical questions, code help, multi-step tasks
Reasoning	≥ 0.60 (or override)	Analysis, architecture decisions, root-cause investigation

---

Configuration

Tier boundaries

Adjust where the score thresholds fall to match your traffic and model lineup.

Web UI

Navigate to Complexity Router in the sidebar.

The Complexity Spectrum bar updates live as you type boundary values, so you can see how your traffic would be distributed before saving.

1. Enter a value between 0 and 1 for each boundary.
2. Boundaries must be strictly increasing: simple_medium < medium_complex < complex_reasoning.
3. Click Save changes to apply immediately (hot-reloaded, no restart required).
4. Click Restore defaults to reset all boundaries and keyword lists to factory values.

API

# Get current configuration
curl http://localhost:8080/api/governance/complexity-analyzer-config

# Update tier boundaries
curl -X PUT http://localhost:8080/api/governance/complexity-analyzer-config \
  -H "Content-Type: application/json" \
  -d '{
    "tier_boundaries": {
      "simple_medium": 0.15,
      "medium_complex": 0.35,
      "complex_reasoning": 0.60
    },
    "keywords": {
      "code_keywords": ["function", "class", "api", "debug"],
      "reasoning_keywords": ["step by step", "explain why", "tradeoffs"],
      "technical_keywords": ["architecture", "kubernetes", "latency"],
      "simple_keywords": ["hello", "hi", "thanks", "what is"]
    }
  }'

# Reset to factory defaults
curl -X POST http://localhost:8080/api/governance/complexity-analyzer-config/reset

Response (GET / PUT):

{
  "tier_boundaries": {
    "simple_medium": 0.15,
    "medium_complex": 0.35,
    "complex_reasoning": 0.60
  },
  "keywords": {
    "code_keywords": ["function", "class", "..."],
    "reasoning_keywords": ["step by step", "..."],
    "technical_keywords": ["architecture", "..."],
    "simple_keywords": ["hello", "hi", "..."]
  }
}

config.json

{
  "governance": {
    "complexity_analyzer_config": {
      "tier_boundaries": {
        "simple_medium": 0.15,
        "medium_complex": 0.35,
        "complex_reasoning": 0.60
      },
      "keywords": {
        "code_keywords": ["function", "class", "api", "debug", "deploy"],
        "reasoning_keywords": ["step by step", "explain why", "tradeoffs", "root cause analysis"],
        "technical_keywords": ["architecture", "kubernetes", "latency", "authentication"],
        "simple_keywords": ["hello", "hi", "thanks", "what is", "define"]
      }
    }
  }
}

Field	Type	Required	Default	Description
tier_boundaries.simple_medium	number	Yes	0.15	Score threshold between Simple and Medium (exclusive: 0 < value < 1)
tier_boundaries.medium_complex	number	Yes	0.35	Score threshold between Medium and Complex
tier_boundaries.complex_reasoning	number	Yes	0.60	Score threshold between Complex and Reasoning
keywords.code_keywords	string[]	Yes	built-in defaults	Signals for code/debugging/programming requests
keywords.reasoning_keywords	string[]	Yes	built-in defaults	Strong reasoning triggers — matches can force the Reasoning tier
keywords.technical_keywords	string[]	Yes	built-in defaults	Architecture/infra/operations signals
keywords.simple_keywords	string[]	Yes	built-in defaults	Phrases that slightly reduce complexity and classify straightforward requests

Each keyword list requires at least one entry. Keywords are normalized to lowercase and deduplicated on save. Changes are hot-reloaded with no restart required.

When governance.complexity_analyzer_config is present in config.json, the default split mode preserves UI and API edits across restarts while the matching file section is unchanged. When a section changes, tier boundaries are replaced from config.json, while keyword lists are merged additively with stored runtime keywords (union with duplicates removed). Set top-level source_of_truth to "config.json" in config.json, or bifrost.governance.sourceOfTruth: config.json in Helm values, only when the file should replace the stored analyzer config.

Keyword lists

Each list controls a different part of the scoring signal. Understanding what they do helps you tune routing for your domain.

The default keyword lists are tuned for common request patterns and are a good starting point for most deployments. For domain-specific traffic, add or remove keywords based on the prompts your users actually send so the tiers match your routing strategy. Bifrost stores and displays the exact keywords you configure; internally, normal word-based keywords and phrases also match common word forms, such as debug, debugging, and debugged. Punctuation-heavy terms such as ci/cd still use literal matching.

Web UI

Type a keyword or phrase and press Enter to add it. Click the × on any tag to remove it. The entry count is shown next to each list label.

About each list

List	Effect	When to customize
Code keywords	Each match contributes to the Code dimension (30% weight)	Add domain-specific tooling, frameworks, or file types your users frequently mention
Reasoning keywords	Strong triggers — two or more matches, or one match alongside strong code/technical signals, forces the Reasoning tier regardless of score	Narrow this list to the phrases that truly demand your most capable model. The default list is intentionally conservative.
Technical keywords	Each match contributes to the Technical dimension (25% weight)	Add industry-specific jargon (e.g. “SOC 2”, “HIPAA”, “proration”) relevant to your product
Simple keywords	Each match slightly reduces the score and can classify straightforward requests as Simple	Add domain-specific phrases that signal trivial intent in your app context

The reasoning keywords list gates the tier-override path, not just scoring. Adding broad terms like “explain” or “analyze” will push many requests to Reasoning. Prefer specific multi-word phrases like “step by step” or “root cause analysis”.

---

Routing with complexity_tier

Once the analyzer is configured, use complexity_tier as a variable in any CEL routing rule expression. Bifrost evaluates it as a plain string.

complexity_tier is not a special standalone rule type. In the Routing Rules builder, it behaves like any other field, so you can combine it with headers, request type, team/customer scope, budgets, and other predicates in the same rule or nested rule group.

Complexity Router only exposes complexity_tier; it does not create rules automatically. Add rules for the tiers you want to route. For deterministic four-tier routing, create rules for Simple, Medium, Complex, and Reasoning.

Available operators

Operator	CEL syntax	Example
Equal	==	complexity_tier == "REASONING"
Not equal	!=	complexity_tier != "SIMPLE"
In list	in	complexity_tier in ["COMPLEX", "REASONING"]
Not in list	!(x in [...])	!(complexity_tier in ["SIMPLE", "MEDIUM"])

Combining with other rule conditions

You can mix complexity with any other routing condition the CEL builder supports:

headers["x-tier"] == "premium" && complexity_tier == "REASONING"
headers["x-region"] == "us-east" && complexity_tier in ["COMPLEX", "REASONING"]
request_type == "chat_completion" && complexity_tier != "SIMPLE"
team_name == "ml-research" && headers["x-env"] == "prod" && complexity_tier == "REASONING"

Setting up a complexity-based routing rule

The best first rollout is usually a single Reasoning rule. It is easy to validate, has the smallest blast radius, and leaves Simple, Medium, and Complex traffic on your existing routing path.

1. Go to Routing Rules in the sidebar.
2. Create a new rule and open the CEL builder.
3. Add a condition: field = Complexity Tier, operator = =, value = Reasoning.
4. Set the target provider and model to your strongest reasoning model.
5. Save and enable the rule.

Once you are happy with the classifications, add complementary rules for Simple, Medium, and Complex if you want a full tier-based routing ladder. An example is shown below.

Use case examples

Start with a Reasoning carve-out

Route only frontier-worthy requests to your strongest model and let everything else keep using your existing routing:

{
  "id": "complexity-reasoning",
  "name": "Reasoning → Frontier model",
  "enabled": true,
  "cel_expression": "complexity_tier == \"REASONING\"",
  "targets": [{ "provider": "anthropic", "model": "claude-opus-4-5", "weight": 1 }],
  "scope": "global",
  "priority": 0
}

Full four-tier ladder

Route every tier explicitly when you want deterministic model selection across the full spectrum:

[
  {
    "id": "complexity-simple",
    "name": "Simple → Fast model",
    "enabled": true,
    "cel_expression": "complexity_tier == \"SIMPLE\"",
    "targets": [{ "provider": "groq", "model": "llama-3.1-8b-instant", "weight": 1 }],
    "scope": "global",
    "priority": 0
  },
  {
    "id": "complexity-medium",
    "name": "Medium → Balanced model",
    "enabled": true,
    "cel_expression": "complexity_tier == \"MEDIUM\"",
    "targets": [{ "provider": "openai", "model": "gpt-4o-mini", "weight": 1 }],
    "scope": "global",
    "priority": 1
  },
  {
    "id": "complexity-complex",
    "name": "Complex → Strong general model",
    "enabled": true,
    "cel_expression": "complexity_tier == \"COMPLEX\"",
    "targets": [{ "provider": "anthropic", "model": "claude-sonnet-4-5", "weight": 1 }],
    "scope": "global",
    "priority": 2
  },
  {
    "id": "complexity-reasoning",
    "name": "Reasoning → Frontier model",
    "enabled": true,
    "cel_expression": "complexity_tier == \"REASONING\"",
    "targets": [{ "provider": "anthropic", "model": "claude-opus-4-5", "weight": 1 }],
    "scope": "global",
    "priority": 3
  }
]

Roll out to one team first

Test complexity routing with a single team before enabling it globally:

{
  "id": "team-reasoning-pilot",
  "name": "Team pilot — reasoning route",
  "enabled": true,
  "cel_expression": "complexity_tier == \"REASONING\"",
  "targets": [{ "provider": "anthropic", "model": "claude-opus-4-5", "weight": 1 }],
  "scope": "team",
  "scope_id": "team-uuid-456",
  "priority": 0
}

---

Observability

Complexity analysis is recorded in the routing log for every request where analysis ran and produced a tier. In the log detail view, look at the Routing Decision Logs section backed by routing_engine_logs.

You will see log lines like Complexity: tier=REASONING score=0.38 words=25. If no configured complexity signal matches the latest user message, the routing log records that complexity analysis was skipped and routing continues on the existing path. This lets you audit how traffic is being distributed and spot mis-classifications to tune thresholds or keyword lists.

---

Troubleshooting

Rule not matching when complexity_tier is set

If the routing rule uses complexity_tier and the request is not matching, make sure the latest user message contains analyzable user text and at least one configured signal. A system prompt by itself is not enough — the analyzer needs a text-bearing user prompt to classify.

If analysis is unavailable (for example the body could not be parsed, the user content is not text-only, or no configured complexity signal matches the latest user message), the complexity-dependent rule does not match and evaluation falls through to the next rule. This is intentional: complexity rules silently degrade rather than blocking requests.

Which request types are supported

Complexity routing currently runs only for text-bearing request families. Supported inputs include:

• Chat Completions and other messages-style requests with text-only user content
• Text Completions requests using prompt
• Responses API requests using text-only input
• Anthropic Messages, Bedrock Converse, and Gemini contents / systemInstruction shapes when they carry text-only user input

It does not run for:

• Image generation, embeddings, rerank, OCR, audio/speech/transcription, video, or count-tokens requests
• Chat or Responses requests where user content mixes text with image, file, or audio blocks
• Requests that contain only system or developer text and no user text

All traffic classified as Reasoning

The reasoning keywords list is the most common cause. Check if any broad single-word terms were added (e.g. “explain”, “analyze”). The override gate fires when two or more strong reasoning keywords match — a broad list will trigger it on most prompts. Replace single-word terms with specific multi-word phrases.

Want to test threshold changes without affecting live traffic

Use the Discard changes button to revert unsaved edits, or Restore defaults to return to factory settings. Changes only take effect on save.

---

Next Steps

Routing Rules

Full reference for CEL expressions, scope hierarchy, and rule chaining

Virtual Keys

Scope complexity routing rules to specific teams, customers, or virtual keys

Budget & Limits

Combine complexity routing with budget limits for cost-optimal routing

Provider Routing

Understand how complexity routing fits into the full request routing pipeline