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

> Discover how OmniRoute's 14-factor Auto-Combo scoring system evaluates model candidates using weighted metrics for quota, health, cost, and latency to select optimal endpoints.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/scoring.ts), with orchestration logic in [`engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/engine.ts) and architectural documentation in [`docs/routing/AUTO-COMBO.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/scoring.ts) computes the final candidate score through a weighted linear combination, with defensive clamping to prevent malformed inputs from corrupting rankings:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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)

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.