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

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, 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 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
• 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 constructs ProviderCandidate objects containing quota, cost, and latency data from the provider registry.
2. Scoring Execution: 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 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, operators can dynamically adjust the I² factors without deploying new code. The system also exposes scoring telemetry via 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:

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.
• 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 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 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. 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. After 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.

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