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

> Learn how OmniRoute's auto-combo routing uses the I²-factor scoring system to dynamically choose the best AI provider based on latency, reliability, cost, and more for each request.

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

---

**OmniRoute's auto-combo routing dynamically selects the optimal AI provider by scoring candidates through a multi-dimensional I²-factor algorithm that weights latency, reliability, cost, quota status, and cache affinity to determine the best model for each request.**

When a request hits the diegosouzapw/OmniRoute gateway without specifying a model, the auto-combo routing engine activates to intelligently route traffic. This system leverages the **I²-factor scoring system**—a weighted multi-criteria algorithm that evaluates provider candidates across runtime telemetry dimensions—to ensure low-latency, cost-effective, and reliable AI inference.

## Building the Virtual Candidate Pool

The process begins in [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts), where the engine constructs a virtual candidate pool of provider-model pairs. Rather than querying the database for static combo records, the factory dynamically assembles eligible providers that have active connections, including no-auth providers that meet allow-list criteria. Each candidate receives a temporary virtual combo ID, enabling the scoring pipeline to treat auto-selected routes identically to explicit model selections.

## The I²-Factor Scoring Pipeline

At the heart of the routing decision lies the scoring implementation in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts). This module calculates an **I² score** (Intelligence-Informed score) for each candidate by aggregating normalized factor values multiplied against mode-specific weights. The system derives these factors from runtime telemetry stored in [`src/lib/usage/usageHistory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/usageHistory.ts).

### Latency and Reliability Metrics

The **usage history factor** retrieves real-world latency percentiles and success rates from [`src/lib/usage/usageHistory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/usageHistory.ts). Providers with lower average response times and higher completion rates receive elevated scores, directly improving user-perceived performance.

### Quota Soft Penalty

To prevent routing to exhausted providers, the algorithm applies a **quota soft penalty** calculated in [`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts). When a provider nears its rate limit or token quota, this factor multiplies the candidate's score by a configurable penalty coefficient (typically between 0.1 and 0.9), gracefully pushing traffic toward healthier alternatives without hard failures.

### Cache Affinity

The **cache affinity factor**, processed in the scoring pipeline, checks for recent cache hits on similar prompts. Providers that have previously processed comparable requests receive score bonuses, reducing redundant computation and improving response times for repeated queries.

### Cost Per Token

Economic efficiency enters the equation through the **cost per 1M tokens** factor, sourced from usage telemetry. This value normalizes provider pricing against the global average, allowing the system to prefer budget-friendly options when performance constraints permit.

### Mode Pack Weighting

The final score emerges from a weighted sum defined in [`src/lib/combos/intelligentRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/combos/intelligentRouting.ts). The request's `X-OmniRoute-Mode` header (or default mode pack) specifies weight vectors—such as "latency-focused" or "cost-focused"—that tune the algorithm's priorities without changing the underlying factor calculations.

```typescript
// Simplified scoring logic from autoStrategy.ts
const i2Score = 
  (latencyScore * weights.latency) +
  (reliabilityScore * weights.reliability) +
  (cacheAffinity * weights.cacheAffinity) +
  (normalizedCost * weights.cost) +
  (quotaPenalty * weights.quotaPenalty);

```

## Runtime Selection and Fallback Logic

After computing I² scores, the engine selects the highest-scoring candidate. If that provider fails—triggering a circuit breaker or quota exhaustion—the system executes a **fallback iteration** with increased quota penalty weights. This resilience mechanism, implemented in the auto-combo middleware, ensures graceful degradation across the candidate pool before returning a 503 error.

## Customizing Routing with Mode Packs

Clients influence the I² calculation through the **`X-OmniRoute-Mode`** header. This header selects predefined weight configurations managed in [`intelligentRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/intelligentRouting.ts), allowing specific use cases to prioritize speed over cost or vice versa without modifying server code.

```typescript
// Trigger auto-combo routing (no model specified)
const response = await fetch('https://api.omniroute.example/v1/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'Explain quantum computing' })
});

```

```typescript
// Request with specific mode pack to prioritize cost
const response = await fetch('https://api.omniroute.example/v1/chat', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-OmniRoute-Mode': 'cost-focused'
  },
  body: JSON.stringify({ prompt: 'Generate a summary' })
});

```

## Debugging Auto-Combo Decisions

For observability, [`src/lib/usage/comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/comboScoringInspector.ts) exposes detailed factor breakdowns. Administrators can inspect individual contributions of latency, cost, and penalty values through diagnostic logs or by enabling debug mode on the candidates endpoint.

```bash

# Debug scoring breakdown via admin endpoint

curl "https://api.omniroute.example/v1/auto-combo/default/candidates?debug=true"

```

## Summary

- OmniRoute's auto-combo routing dynamically builds virtual candidate pools in [`virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/virtualFactory.ts) when requests omit specific model parameters.
- The **I²-factor scoring system** evaluates candidates across multiple dimensions including latency, reliability, quota status, cache affinity, and cost.
- Weights are configurable via **mode packs** specified through the `X-OmniRoute-Mode` header, allowing runtime customization of routing priorities.
- **Quota soft penalties** and fallback iterations ensure resilience when primary providers exhaust their limits.
- Diagnostic visibility into scoring decisions is available through [`comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboScoringInspector.ts) for debugging and optimization.

## Frequently Asked Questions

### What does the "I²" in I²-factor scoring stand for?

The I² designation stands for "Intelligence-Informed," representing the system's use of real-time telemetry and historical usage data to inform routing decisions. The squared notation metaphorically represents the multiplicative interaction between the distinct scoring dimensions evaluated for each provider.

### How does the quota soft penalty prevent routing to exhausted providers?

Rather than blocking exhausted providers entirely, the quota soft penalty applies a fractional multiplier (typically 0.1–0.9) to the provider's score based on remaining capacity. This mathematical down-weighting naturally pushes traffic toward healthier candidates while maintaining the exhausted provider as a last-resort option.

### Can I customize which factors matter most for my specific use case?

Yes. By sending the `X-OmniRoute-Mode` header with values like "latency-focused," "cost-focused," or "balanced," you select predefined weight vectors in [`intelligentRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/intelligentRouting.ts) that adjust the relative importance of each I² factor without requiring code changes.

### Where can I see the actual scores calculated for my requests?

Enable diagnostic mode by appending `?debug=true` to the auto-combo candidates endpoint, or check the application logs for entries generated by [`comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboScoringInspector.ts). These outputs expose the normalized factor values and final weighted scores for each candidate considered.