OmniRoute Auto-Combo 12-Factor Algorithm for Provider Selection Explained

The Auto-Combo 12-factor algorithm selects the optimal LLM provider by filtering unavailable candidates and scoring survivors across 12 weighted metrics—including health, cost, latency, and quota—to maximize request success rates.

The Auto-Combo engine in the diegosouzapw/OmniRoute repository automates provider selection using a multi-factor scoring system often referred to as the I²-factor (Integrated Insights) algorithm. This mechanism evaluates every registered connection against a dozen normalized signals to determine which model can best serve a specific request in real-time.

How the Auto-Combo 12-Factor Algorithm Works

The algorithm operates as a two-stage pipeline implemented in open-sse/services/autoCombo/engine.ts. It first eliminates unsuitable providers, then calculates a weighted composite score for the remaining candidates.

Stage 1: Candidate Pool Filtering

Before scoring begins, the engine gathers all registered connections for the requested category (e.g., auto/coding or auto/vision). It immediately excludes any provider that is unavailable due to:

• An open circuit-breaker indicating recent failures
• An active cooldown period
• Exhausted quota limits
• Model lockout states

This filtration produces a sanitized candidate pool containing only providers capable of accepting traffic.

Stage 2: 12-Factor Weighted Scoring

Each surviving candidate receives a score calculated from 12 normalized factors defined in open-sse/services/autoCombo/scoring.ts. The default metrics include:

• Health and availability status
• Quota remaining relative to limits
• Cost per token
• Latency (average response time)
• Success rate over recent windows
• Freshness of the last successful request
• Tier priority (Free vs. Pro/Ultra account classifications)

Each factor is normalized to a [0, 1] scale and multiplied by its corresponding value in the DEFAULT_WEIGHTS configuration. The sum of these weighted products yields the final score, with the highest-scoring candidate winning the request.

Stage 3: Dynamic Overrides via Mode Packs

Clients can bias the algorithm without modifying stored configurations by sending the X-OmniRoute-Mode header. Valid mode packs—including fast, balanced, quality, cheap, reliable, and offline—substitute the default weights with preset values that prioritize specific factors like latency or cost.

Stage 4: Budget Cap Constraints

The optional X-OmniRoute-Budget header accepts a USD value that enforces a hard spending limit per request. The engine filters out candidates whose estimated costs exceed this cap before the scoring stage executes.

Core Implementation Files

According to the diegosouzapw/OmniRoute source code, three files define the algorithm's behavior:

• open-sse/services/autoCombo/scoring.ts: Contains the DEFAULT_WEIGHTS constant and normalization logic for the 12 factors.
• open-sse/services/autoCombo/engine.ts: Orchestrates candidate collection, filtering, mode-pack application, and final selection via argmax on the score map.
• docs/routing/AUTO-COMBO.md: Documents the 12-factor scoring diagram and architectural overview.

Code Examples

Basic Auto-Combo Request

import { OpenRouter } from "omniroute";

const client = new OpenRouter({ apiKey: process.env.OMNI_API_KEY });

await client.chat.completions.create({
  model: "auto/vision",
  messages: [{ role: "user", content: "Describe this image." }],
});

Applying Mode Packs and Budget Caps

await client.chat.completions.create({
  model: "auto/coding",
  messages: [{ role: "user", content: "Write a quick sort in Python." }],
  headers: {
    "X-OmniRoute-Mode": "fast",
    "X-OmniRoute-Budget": "0.01",
  },
});

Inspecting the Selected Provider

const resp = await client.chat.completions.create({
  model: "auto/embedding",
  messages: [{ role: "user", content: "Encode this sentence." }],
});

console.log("Selected provider:", resp.headers?.get("X-Route-Model"));

Summary

• The Auto-Combo 12-factor algorithm filters providers by health and quota status before scoring to ensure only viable candidates are evaluated.
• Twelve weighted metrics—including cost, latency, and success rate—are normalized and summed to determine the optimal provider for each request.
• Mode packs (X-OmniRoute-Mode) and budget headers (X-OmniRoute-Budget) allow dynamic customization of the selection criteria without code changes.
• The implementation resides primarily in open-sse/services/autoCombo/engine.ts and scoring.ts, providing a self-healing routing layer that adapts to real-time provider conditions.

Frequently Asked Questions

What does the "12-factor" in Auto-Combo refer to?

The 12-factor designation refers to the dozen weighted metrics used to score providers, including health, quota availability, per-token cost, latency averages, success rates, request freshness, and tier priority. These factors are defined in the DEFAULT_WEIGHTS configuration within open-sse/services/autoCombo/scoring.ts.

How does the algorithm handle provider failures?

The algorithm is self-healing: it continuously refreshes health and quota status lazily. When a provider recovers from a temporary failure and its circuit breaker closes, its normalized health score automatically increases, allowing it to re-enter the candidate pool and win requests based on merit.

Can I prioritize speed over cost using Auto-Combo?

Yes. Send the header X-OmniRoute-Mode: fast with your request. This mode pack overrides the default weights to prioritize low-latency providers, while X-OmniRoute-Mode: cheap biases selection toward cost-effective options regardless of speed.

What happens if no provider passes the budget filter?

If the X-OmniRoute-Budget header eliminates all candidates, the request fails with an error indicating that no available provider can satisfy the financial constraint. The engine returns this failure before consuming tokens or routing to an over-budget service.

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