Controlling OmniRoute Auto-Combo Behavior with HTTP Headers

You can dynamically control OmniRoute’s auto-combo routing engine on a per-request basis by sending the X-OmniRoute-Mode and X-OmniRoute-Budget HTTP headers, which the resolveRequestAutoControls function parses and merges into the combo’s runtime configuration without altering persisted settings.

The auto-combo feature in the diegosouzapw/OmniRoute repository automatically selects and scores AI models based on configurable strategies. By leveraging specific request headers, API clients can override scoring presets and spending limits for individual requests while keeping the underlying combo definition intact.

Understanding the Auto-Combo Header Architecture

OmniRoute implements request-level auto-combo controls through a pure function design that isolates header parsing from business logic. The core resolver, resolveRequestAutoControls, lives in open-sse/services/autoCombo/requestControls.ts and extracts validated control parameters from incoming HTTP headers.

This function returns a plain object containing optional modePack and budgetCap values. The chat request handler in src/sse/handlers/chat.ts imports this resolver at line 42 and applies its output at line 1032, merging the per-request controls with the combo’s stored configuration before the scoring engine evaluates candidate models. The same resolver is also consumed by open-sse/services/combo/resolveAutoStrategy.ts, ensuring consistent header interpretation across the entire request pipeline.

Available Control Headers

OmniRoute recognizes two specific headers that adjust auto-combo behavior at runtime.

X-OmniRoute-Mode Header

The X-OmniRoute-Mode header selects a scoring preset or specifies a raw mode-pack name for the auto-combo engine. This header accepts the following friendly preset values:

• fast — Prioritizes low-latency responses
• balanced — Uses default weight sets (also forces defaults if other values were set)
• quality — Optimizes for highest output quality
• cheap — Minimizes cost per token
• reliable — Favors providers with highest uptime metrics
• offline — Limits selection to locally-hosted or cached models

You may also supply a custom mode-pack name (e.g., my-experimental-mode) to override presets entirely. If the header is missing or contains an unrecognized value, the engine ignores it and retains the combo’s persisted configuration.

X-OmniRoute-Budget Header

The X-OmniRoute-Budget header caps the total USD cost that the auto-combo may spend for the current request. Provide the value as a decimal amount (e.g., 0.05 for five cents). The engine interprets this number as a strict spending ceiling during model selection and routing.

How Headers Are Processed in the Request Pipeline

When a request reaches the chat completion endpoint, the handler invokes resolveRequestAutoControls to transform header values into runtime controls. The function validates the inputs and returns an object structured as { modePack?: string, budgetCap?: number }.

At line 1032 of src/sse/handlers/chat.ts, these controls merge with the combo engine’s existing config object. This merge happens immediately before candidate scoring, ensuring that per-request overrides take precedence over stored defaults while maintaining type safety. The implementation guarantees that malformed or missing headers cannot corrupt the persisted combo settings—invalid values are silently ignored, leaving the original configuration unchanged.

Practical Implementation Examples

Force Fast Mode with a Spending Cap

To prioritize speed and limit costs to three cents per request:

fetch('https://omniroute.example/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-OmniRoute-Mode': 'fast',
    'X-OmniRoute-Budget': '0.03',
  },
  body: JSON.stringify({ 
    model: 'auto', 
    messages: [{ role: 'user', content: 'Hello' }] 
  })
});

Use a Custom Mode-Pack for Experimental Routing

To test a custom scoring strategy without modifying the persisted combo:

fetch('/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-OmniRoute-Mode': 'my-experimental-mode',
    // No budget header → uses the combo’s persisted budget
  },
  body: JSON.stringify({ 
    model: 'auto', 
    messages: [{ role: 'user', content: 'Explain quantum tunneling' }] 
  })
});

Server-Side Header Processing

When building custom handlers that leverage OmniRoute’s internals:

import { resolveRequestAutoControls } from '@omniroute/open-sse/services/autoCombo/requestControls.ts';

export async function handleChat(request: Request) {
  const perRequestAutoControls = resolveRequestAutoControls(request.headers);
  // `perRequestAutoControls` now contains `{ modePack?: string, budgetCap?: number }`
  // These are merged with the stored combo config before routing.
}

Error Handling and Safety Guarantees

The header control system employs a fail-safe design. If X-OmniRoute-Mode or X-OmniRoute-Budget contain invalid syntax, non-numeric budget strings, or unrecognized preset names, resolveRequestAutoControls returns an empty object or omits the invalid field. Consequently, the merging logic in src/sse/handlers/chat.ts applies only valid overrides, preventing malformed requests from corrupting stored combo definitions or causing runtime exceptions.

Regression coverage exists in tests/unit/auto-combo-request-controls-6024.test.ts, which validates that the resolver correctly aggregates mode and budget headers under various edge cases. The feature is also documented in localized changelog files such as docs/i18n/zh-TW/CHANGELOG.md under issue references #6023, #6024, and #6025.

Summary

• Per-request control: Send X-OmniRoute-Mode and X-OmniRoute-Budget headers to adjust auto-combo behavior without modifying persisted configurations.
• Preset flexibility: Choose from fast, balanced, quality, cheap, reliable, or offline presets, or specify a custom mode-pack name.
• Budget enforcement: Cap spending using decimal USD values (e.g., 0.10 for ten cents).
• Safe defaults: Invalid or missing headers are ignored, ensuring the combo’s stored settings remain intact.
• Core implementation: Header parsing occurs in open-sse/services/autoCombo/requestControls.ts and is applied in src/sse/handlers/chat.ts at lines 42 and 1032.

Frequently Asked Questions

What happens if I send an invalid header value?

OmniRoute silently ignores unrecognized values. If you send an invalid mode name or a non-numeric budget string, resolveRequestAutoControls treats it as if the header were absent, falling back to the combo’s persisted configuration without throwing errors or corrupting stored settings.

Can I use custom mode-pack names instead of presets?

Yes. While X-OmniRoute-Mode accepts friendly presets like fast or quality, you can also supply a raw mode-pack identifier (e.g., my-custom-strategy). When a custom name is provided, it overrides the preset system entirely, allowing you to test experimental scoring configurations on a per-request basis.

Where is the header parsing logic located in the codebase?

The pure resolution logic resides in open-sse/services/autoCombo/requestControls.ts within the resolveRequestAutoControls function. The chat handler at src/sse/handlers/chat.ts imports this function at line 42 and applies the results at line 1032. Additional consumption occurs in open-sse/services/combo/resolveAutoStrategy.ts for strategy loading.

How does the budget header interact with the combo's stored configuration?

The X-OmniRoute-Budget value merges with the existing combo configuration immediately before candidate scoring. If provided, it acts as a strict ceiling that overrides any persisted budget limit for that specific request. If omitted, the engine respects the combo’s original spending configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}