# How OmniRoute's Auto-Combo System Selects Optimal Providers Using 12 Scoring Factors

> Discover how OmniRoute's Auto-Combo system intelligently selects optimal providers using 12 scoring factors. Learn about its weighted I² algorithm for efficient routing.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-17

---

**OmniRoute's Auto-Combo engine uses a weighted I² scoring algorithm to evaluate providers across 12 factors—including quota, latency, cost, and task fitness—then selects the highest-ranked candidate based on configurable routing strategies.**

OmniRoute's auto-combo system intelligently routes API requests to the optimal large language model (LLM) provider by calculating a deterministic score from 12 weighted performance factors. According to the diegosouzapw/OmniRoute source code, the system normalizes raw telemetry into a 0-1 range, allowing operators to fine-tune provider selection without code changes.

## Understanding the I² Scoring Algorithm

The core selection logic lives in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts), where the **I² (Intelligent-Inference) scoring** algorithm processes provider candidates through three deterministic steps:

1. **Metric Collection**: The system aggregates raw `ScoringFactors` from each `ProviderCandidate`, including quota remaining, health status, inverse cost, and task-specific fitness metrics.
2. **Weight Application**: Each factor is multiplied by its corresponding value in the `ScoringWeights` configuration, with defaults defined in `DEFAULT_WEIGHTS` (lines 41-54).
3. **Score Calculation**: The `calculateScore(factors, weights)` function (lines 98-100) sums the weighted values and clamps the result to a [0-1] range, ensuring deterministic ranking.

### Configurable Weight Architecture

The `ScoringWeights` type (lines 26-39) and `DEFAULT_WEIGHTS` object make the system adaptable. Operators can adjust weights at runtime via [`src/lib/db/comboScoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboScoring.ts) to favor specific operational goals, such as prioritizing low latency over cost savings.

## The 12 Scoring Factors Explained

The `ScoringFactors` type (lines 11-24) defines 12 normalized inputs that quantify provider suitability:

- **quota**: Remaining quota percentage (0-100) from `ProviderCandidate.quotaRemaining`
- **health**: Provider health indicator (0-1) from the internal health monitor
- **costInv**: Inverse of cost per 1M tokens, calculated as `1 / costPer1MTokens`
- **latencyInv**: Inverse of 95th-percentile latency, calculated as `1 / p95LatencyMs`
- **taskFit**: Compatibility score between the request and provider's specialty from [`taskFitness.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/taskFitness.ts)
- **stability**: Observed reliability calculated as `1 - errorRate`
- **tierPriority**: Account-tier boost factor (Ultra > Pro > Free) from `accountTier`
- **tierAffinity**: Additional tier-based affinity weighting
- **specificityMatch**: Alignment with manifest-specified provider/model requirements from `manifestAdapter`
- **contextAffinity**: Preference to maintain session continuity using `contextAffinity`
- **resetWindowAffinity**: Preference for providers with imminent quota reset windows
- **connectionDensity**: Load-balancing factor based on current connection pool size, calculated as `1 / connectionPoolSize`

## Provider Selection Flow

The auto-combo pipeline orchestrates four discrete stages across multiple source files:

1. **Candidate Generation**: [`builtinCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/builtinCatalog.ts) constructs `ProviderCandidate` objects containing quota, cost, and latency data from the provider registry.
2. **Scoring Execution**: [`engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/engine.ts) invokes `calculateScore()` for each candidate, producing `ScoredProvider` instances with normalized 0-1 scores.
3. **Ranking**: Candidates sort descending by their computed score.
4. **Strategy Application**: [`routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/routerStrategy.ts) applies the active combo strategy—`priority`, `weighted`, or `fill-first`—to select the final provider from the ranked list.

## Runtime Configuration and Observability

Because weights are runtime-configurable through [`src/lib/db/comboScoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboScoring.ts), operators can dynamically adjust the I² factors without deploying new code. The system also exposes scoring telemetry via [`src/lib/usage/comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/comboScoringInspector.ts), which provides visibility into provider ranking decisions through the `/api/usage/combo-scoring-inspector` endpoint.

## Implementation Example

Below is a practical TypeScript example demonstrating how to calculate provider scores using the I² algorithm:

```typescript
import { calculateScore, DEFAULT_WEIGHTS } from '@omniroute/open-sse/services/autoCombo/scoring';
import type { ProviderCandidate, ScoringFactors } from '@omniroute/open-sse/services/autoCombo/scoring';

// 1. Build a candidate (normally supplied by the catalog)
const candidate: ProviderCandidate = {
  provider: 'openai',
  model: 'gpt-4o',
  quotaRemaining: 78,
  quotaTotal: 100,
  circuitBreakerState: 'CLOSED',
  costPer1MTokens: 0.02,
  p95LatencyMs: 150,
  latencyStdDev: 30,
  errorRate: 0.01,
};

// 2. Assemble raw factors (derived from telemetry)
const factors: ScoringFactors = {
  quota: candidate.quotaRemaining / 100,
  health: 0.92,
  costInv: 1 / candidate.costPer1MTokens,
  latencyInv: 1 / candidate.p95LatencyMs,
  taskFit: 0.8,
  stability: 1 - (candidate.errorRate ?? 0),
  tierPriority: 0.1,
  tierAffinity: 0.1,
  specificityMatch: 0.9,
  contextAffinity: candidate.contextAffinity ?? 0,
  resetWindowAffinity: candidate.resetWindowAffinity ?? 0,
  connectionDensity: 1 / (candidate.connectionPoolSize ?? 1),
};

// 3. Compute the weighted score (I²)
const score = calculateScore(factors, DEFAULT_WEIGHTS);
console.log(`Provider ${candidate.provider}/${candidate.model} scored ${score.toFixed(3)}`);

```

## Summary

- OmniRoute's auto-combo system evaluates providers using **12 weighted scoring factors** defined in [`scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts).
- The **I² algorithm** computes deterministic scores between 0 and 1 by combining raw telemetry with configurable weights.
- **Provider selection** occurs in four stages: candidate generation, scoring via `calculateScore()`, ranking, and strategy application.
- All weights are **runtime-configurable**, allowing dynamic adjustment of routing preferences without code redeployment.
- The system exposes detailed scoring metrics via the [`comboScoringInspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboScoringInspector.ts) endpoint for operational debugging.

## Frequently Asked Questions

### What is the I² scoring algorithm in OmniRoute?

The I² (Intelligent-Inference) scoring algorithm is the mathematical engine in [`open-sse/services/autoCombo/scoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts) that converts 12 normalized provider metrics into a weighted sum clamped between 0 and 1. It enables deterministic comparison of heterogeneous providers by quantifying factors like quota availability, cost efficiency, and latency performance.

### How many factors does OmniRoute use to score providers?

OmniRoute uses **12 distinct scoring factors** defined in the `ScoringFactors` type. These include quota remaining, health status, inverse cost, inverse latency, task fitness, stability, tier priority, tier affinity, specificity match, context affinity, reset window affinity, and connection density.

### Can I adjust the scoring weights without changing the source code?

Yes. The weights stored in `DEFAULT_WEIGHTS` are runtime-configurable through [`src/lib/db/comboScoring.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboScoring.ts). This allows operators to tune provider selection criteria—such as favoring lower latency over cost—without modifying the underlying TypeScript source or redeploying the application.

### Which file handles the final provider selection after scoring?

The final selection logic resides in [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts). After [`engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/engine.ts) calculates and sorts scores, this file applies the active routing strategy (priority, weighted-random, or fill-first) to determine which provider actually receives the request.