How OmniRoute's Auto-Combo Routing Works with the I²-Factor Live Scoring System

OmniRoute's auto-combo routing selects the optimal model for each request by scoring candidate providers against a multi-dimensional I²-factor system that weights latency, reliability, cost, cache affinity, and quota status in real time.

The auto-combo engine in OmniRoute transparently handles model selection when you don't specify a provider, using live telemetry to make intelligent routing decisions. This article explains the complete I²-factor scoring pipeline, from candidate pool construction to final selection, based on the actual implementation in the diegosouzapw/OmniRoute codebase.

What Is Auto-Combo Routing?

Auto-combo routing is OmniRoute's mechanism for automatic model selection. When a request arrives without an explicit model (or when the requested model is unavailable), the system builds a virtual combo—a temporary provider-model pair scored and selected on-the-fly rather than fetched from the database.

This differs from static combos, which are preconfigured provider-model mappings stored in the database. Auto-combos are ephemeral and computed per-request, enabling dynamic adaptation to real-time conditions.

Building the Candidate Pool

The pool construction happens in open-sse/services/autoCombo/virtualFactory.ts.

The process works as follows:

1. Gather eligible providers — All providers with valid connections are collected, including no-auth providers that pass allow-list checks.
2. Create virtual entries — For each candidate, the factory constructs a virtual combo object with model: "auto".
3. Pass to scoring pipeline — The candidate list flows into the I²-factor scoring system for evaluation.

// Conceptual flow from virtualFactory.ts
const candidates = providers
  .filter(p => p.isConnected || noAuthAllowed.includes(p.id))
  .map(p => ({ provider: p.id, model: "auto", virtual: true }));
// candidates → autoStrategy.ts for scoring

The I²-Factor Scoring Pipeline

The core scoring logic resides in open-sse/services/combo/autoStrategy.ts and src/lib/combos/intelligentRouting.ts. The I²-factor name represents "intelligence-informed" scoring—the product of multiple weighted dimensions that together produce a single normalized score.

The Five Scoring Dimensions

Factor	Data Source	Normalization	Impact
Latency (L)	src/lib/usage/usageHistory.ts	Inverse percentile (lower = better)	Prefers responsive providers
Reliability (R)	src/lib/usage/usageHistory.ts	Success-rate percentage	Avoids error-prone endpoints
Cost per 1M tokens (C)	Telemetry aggregation	Relative to cheapest option	Favors economical providers
Cache affinity (A)	open-sse/services/combo/promptCacheAffinity.ts	Hit-rate for prompt signature	Rewards warm cache hits
Quota soft penalty (Q)	autoStrategy.ts internal tracking	Linear penalty when quota > threshold	Deprioritizes exhausted providers

The Scoring Equation

Each factor produces a value between 0 and 1. The I² score is computed as a weighted sum:

// From open-sse/services/combo/autoStrategy.ts
const i2Score =
  (latencyScore      * weights.latency) +
  (reliabilityScore  * weights.reliability) +
  (costScore         * weights.cost) +
  (cacheAffinity     * weights.cacheAffinity) +
  (quotaPenalty      * weights.quotaPenalty);

// Final clamp to [0, 1] to handle edge cases
const finalScore = Math.max(0, Math.min(1, i2Score));

The quota soft penalty deserves special attention. Rather than hard-blocking exhausted providers, the system applies a multiplicative penalty that scales with quota depletion. This creates graceful degradation—exhausted providers can still win if all other factors strongly favor them, but they're heavily disfavored.

Mode Packs: Configuring I² Weights

The "I" in I² also refers to intelligence packs—preset weight configurations selected via the X-OmniRoute-Mode header.

Mode pack definitions live in src/lib/combos/intelligentRouting.ts. Common presets include:

Mode Pack	Latency	Reliability	Cost	Cache	Quota
default	0.25	0.25	0.20	0.20	0.10
latency-focused	0.40	0.30	0.10	0.15	0.05
cost-focused	0.15	0.20	0.45	0.10	0.10
reliability-focused	0.20	0.40	0.15	0.15	0.10

// Sending a cost-optimized request
fetch('/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-OmniRoute-Mode': 'cost-focused'
  },
  body: JSON.stringify({ prompt: 'Summarize this article.' })
});
// → I² scoring weights cost at 0.45, prioritizing cheaper providers

