# What Is Auto-Combo in OmniRoute and How Does Its Scoring System Work?

> Discover Auto-Combo in OmniRoute, the zero-config engine that picks optimal providers with a 14-factor scoring system. Learn how it works for efficient routing.

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

---

**Auto-Combo is OmniRoute's zero-config routing engine that automatically selects the optimal provider-model for each request using a 14-factor weighted scoring function.**

OmniRoute's **Auto-Combo** eliminates manual provider selection by building transient provider combinations on-the-fly. When you send `model: "auto"` or `model: "auto/<variant>"`, the system evaluates every available provider-model through a multi-factor scoring pipeline—no persisted combo objects or extra API calls required. This article breaks down the scoring architecture, customization options, and implementation details from the OmniRoute source code.

## How Auto-Combo Works: The Virtual Factory Pattern

The **virtual factory** pattern is the core mechanism behind Auto-Combo. Located in [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts), this component constructs a temporary combo for each incoming request rather than maintaining static provider configurations.

When a request arrives with `model: "auto"`, the factory immediately:

1. Generates a candidate pool from available providers
2. Applies filtering constraints (resilience, quota, tier)
3. Executes the scoring pipeline
4. Returns the highest-ranked provider-model

This transient approach means **zero persisted state** and **no additional API overhead**—the combo exists only for the duration of the request.

## The 14-Factor Scoring System Explained

The scoring engine lives in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts) and evaluates candidates across **14 weighted factors**. These factors capture cost, performance, reliability, and operational health:

| Factor Category | Specific Factors |
|-----------------|----------------|
| **Resource Health** | Quota health, provider health, circuit-breaker status |
| **Cost & Performance** | Cost per token, latency (TTFT, total), throughput |
| **Stability** | Latency variance, error rate, uptime history |
| **Task Fit** | Model capability alignment with request type |
| **Tier & Operational** | Provider tier, quota utilization, geographic proximity |

The **default weight sum is 1.05**, allowing slight overweighting of critical reliability factors. Custom distributions are automatically normalized before scoring to maintain comparable score ranges.

### Score Calculation Process

The `scorePool()` function—implemented as a 9-factor variant in the ranking stage—executes four sequential steps:

- **Candidate Pool Filtering**: Removes providers failing resilience checks, quota limits, or tier requirements
- **Factor Evaluation**: Computes normalized scores for each of the 14 factors
- **Weighted Summation**: Multiplies factor scores by their configured weights
- **Rank & Select**: Returns the provider-model with highest composite score

Here's a practical example requesting Auto-Combo with performance preferences:

```typescript
// Request with "fast" preset for low-latency routing
fetch("https://omniroute.local/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-OmniRoute-Mode": "fast",      // Overrides default weights
    "X-OmniRoute-Budget": "0.02"     // Hard USD cost ceiling per request
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Explain quantum tunnelling." }]
  })
});

```

## Customizing Auto-Combo with Mode Packs

The `X-OmniRoute-Mode` header in [`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts) enables runtime weight customization through **preset mode packs** or custom pack names:

| Mode Pack | Weight Emphasis | Ideal Use Case |
|-----------|---------------|--------------|
| **fast / ship-fast** | Latency, health | Real-time applications, streaming |
| **cheap / cost-saver** | Cost minimization | Batch processing, high-volume workloads |
| **reliable** | Circuit-breaker health, latency stability | Production-critical systems |
| **offline** | Uptime, low quota usage | Resilient fallback scenarios |
| **balanced** *(default)* | Even distribution across all factors | General-purpose routing |

Custom packs defined in the OmniRoute UI can also be referenced directly:

```typescript
// Using a UI-defined custom weight pack
fetch("/v1/chat/completions", {
  method: "POST",
  headers: {
    "X-OmniRoute-Mode": "quality-first"  // Custom accuracy-focused weights
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Write a haiku." }]
  })
});

```

The `X-OmniRoute-Budget` header provides an additional **hard cost ceiling** in USD—requests exceeding this threshold are rejected regardless of scoring outcomes.

## Key Source Files and Their Roles

| File Path | Purpose |
|-----------|---------|
| [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts) | Defines `DEFAULT_WEIGHTS` and `scorePool()` ranking logic |
| [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts) | Implements transient combo construction for `model: "auto"` |
| [`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts) | Parses `X-OmniRoute-Mode` and `X-OmniRoute-Budget` headers |
| [`docs/routing/AUTO-COMBO.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/AUTO-COMBO.md) | Complete user guide with full factor documentation |
| `docs/diagrams/exported/auto-combo-12factor.svg` | Visual reference for 13 of 14 scoring factors |

## Summary

- **Auto-Combo** automatically selects provider-models via transient combos—no manual configuration or persisted state required
- **14 weighted factors** in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) evaluate cost, latency, reliability, and operational health
- **`X-OmniRoute-Mode`** header enables runtime weight customization through presets (`fast`, `cheap`, `reliable`, `offline`) or custom packs
- **`X-OmniRoute-Budget`** enforces hard USD cost ceilings per request
- **`scorePool()`** ranks candidates and returns the optimal provider-model for each request

## Frequently Asked Questions

### How many factors does OmniRoute Auto-Combo evaluate?

OmniRoute Auto-Combo evaluates **14 factors** by default, including quota health, provider health, cost, latency metrics, task-fit, stability measures, and tier-related indicators. The `scorePool()` ranking function uses a 9-factor subset for final candidate ordering. All factors and their default weights are defined in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts).

### Can I use Auto-Combo without any configuration?

Yes. Auto-Combo is designed as a **zero-config routing layer**. Simply set `model: "auto"` in your request body. The system uses the `balanced` weight preset by default and automatically filters providers by health, quota, and resilience status. No combo objects need to be created or maintained.

### What happens if no provider passes the scoring filters?

If all candidates fail the filtering stage—due to circuit-breaker states, quota exhaustion, or budget constraints—the request is rejected with an appropriate error response. The [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts) handles this graceful degradation path.

### How do custom mode packs interact with the default weights?

Custom mode packs specified via `X-OmniRoute-Mode` **completely override** the `DEFAULT_WEIGHTS` table defined in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts). The override occurs in [`requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/requestControls.ts), and any custom weight distribution is normalized before scoring to ensure comparable score ranges across different configurations.