# How OmniRoute's Auto-Combo System Selects the Best Provider Using I² Scoring Factors

> Discover how OmniRoute's auto-combo system selects the best provider using I² scoring. Learn about weighted telemetry factors like quota, latency, cost, and model intelligence to optimize your requests.

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

---

**The OmniRoute auto-combo system evaluates provider candidates using a composite I² (Intelligence & Influence) score calculated from weighted telemetry factors including quota, latency, cost, and model intelligence, selecting the highest-scoring provider for each request.**

The **OmniRoute** repository implements a sophisticated **auto-combo** engine that dynamically routes requests to the optimal AI provider based on real-time telemetry. When a request targets an auto-combo, the system constructs a candidate pool from matching models and ranks providers using a **composite I² score** that balances operational metrics with model intelligence ratings.

## Building the Candidate Pool

The selection process begins with candidate generation in [`builtinCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/builtinCatalog.ts). The system gathers all models matching the requested family, then applies provider-specific filters to ensure quality and diversity.

- **Provider filters** implemented in [`paidModelFilter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/paidModelFilter.ts) and [`resilienceCandidateFilter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/resilienceCandidateFilter.ts) remove unavailable or unsuitable models from consideration.
- **Diversity constraints** from [`providerDiversity.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/providerDiversity.ts) ensure the pool maintains resilience against single-provider failures.
- **Request-control rules** in [`requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/requestControls.ts) apply custom logic based on session context or specific user requirements.

## The I² Scoring Factors

The scoring logic resides in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts) (lines 27-122), where the `calculateScore` function combines **I² factors** (Intelligence & Influence) into a weighted composite. Each factor represents live telemetry critical to provider performance.

### Resource and Health Metrics

These four factors measure provider capacity and operational status:

- **quotaRemaining**: Percentage of account quota remaining, sourced from `quotaTracker` data.
- **latencyMs**: Exponentially-weighted moving average (EMA) of recent request latency from `latencyTracker`.
- **costUsd**: Estimated cost per token or operation retrieved from the internal pricing database.
- **statusHealth**: Binary health indicator (1 for healthy, 0 for unhealthy) from `statusMonitor`, respecting circuit-breaker states.

### Intelligence and Contextual Factors

These specialized factors differentiate model suitability based on capability and context:

- **intelScore**: The core **I² factor** representing model intelligence rank via ELO-style ratings from [`modelIntelligence.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modelIntelligence.ts).
- **cacheAffinity**: Preference score for cached models when [`requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/requestControls.ts) indicates a session cache pin for the request.
- **complexityFit**: Alignment score between request complexity and model capability from [`complexityRouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/complexityRouter.ts).

## Weight Configuration and Normalization

Scoring weights are defined in `DEFAULT_WEIGHTS` ([`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts), line 43) but can be customized per combo or globally.

- **Mode packs** in [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts) provide pre-configured weight bundles (e.g., `ship-fast`, `cost-aware`) for specific operational strategies.
- **Normalization** occurs via `normalizeScoringWeights()` (lines 60-75), which ensures weights sum to 1.0 and fills missing entries with default values.
- **Per-combo overrides** allow explicit JSON weight definitions within the combo configuration itself.

## Score Calculation and Provider Selection

For each candidate, the engine executes `calculateScore()` with the normalized weights to produce a composite ranking:

```typescript
const score = calculateScore({
  quotaRemaining: candidate.quotaRemaining,
  latencyMs: candidate.latency,
  costUsd: candidate.cost,
  statusHealth: candidate.isHealthy ? 1 : 0,
  intelScore: candidate.intel,
  cacheAffinity: candidate.cacheScore,
  complexityFit: candidate.complexityFit,
}, effectiveWeights);

```

The system sorts candidates descending by this composite score. The highest-scoring provider wins the request assignment. If runtime errors occur during request execution, the `handleComboChat` function in [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts) triggers automatic fallback logic to the next-highest-scoring candidate from the sorted pool.

## Runtime Monitoring with the Combo Scoring Inspector

Operators can inspect live selection decisions via the **Combo Scoring Inspector** ([`src/lib/usage/comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/comboScoringInspector.ts)). This utility exposes the full scoring breakdown for each candidate, allowing verification of how individual I² factors and their weights contributed to the final ranking.

## Programmatic Usage Example

Integrate auto-combo selection directly into your application using the pipeline router:

```typescript
import { resolveComboTargets } from '@omniroute/open-sse/services/autoCombo/pipelineRouter';
import { ComboId } from '@omniroute/shared/types';

async function pickProvider(comboId: ComboId) {
  const targets = await resolveComboTargets({ 
    comboId, 
    request: { /* request context */ } 
  });
  // Targets are pre-sorted by composite score (highest first)
  const best = targets[0];
  console.log(`Selected: ${best.providerId} (I² score: ${best.score})`);
  return best;
}

// Execute selection
await pickProvider('auto-combo-1234');

```

The `resolveComboTargets` function internally orchestrates candidate building, weight normalization, and I² scoring as implemented in the OmniRoute source code.

## Summary

- The **auto-combo** engine dynamically selects providers using a **composite I² score** that combines seven telemetry factors from live system data.
- Candidate pools are filtered through [`builtinCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/builtinCatalog.ts), [`paidModelFilter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/paidModelFilter.ts), and [`resilienceCandidateFilter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/resilienceCandidateFilter.ts) before scoring occurs.
- **Weight normalization** in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) ensures configurable scoring via [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts) or per-combo JSON definitions.
- The **intelScore** (I² factor) from [`modelIntelligence.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modelIntelligence.ts) provides the primary differentiation for model quality rankings.
- Runtime visibility and debugging are available through [`comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboScoringInspector.ts), which exposes full factor contributions.

## Frequently Asked Questions

### What does I² stand for in OmniRoute scoring?

I² stands for **Intelligence & Influence**. It represents the composite scoring framework that weighs model intelligence rankings from [`modelIntelligence.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modelIntelligence.ts) alongside operational influence factors including quota availability, latency, and cost.

### How can I customize the scoring weights for a specific auto-combo?

You can define custom weights in the combo's JSON configuration or reference a predefined mode pack from [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts). The `normalizeScoringWeights()` function in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) (lines 60-75) automatically normalizes these values to sum to 1.0 while filling missing entries with defaults.

### What happens if the highest-scoring provider fails at runtime?

The auto-combo system implements fallback logic in `handleComboChat` within [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts). If the selected provider returns an error or becomes unavailable, the engine automatically retries the request with the next-highest-scoring candidate from the sorted pool.

### Where can I view the detailed scoring breakdown for debugging?

Use the **Combo Scoring Inspector** implemented in [`src/lib/usage/comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/comboScoringInspector.ts). This utility exposes individual factor contributions, normalized weights, and final I² scores for each candidate in the selection pipeline.