How the 14-Factor Auto-Combo Scoring System Evaluates and Selects Model Candidates in OmniRoute

OmniRoute's Auto-Combo router uses a weighted 14-factor scoring algorithm that prioritizes four core operational metrics—quota, health, cost, and latency—to rank provider-model candidates and select the optimal endpoint for each request.

The 14-factor Auto-Combo scoring system is the decision engine behind OmniRoute's intelligent request routing. Unlike simple round-robin or static routing, this system dynamically evaluates every available provider-model combination against real-time operational data, then selects the highest-scoring candidate. The implementation lives primarily in open-sse/services/autoCombo/scoring.ts, with orchestration logic in engine.ts and architectural documentation in docs/routing/AUTO-COMBO.md.

Understanding the 14 Scoring Factors

The ScoringFactors interface defines fourteen normalized inputs (0–1 range) that capture different dimensions of provider health and suitability:

Factor	Description
quota	Remaining quota percentage for the provider-account pair
health	Circuit-breaker health state (1.0 = healthy, 0.0 = tripped)
costInv	Inverse cost per 1M tokens (cheaper models score higher)
latencyInv	Inverse 95th-percentile latency (faster models score higher)
taskFit	Model capability match for the specific task type
stability	Historical uptime/reliability metric
tierPriority	Account tier elevation (ultra/pro/standard/free)
tierAffinity	Preferred tier alignment from routing hints
specificityMatch	How closely model specificity matches request requirements
contextAffinity	Reuse preference for established context/model pairings
cacheAffinity	Cache hit probability for similar previous requests
sessionAvailability	Session continuity support availability
resetWindowAffinity	Proximity to quota reset time
connectionDensity	Current connection load distribution

Each factor is normalized before scoring to ensure fair comparison across providers with different scales.

The I4-Factor: Core Decision Weights

The I4-factor refers to the four highest-weighted factors that dominate routing decisions. These core operational metrics receive substantially more weight than the ten supplementary factors:

// open-sse/services/autoCombo/scoring.ts
export const DEFAULT_WEIGHTS: ScoringWeights = {
  quota: 0.1429,        // ~14.3% — remaining quota
  health: 0.1905,       // ~19.0% — circuit health
  costInv: 0.1429,      // ~14.3% — inverse cost
  latencyInv: 0.1143,   // ~11.4% — inverse latency
  taskFit: 0.0762,
  stability: 0.0476,
  tierPriority: 0.0476,
  tierAffinity: 0.0476,
  specificityMatch: 0.0476,
  contextAffinity: 0.0476,
  cacheAffinity: 0,
  sessionAvailability: 0.0476,
  resetWindowAffinity: 0,
  connectionDensity: 0.0476,
};

The I4-factor weights sum to approximately 59% of the total score (0.1429 + 0.1905 + 0.1429 + 0.1143 = 0.5906). This design ensures that fundamental operational health—quota availability, system health, cost efficiency, and speed—always outweigh secondary preferences like caching or session affinity.

Score Calculation Algorithm

The calculateScore function in scoring.ts computes the final candidate score through a weighted linear combination, with defensive clamping to prevent malformed inputs from corrupting rankings:

// open-sse/services/autoCombo/scoring.ts
export function calculateScore(
  factors: ScoringFactors,
  weights: ScoringWeights
): number {
  return clamp01(
    weights.quota * factors.quota +
    weights.health * factors.health +
    weights.costInv * factors.costInv +
    weights.latencyInv * factors.latencyInv +
    weights.taskFit * factors.taskFit +
    weights.stability * factors.stability +
    weights.tierPriority * factors.tierPriority +
    weights.tierAffinity * factors.tierAffinity +
    weights.specificityMatch * factors.specificityMatch +
    weights.contextAffinity * factors.contextAffinity +
    weights.cacheAffinity * (factors.cacheAffinity ?? 0) +
    weights.sessionAvailability * (factors.sessionAvailability ?? 0) +
    weights.resetWindowAffinity * (factors.resetWindowAffinity ?? 0) +
    weights.connectionDensity * factors.connectionDensity
  );
}

The clamp01 utility guarantees output in the valid [0, 1] range even if factor inputs are corrupted or missing.

Tier-Aware Scoring Adjustments

