# OmniRoute Auto-Combo Engine 12-Factor Scoring: How the I²-Factor Works

> Discover how OmniRoute's auto-combo engine uses 12-factor scoring and the I²-factor to dynamically rank providers based on cost, latency, and status. Optimize your routes efficiently.

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

---

**The OmniRoute auto-combo engine uses a 12-factor weighted scoring system where the I²-factor (inverse-impact multiplier) penalizes expensive, slow, or quota-constrained providers by multiplying normalized quota-share, cost-inverse, latency-inverse, and status-deprioritization values to dynamically rank candidates.**

The **OmniRoute** repository (`diegosouzapw/OmniRoute`) implements an intelligent routing layer that automatically selects the optimal provider and model pair for each request. At the heart of this system lies a sophisticated 12-factor scoring algorithm that balances speed, cost, stability, and resource availability, with the unique **I²-factor** serving as a critical penalty multiplier against resource-intensive candidates.

## How the Auto-Combo Engine Generates Candidates

Before scoring begins, the engine constructs a filtered list of viable provider/model pairs. In [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), the combo resolution logic expands configuration patterns into an ordered list of `ResolvedComboTarget` objects. These candidates then undergo filtering in [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts), which prunes entries lacking required credentials or marked as disabled.

Each surviving candidate carries telemetry data—including quota usage, health status, real-time cost, and recent latency—that feeds directly into the 12-factor scoring pipeline.

## The 12-Factor Scoring Architecture

The scoring implementation spans several specialized modules under `open-sse/services/autoCombo/`:

- **[`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts)** – Defines the `ScoringFactors` interface and the `calculateScore` function that computes the final [0–1] ranking value
- **[`speedRanking.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/speedRanking.ts)** – Calculates the speed-ranking sub-score covering TTFT (Time To First Token), TPS (Tokens Per Second), E2E latency, P95 metrics, reliability, and health
- **[`routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/routerStrategy.ts)** – Implements the `RulesStrategy` that injects speed-based factors into the scoring pipeline
- **[`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts)** – Adds soft-policy factors including quota-share, status-deprioritization, and the **I²-factor** calculation

The `calculateScore` function aggregates these inputs through a weighted sum:

```ts
export function calculateScore(factors: ScoringFactors, weights: ScoringWeights): number {
  return clamp01(
    weights.quota * factors.quota +
    weights.health * factors.health +
    weights.costInv * factors.costInv +
    weights.latencyInv * factors.latencyInv +
    weights.taskFit * factors.taskFit +
    weights.stability * factors.stability +
    weights.tierPriority * factors.tierPriority +
    (weights.tierAffinity ?? 0) * factors.tierAffinity +
    (weights.specificityMatch ?? 0) * factors.specificityMatch +
    (weights.contextAffinity ?? 0) * factors.contextAffinity +
    (weights.cacheAffinity ?? 0) * (factors.cacheAffinity ?? 0) +
    (weights.resetWindowAffinity ?? 0) * factors.resetWindowAffinity +
    (weights.connectionDensity ?? 0) * factors.connectionDensity
  );
}

```

## Understanding the I²-Factor Calculation

