# How the OmniRoute Auto-Combo Engine Scores Candidates for Model Selection

> Discover how the OmniRoute Auto-Combo engine scores candidates using a 15-factor weighted formula for optimal model selection and provider connection evaluation.

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

---

**The OmniRoute Auto-Combo engine evaluates every active provider connection using a deterministic 15-factor weighted formula to select the highest-scoring candidate for each request.**

The **Auto-Combo** feature in the [OmniRoute](https://github.com/diegosouzapw/OmniRoute) repository dynamically routes LLM requests to the optimal provider and model by computing a composite score across multiple performance dimensions. When a request arrives with an `auto` model prefix, the engine builds a virtual pool of candidates and applies a normalized scoring function defined in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts) to determine the best match.

## The 15-Factor Scoring Algorithm

The scoring pipeline operates per-request without persisting state, ensuring that new providers or refreshed credentials are immediately available for routing. The process begins in [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts), which constructs an in-memory pool of `VirtualAutoComboCandidate` objects from all active connections. Each candidate is then evaluated by the `scorePool()` function using the following weighted factors:

| Factor | Default Weight | Description |
|--------|----------------|-------------|
| `quota` | **0.1429** | Remaining quota or rate-limit headroom, normalized to a 0–1 scale. |
| `health` | **0.1605** | Circuit-breaker health status (CLOSED = 1.0, HALF_OPEN = 0.5, OPEN = 0.0). |
| `costInv` | **0.1429** | Inverse blended cost (60% input + 40% output token pricing). |
| `latencyInv` | **0.1143** | Inverse of p95 latency, normalized across the candidate pool. |
| `taskFit` | **0.0762** | Task-type fitness matching (coding, review, planning, analysis, debugging, docs). |
| `stability` | **0.0476** | Low latency standard deviation and error rate signal. |
| `tierPriority` | **0.0476** | Account tier priority (Ultra = 1.0, Pro = 0.67, Standard = 0.33, Free = 0.0). |
| `tierAffinity` | **0.0476** | Alignment between the candidate’s tier and the manifest-recommended tier. |
| `specificityMatch` | **0.0476** | Match between request specificity hints and model capabilities. |
| `contextAffinity` | **0.0476** | Affinity between the request’s context-window requirements and the model’s capacity. |
| `sessionAvailability` | **0.0476** | OAuth session availability score (non-OAuth connections default to 1.0). |
| `connectionDensity` | **0.0476** | Anti-concentration factor to distribute load across multiple connections. |
| `cacheAffinity` | **0.00** | Rendezvous-hash affinity for cached prompt prefixes (disabled by default). |
| `resetWindowAffinity` | **0.00** | Bias toward connections with favorable quota reset windows (disabled by default). |
| `quality` | **0.03** | Feedback-driven quality signal from the routing-event tracker (neutral 0.5 if no data exists). |

The default weights sum to **1.0**, and custom weight profiles are normalized before application. The candidate with the highest total weighted score wins the request.

## Mode Packs and Weight Profiles

OmniRoute provides four built-in **mode packs** that reconfigure the scoring weights to optimize for specific operational goals. These are defined in [`open-sse/services/autoCombo/modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/modePacks.ts):

| Mode Pack | Key Weight Adjustments | Use Case |
|-----------|------------------------|----------|
| **ship-fast** | `latencyInv` = 0.32, `health` = 0.28 | Prioritize low-latency, healthy connections for rapid responses. |
| **cost-saver** | `costInv` = 0.37 | Heavily favor the cheapest available providers. |
| **quality-first** | `taskFit` = 0.37, `stability` = 0.15 | Select the best model for the specific task with high consistency. |
| **offline-friendly** | `quota` = 0.37, `health` = 0.28 | Maximize quota headroom for resilient offline routing. |

You can activate a mode pack using the `X-OmniRoute-Mode` request header with aliases like `fast`, `cheap`, `quality`, or the raw pack names.

## Per-Request Controls

The engine accepts several HTTP headers to override scoring behavior dynamically. These are parsed in [`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts):

| Header | Effect |
|--------|--------|
| `X-OmniRoute-Mode` | Selects a preset alias (`fast`, `balanced`, `quality`, `cheap`, `reliable`, `offline`) or a raw mode pack name to override weights for the current request. |
| `X-OmniRoute-Budget` | Specifies a USD budget cap; candidates exceeding this cost are filtered before scoring. |
| `X-OmniRoute-Budget-Fallback` | Controls budget enforcement: `cheapest` (allows cheapest candidate even if over budget) or `strict` (returns HTTP 402 if no candidate fits). |

## Implementation Architecture

The scoring system spans several key files in the OmniRoute codebase:

- **[`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts)** – Implements the `scorePool()` function and the `DEFAULT_WEIGHTS` constant containing the 15-factor formula.
- **[`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts)** – Builds the candidate pool by aggregating active provider connections and their metadata.
- **[`open-sse/services/autoCombo/modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/modePacks.ts)** – Exports the weight profile definitions for the four built-in mode packs.
- **[`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts)** – Handles header parsing and applies per-request overrides before scoring begins.
- **[`open-sse/services/autoCombo/engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/engine.ts)** – Orchestrates the full selection process, including bandit exploration and self-healing logic.
- **[`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts)** – Detects the `auto/` model prefix and routes the request to the virtual auto-combo engine.

## Usage Examples

### Zero-Config Request with Mode Selection

The following curl command demonstrates routing with the `fast` mode pack and a strict budget constraint:

```bash
curl -sS http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Mode: fast" \
  -H "X-OmniRoute-Budget: 0.05" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Explain the scoring algorithm"}]}'

```

In this flow, [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) detects the `auto` prefix, [`virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/virtualFactory.ts) assembles the candidate pool, and [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) computes the final scores using the `ship-fast` weight profile.

### Persisted Auto-Combo with Custom Weights

For consistent custom scoring across requests, define a persisted combo with explicit weights:

```json
{
  "name": "My-Auto-Combo",
  "strategy": "auto",
  "config": {
    "routerStrategy": "rules",
    "auto": {
      "weights": {
        "quota": 0.20,
        "health": 0.20,
        "costInv": 0.10,
        "latencyInv": 0.30,
        "taskFit": 0.15,
        "stability": 0.05
      }
    }
  }
}

```

POST this configuration to `/api/combos`. Subsequent requests using `model: "My-Auto-Combo"` will invoke the same scoring engine with your custom weight distribution, processed by [`open-sse/services/autoCombo/engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/engine.ts).

## Summary

- The **OmniRoute Auto-Combo engine** uses a deterministic **15-factor weighted formula** to score candidates per-request.
- Key factors include **health** (0.1605), **quota** (0.1429), **costInv** (0.1429), and **latencyInv** (0.1143), with **mode packs** available to re-prioritize these weights.
- The scoring implementation resides in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts), while candidate pool generation occurs in [`virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/virtualFactory.ts).
- Users control routing behavior via the `X-OmniRoute-Mode` and `X-OmniRoute-Budget` headers, or by defining persisted combos with custom weight objects.

## Frequently Asked Questions

### How does OmniRoute handle circuit-breaker states during scoring?

The **health** factor (weight 0.1605) in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts) maps circuit-breaker states directly to numeric values: CLOSED connections score 1.0, HALF_OPEN score 0.5, and OPEN score 0.0. This ensures unhealthy providers are heavily penalized or eliminated from selection unless no alternatives exist.

### Can I disable specific scoring factors?

Yes. While you cannot remove factors entirely, you can set their weights to **0.00** in a custom weight profile. Both `cacheAffinity` and `resetWindowAffinity` default to 0.00 in the standard configuration, effectively disabling them unless explicitly enabled.

### What happens if multiple candidates receive the same score?

When scores tie, the engine applies secondary selection logic within [`open-sse/services/autoCombo/engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/engine.ts), including bandit exploration for quality discovery and connection density balancing to prevent over-concentration on a single provider account.

### Is the scoring deterministic for identical requests?

The core 15-factor formula is deterministic given identical candidate pools and weights. However, per-request factors like **sessionAvailability**, **quota** headroom, and circuit-breaker **health** states change dynamically, meaning the same request may route differently as provider conditions evolve.