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

> Understand the Auto-Combo 12-factor algorithm for optimal LLM provider selection. It filters and scores candidates across 12 metrics to boost success rates.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-09

---

**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](https://github.com/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts)**: Contains the `DEFAULT_WEIGHTS` constant and normalization logic for the 12 factors.
- **[`open-sse/services/autoCombo/engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/AUTO-COMBO.md)**: Documents the 12-factor scoring diagram and architectural overview.

## Code Examples

### Basic Auto-Combo Request

```typescript
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

```typescript
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

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/engine.ts) and [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.