The **I²-factor** (inverse-impact) is a penalty multiplier computed in [`open-sse/services/autoCombo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/autoStrategy.ts) that captures how resource-intensive a candidate is. It combines four normalized [0–1] sub-factors through multiplication:

| Sub-Factor | Source | Purpose |
|------------|--------|---------|
| **Quota-share** | [`src/lib/db/quotaSnapshots.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/quotaSnapshots.ts) | Remaining quota percentage; near-limit providers score lower |
| **Cost-inverse** | [`src/lib/pricingSync.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/pricingSync.ts) | `1 / cost` where cost is USD per token; cheaper providers score higher |
| **Latency-inverse** | [`src/lib/db/providerLimits.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providerLimits.ts) | `1 / latency` based on recent measurements; faster endpoints score higher |
| **Status-deprioritization** | [`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts) | Soft-policy dampener for unhealthy or exhausted providers |

The calculation follows this pattern (see the `// I²-factor` comment block in [`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts)):

```ts
const i2Factor =
    Math.max(0, quotaShare) *
    Math.max(0, costInv) *
    Math.max(0, latencyInv) *
    statusDep;          // already clamped to [0,1]

```

If any sub-factor hits 0, the I²-factor collapses to 0, effectively eliminating the candidate from selection. The resulting multiplier is folded into the `quota`, `costInv`, and `latencyInv` entries before they enter the weighted sum in `calculateScore`, implicitly down-weighting resource-heavy candidates while preserving the influence of task-fit and stability factors.

## End-to-End Routing Flow

The complete auto-combo pipeline executes in five stages within [`open-sse/services/autoCombo/engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/engine.ts):

1. **Resolve Combo** – [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts) generates the initial candidate list
2. **Collect Telemetry** – Each target receives a `ScoringFactors` object populated from quota snapshots, pricing data, and latency metrics
3. **Apply I²-Factor** – The inverse-impact multiplier is computed and applied to resource-sensitive factors
4. **Weight & Sum** – `calculateScore` produces the final numeric score per candidate
5. **Select Winner** – The highest-scoring candidate is selected; ties trigger fallback strategies (e.g., round-robin)

The chosen target streams back to the request handler in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts), completing the routing decision.

## Debugging 12-Factor Scoring Decisions

Developers can inspect the raw factor values by enabling debug headers. When `x-omniroute-auto-combo-debug` is set to `true`, the API returns a JSON blob showing how each candidate scored across the 12 factors.

```ts
import { OpenAIApi } from '@omniroute/openai-compatible';

const client = new OpenAIApi({
  baseURL: 'https://router.example.com/v1',
  apiKey: process.env.OMNIRoute_API_KEY,
});

client.defaults.headers.common['x-omniroute-auto-combo-debug'] = 'true';

const resp = await client.createChatCompletion({
  model: 'auto',               // Triggers auto-combo engine
  messages: [{ role: 'user', content: 'Explain quantum tunnelling' }],
});

console.log(resp.headers['x-omniroute-auto-combo-debug']);

```

The debug output reveals the I²-factor product alongside individual component scores:

```json
{
  "candidates": [
    {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "score": 0.84,
      "factors": {
        "quota": 0.92,
        "health": 0.99,
        "costInv": 0.87,
        "latencyInv": 0.91,
        "taskFit": 0.97,
        "stability": 0.95,
        "i2Factor": 0.71
      }
    }
  ]
}

```

## Summary

- The **OmniRoute auto-combo engine** evaluates candidates using a **12-factor weighted scoring** system defined in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts)
- The **I²-factor** acts as a penalty multiplier calculated in [`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts) from quota-share, cost-inverse, latency-inverse, and status-deprioritization sub-factors
- Any I²-factor sub-component hitting zero eliminates the candidate, preventing selection of exhausted or expensive providers
- Debug headers expose raw factor values, enabling transparency into routing decisions
- The architecture dynamically balances performance, cost, and availability without manual intervention

## Frequently Asked Questions

### What is the I²-factor in OmniRoute scoring?

The **I²-factor** (inverse-impact factor) is a penalty multiplier computed in [`open-sse/services/autoCombo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/autoStrategy.ts) that quantifies how resource-intensive a provider candidate is. It is calculated as the product of four normalized values: quota-share, cost-inverse, latency-inverse, and status-deprioritization. When multiplied into the final score, it automatically demotes expensive, slow, or quota-constrained providers while favoring efficient alternatives.

### How does OmniRoute handle providers near quota limits?

When a provider approaches its quota cap, the **quota-share** value read from [`src/lib/db/quotaSnapshots.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/quotaSnapshots.ts) approaches zero. Because the I²-factor multiplies this value directly with other resource factors, quota-depleted candidates receive dramatically reduced scores. If quota-share hits zero, the I²-factor collapses to zero, effectively removing the provider from contention until capacity resets.

### Can I disable 12-factor scoring and use strict routing rules?

Yes. While the **auto-combo engine** defaults to 12-factor scoring, OmniRoute supports alternative routing strategies. The [`routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/routerStrategy.ts) module implements a `RulesStrategy` that can bypass dynamic scoring in favor of hard-coded rules or priority lists. Set the appropriate strategy flag in your combo configuration to switch from data-driven scoring to deterministic routing.

### Why does the debug output show different scores for identical providers?

Score variance occurs because **latency-inverse** and **status-deprioritization** values fluctuate based on real-time telemetry stored in [`src/lib/db/providerLimits.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providerLimits.ts) and in-memory health checks. The I²-factor is recalculated for every request, meaning temporary network degradation or momentary quota pressure can shift a provider's ranking between requests even when configuration remains static.