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

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, 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, 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 – Defines the ScoringFactors interface and the calculateScore function that computes the final [0–1] ranking value
• 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 – Implements the RulesStrategy that injects speed-based factors into the scoring pipeline
• 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:

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 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	Remaining quota percentage; near-limit providers score lower
Cost-inverse	src/lib/pricingSync.ts	1 / cost where cost is USD per token; cheaper providers score higher
Latency-inverse	src/lib/db/providerLimits.ts	1 / latency based on recent measurements; faster endpoints score higher
Status-deprioritization	autoStrategy.ts	Soft-policy dampener for unhealthy or exhausted providers

The calculation follows this pattern (see the // I²-factor comment block in autoStrategy.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:

1. Resolve Combo – 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, 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.

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:

{
  "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
• The I²-factor acts as a penalty multiplier calculated in 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}