Custom mode packs can be registered via the registerModePack() function in intelligentRouting.ts.

Fallback Handling and Resilience

When the top-scoring candidate fails during execution, the auto-combo system initiates fallback iteration:

1. Increment quota penalty for the failed provider in the scoring context
2. Re-run I² scoring with adjusted weights
3. Select next best candidate from remaining pool
4. Emit circuit-breaker telemetry to src/lib/usage/usageHistory.ts for future reliability adjustments

This loop continues until success or pool exhaustion. Complete exhaustion triggers a 503 response with diagnostic context.

Live Scoring Diagnostics

For observability, src/lib/usage/comboScoringInspector.ts generates detailed factor breakdowns. These traces expose:

• Raw factor values before normalization
• Applied weights from the active mode pack
• Intermediate products (factor × weight)
• Final I² score and ranking

Access via the debug endpoint:

# Request with debug flag to see I²-factor breakdown

curl -H "X-OmniRoute-Debug: true" \
  -X POST https://api.omniroute.example/v1/chat \
  -d '{"prompt":"test"}'

Response includes:

{
  "autoComboSelection": {
    "selected": "openai/gpt-4o",
    "i2Score": 0.847,
    "factors": {
      "latency": { "raw": 145, "normalized": 0.92, "weighted": 0.23 },
      "reliability": { "raw": 0.997, "normalized": 0.997, "weighted": 0.249 },
      "cost": { "raw": 5.00, "normalized": 0.60, "weighted": 0.12 },
      "cacheAffinity": { "raw": 0.85, "normalized": 0.85, "weighted": 0.17 },
      "quotaPenalty": { "raw": 0.1, "normalized": 0.9, "weighted": 0.078 }
    },
    "modePack": "default",
    "fallbackDepth": 0
  }
}

Complete Usage Example

// Ultra-low-latency auto-combo with fallback visibility
async function streamWithAutoCombo(prompt: string) {
  const response = await fetch('/api/v1/chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-OmniRoute-Mode': 'latency-focused',
      'X-OmniRoute-Debug': 'true',
      'Accept': 'text/event-stream'
    },
    body: JSON.stringify({ prompt, stream: true })
  });

  // I² scoring metadata available in X-OmniRoute-Selection header
  const selection = JSON.parse(response.headers.get('X-OmniRoute-Selection'));
  console.log(`Selected ${selection.provider}/${selection.model} with I² score ${selection.i2Score}`);

  return response.body;
}

Summary

• Auto-combo routing creates virtual provider-model pairs on-the-fly instead of using static database entries
• I²-factor scoring combines five live dimensions—latency, reliability, cost, cache affinity, and quota status—into a single weighted score
• Mode packs via X-OmniRoute-Mode adjust factor weights for latency-focused, cost-optimized, or reliability-first routing
• autoStrategy.ts contains the core scoring algorithm with quota soft-penalty handling
• Fallback iteration preserves availability by re-scoring with adjusted penalties when candidates fail

Frequently Asked Questions

What does "I²" stand for in OmniRoute's scoring system?

I² stands for "intelligence-informed" scoring. It represents the two-layer intelligence: first, the live telemetry that informs each factor (latency, reliability, cost, cache, quota), and second, the configurable mode-pack weights that inform how those factors combine. The squared notation also hints at the multiplicative interaction between real-time data and policy configuration.

How does the quota soft penalty differ from hard quota enforcement?

The quota soft penalty in open-sse/services/combo/autoStrategy.ts applies a scoring degradation rather than a hard block. As a provider approaches its quota limit, its I² score receives an increasingly severe multiplicative penalty. This allows exhausted providers to still win if they're dramatically superior on all other factors, but makes such selection unlikely. Hard enforcement would create availability gaps when quotas cluster.

Can I create custom mode packs for specialized workloads?

Yes. Custom mode packs can be registered programmatically via registerModePack() in src/lib/combos/intelligentRouting.ts, or injected via configuration. Each pack defines the five weight coefficients that the I² scorer applies. This enables domain-specific routing—for example, a batch-processing pack that maximizes cost savings for offline jobs, or a real-time-audio pack that prioritizes sub-100ms latency above all else.

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