Beyond the base 14 factors, OmniRoute integrates T10 tier logic through two additional scoring pathways:

• tierPriority — Derived from calculateTierScore, which converts account tiers (ultra, pro, standard, free) into normalized priority values
• tierAffinity — Matches routing hints against provider tier assignments to reward preferred provider relationships

These tier adjustments ensure that high-value accounts receive preferential routing without hard-coding provider priorities.

Candidate Selection Flow in the Engine

The engine.ts module orchestrates the full selection pipeline:

1. Gather candidates — Query all provider-model combinations eligible for the request
2. Compute factors — For each candidate, resolve real-time metrics (quota remaining, health status, latency measurements)
3. Calculate scores — Invoke calculateScore with computed factors and configured weights
4. Rank and select — Sort descending by score; return top candidate (or top N for multi-target routing)

// Example: Computing a candidate score
import { calculateScore, DEFAULT_WEIGHTS } from "@omniroute/open-sse/services/autoCombo/scoring";

const candidateFactors = {
  quota: 0.85,              // 85% quota remaining
  health: 1.0,              // Fully healthy
  costInv: 0.92,            // Very cost-effective
  latencyInv: 0.78,         // Below-average latency
  taskFit: 0.81,
  stability: 0.95,
  tierPriority: 0.6,
  tierAffinity: 0.4,
  specificityMatch: 0.35,
  contextAffinity: 0.2,
  cacheAffinity: 0,
  sessionAvailability: 0.7,
  resetWindowAffinity: 0,
  connectionDensity: 0.3,
};

const finalScore = calculateScore(candidateFactors, DEFAULT_WEIGHTS);
// I4-factor contribution: 0.85×0.1429 + 1.0×0.1905 + 0.92×0.1429 + 0.78×0.1143 ≈ 0.52
// Total score combines I4 + remaining 10 factors

Performance and Operational Characteristics

• Scoring latency: Factor computation and score calculation complete in sub-millisecond time per candidate
• Weight customization: Deployments can override DEFAULT_WEIGHTS without code changes to emphasize cost over latency or vice versa
• Graceful degradation: If real-time metrics are unavailable, factors default to conservative values rather than failing open

Summary

• The 14-factor Auto-Combo scoring system in OmniRoute evaluates every provider-model candidate across operational, financial, and strategic dimensions
• The I4-factor (quota, health, costInv, latencyInv) receives ~59% of total weight, ensuring routing decisions prioritize fundamental system health
• calculateScore in open-sse/services/autoCombo/scoring.ts implements the weighted combination with defensive clamp01 normalization
• Tier-aware adjustments via tierPriority and tierAffinity layer account-level preferences atop base operational scores
• The engine in open-sse/services/autoCombo/engine.ts orchestrates candidate gathering, factor resolution, scoring, and final selection

Frequently Asked Questions

What makes the I4-factor different from the other ten factors?

The I4-factor designates the four highest-weighted scoring inputs that collectively dominate routing decisions: quota availability, health status, inverse cost, and inverse latency. These factors receive weights of 0.1429, 0.1905, 0.1429, and 0.1143 respectively, summing to nearly 60% of the total score. The remaining ten factors each carry 0.0762 or less, serving as tie-breakers or preference signals rather than primary decision drivers.

Can I customize the scoring weights for my deployment?

Yes. While DEFAULT_WEIGHTS provides the standard I4-factor distribution, the ScoringWeights interface allows complete weight customization. Pass alternate weights to calculateScore or configure via your deployment's routing manifest. Common customizations include increasing latencyInv weight for real-time applications or boosting costInv for batch processing workloads.

How does the engine handle missing or stale metrics for scoring factors?

The scoring system implements defensive programming through the clamp01 utility and optional chaining on nullable factors like cacheAffinity and sessionAvailability. When real-time data is unavailable, factors default to conservative safe values (typically 0 or 0.5) rather than causing calculation failures. This ensures routing continuity during metrics pipeline outages.

Where is the architectural documentation for the Auto-Combo routing strategy?

The comprehensive design specification resides at docs/routing/AUTO-COMBO.md in the OmniRoute repository. This document details the 14-factor scoring matrix, explains the I4-factor prioritization rationale, and describes how tier-aware routing integrates with base scoring to achieve intelligent load distribution across heterogeneous provider fleets.

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