# OmniRoute 15-Factor Auto-Combo Scoring: Complete Technical Guide

> Discover OmniRoute's 15-factor auto-combo scoring system. Learn how it ranks LLM connections using quota, health, cost, and fitness for optimal performance.

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

---

**OmniRoute's Auto-Combo engine uses a weighted 15-factor algorithm to rank LLM provider connections, combining signals like quota availability, circuit-breaker health, inverse cost, and task fitness into a composite score ranging from 0 to 1.**

OmniRoute, an open-source intelligent routing layer maintained in the `diegosouzapw/OmniRoute` repository, automatically selects optimal model providers through a sophisticated scoring system defined in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts). The `DEFAULT_WEIGHTS` configuration assigns specific weights to 15 distinct factors that collectively determine routing decisions at request time.

## The 15-Factor Weight Configuration

The scoring algorithm evaluates each candidate connection using the following factors, where weights sum to exactly 1.0:

### Core Capacity and Health Signals

- **`health`** (0.1605): Circuit-breaker state where **CLOSED** = 1.0, **HALF_OPEN** = 0.5, and **OPEN** = 0.0.
- **`quota`** (0.1429): Remaining rate-limit headroom normalized as a ratio from 0 to 1.
- **`costInv`** (0.1429): Inverse blended cost calculated from 60% input token price and 40% output token price.
- **`latencyInv`** (0.1143): Inverse of p95 latency measurements, where faster response times yield higher scores.

### Task and Context Alignment

- **`taskFit`** (0.0762): Fitness rating for specific task types including coding, review, planning, analysis, debugging, and documentation.
- **`contextAffinity`** (0.0476): Match between the request's required context window and the model's available context capacity.
- **`specificityMatch`** (0.0476): Alignment between the request's specificity manifest hint and the model's designated tier.

### Account and Tier Management

- **`tierPriority`** (0.0476): Account tier weighting where Ultra = 1.0, Pro = 0.67, Standard = 0.33, and Free = 0.0.
- **`tierAffinity`** (0.0476): Compatibility between the candidate's service tier and the manifest-recommended tier.
- **`sessionAvailability`** (0.0476): OAuth session availability status retrieved via `getOAuthSessionAvailability()`.

### Stability and Load Distribution

- **`stability`** (0.0476): Variance-based metric incorporating latency standard deviation and error rates.
- **`connectionDensity`** (0.0476): Anti-concentration load-balancing measure across connections sharing the same provider.

### Feedback and Advanced Signals

- **`quality`** (0.03): Output quality feedback from the routing-event quality tracker; candidates without historical observations receive a neutral 0.5 score.
- **`cacheAffinity`** (0.00): Rendezvous-hash affinity for prompt-cache prefix hits (disabled by default).
- **`resetWindowAffinity`** (0.00): Preference for connections approaching favorable quota-reset windows (disabled by default).

## How the Scoring Pipeline Executes

The Auto-Combo engine processes every request through a four-stage pipeline implemented across the `open-sse/services/autoCombo/` directory:

1. **Candidate pool creation**: The [`virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/virtualFactory.ts) module builds virtual candidates from all active provider connections.
2. **Factor computation**: The `scorePool()` function in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) calculates all 15 factors for each candidate.
3. **Weight application**: The system applies either `DEFAULT_WEIGHTS` or a selected weight pack from [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts) to generate composite scores.
4. **Selection**: The highest-scoring candidate is selected for the request.

This evaluation occurs entirely at request time without persisting combo selections to the database.

## Practical Implementation Examples

Trigger the default 15-factor scoring by specifying `model: "auto"` in your request:

```typescript
import fetch from "node-fetch";

await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Explain the 15-factor scoring table." }],
  }),
});

```

Override default weights using the `X-OmniRoute-Mode` header to select predefined weight packs:

```typescript
await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
    "X-OmniRoute-Mode": "fast",
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Prioritize low latency." }],
  }),
});

```

## Customizing Behavior with Mode Packs

The [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts) file defines alternative weight profiles that bias the engine toward specific operational goals:

- **ship-fast**: Prioritizes `latencyInv` and `health` for rapid response times.
- **cost-saver**: Maximizes `costInv` weighting to minimize token expenses.
- **quality-first**: Emphasizes the `quality` factor and `stability` metrics.
- **offline-friendly**: Optimizes for `connectionDensity` and session availability.

These packs modify the default weight distribution while maintaining the full 15-factor evaluation framework.

## Summary

- OmniRoute's **15-factor scoring** combines health, quota, cost, latency, and contextual signals into a normalized composite score.
- The **`DEFAULT_WEIGHTS`** table in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) allocates the highest weights to health (0.1605), quota (0.1429), and cost (0.1429).
- **Two factors** (`cacheAffinity` and `resetWindowAffinity`) are disabled by default with 0.00 weights but remain available for custom configurations.
- **Mode packs** allow runtime weight adjustments via the `X-OmniRoute-Mode` header without modifying source code.
- The entire scoring pipeline executes at request time in `scorePool()` without database persistence.

## Frequently Asked Questions

### What is the difference between tierPriority and tierAffinity?

**`tierPriority`** assigns base scores based on the user's account tier (Ultra, Pro, Standard, Free), while **`tierAffinity`** measures how well a specific model's tier matches the tier recommended in the request manifest. The first rewards high-tier accounts, and the second optimizes for tier-specific model selection.

### How does OmniRoute handle disabled factors like cacheAffinity?

Factors with **0.00 weights** such as `cacheAffinity` and `resetWindowAffinity` are calculated but do not contribute to the composite score in default configurations. Developers can enable them by assigning positive weights in custom mode packs or by modifying the `DEFAULT_WEIGHTS` constant in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts).

### How is the quality factor calculated for new connections?

The **`quality`** factor relies on historical observations from the routing-event tracker. Candidates without prior observation data receive a **neutral default score of 0.5**, preventing new connections from being penalized while the system gathers performance data.

### Can I implement custom weight packs beyond the predefined modes?

Yes. The [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts) exports weight configurations that override `DEFAULT_WEIGHTS`. You can define custom weight objects that redistribute the 1.0 total across the 15 factors, then reference them through application-specific routing logic or extended header values.