OmniRoute 15-Factor Auto-Combo Scoring: Complete Technical Guide

OmniRoute's Auto-Combo engine uses a weighted 15-factor algorithm to rank LLM provider connections, combining signals like quota availability, circuit-breaker health, inverse cost, and task fitness into a composite score ranging from 0 to 1.

OmniRoute, an open-source intelligent routing layer maintained in the diegosouzapw/OmniRoute repository, automatically selects optimal model providers through a sophisticated scoring system defined in open-sse/services/autoCombo/scoring.ts. The DEFAULT_WEIGHTS configuration assigns specific weights to 15 distinct factors that collectively determine routing decisions at request time.

The 15-Factor Weight Configuration

The scoring algorithm evaluates each candidate connection using the following factors, where weights sum to exactly 1.0:

Core Capacity and Health Signals

• health (0.1605): Circuit-breaker state where CLOSED = 1.0, HALF_OPEN = 0.5, and OPEN = 0.0.
• quota (0.1429): Remaining rate-limit headroom normalized as a ratio from 0 to 1.
• costInv (0.1429): Inverse blended cost calculated from 60% input token price and 40% output token price.
• latencyInv (0.1143): Inverse of p95 latency measurements, where faster response times yield higher scores.

Task and Context Alignment

• taskFit (0.0762): Fitness rating for specific task types including coding, review, planning, analysis, debugging, and documentation.
• contextAffinity (0.0476): Match between the request's required context window and the model's available context capacity.
• specificityMatch (0.0476): Alignment between the request's specificity manifest hint and the model's designated tier.

Account and Tier Management

• tierPriority (0.0476): Account tier weighting where Ultra = 1.0, Pro = 0.67, Standard = 0.33, and Free = 0.0.
• tierAffinity (0.0476): Compatibility between the candidate's service tier and the manifest-recommended tier.
• sessionAvailability (0.0476): OAuth session availability status retrieved via getOAuthSessionAvailability().

Stability and Load Distribution

• stability (0.0476): Variance-based metric incorporating latency standard deviation and error rates.
• connectionDensity (0.0476): Anti-concentration load-balancing measure across connections sharing the same provider.

Feedback and Advanced Signals

• quality (0.03): Output quality feedback from the routing-event quality tracker; candidates without historical observations receive a neutral 0.5 score.
• cacheAffinity (0.00): Rendezvous-hash affinity for prompt-cache prefix hits (disabled by default).
• resetWindowAffinity (0.00): Preference for connections approaching favorable quota-reset windows (disabled by default).

How the Scoring Pipeline Executes

The Auto-Combo engine processes every request through a four-stage pipeline implemented across the open-sse/services/autoCombo/ directory:

1. Candidate pool creation: The virtualFactory.ts module builds virtual candidates from all active provider connections.
2. Factor computation: The scorePool() function in scoring.ts calculates all 15 factors for each candidate.
3. Weight application: The system applies either DEFAULT_WEIGHTS or a selected weight pack from modePacks.ts to generate composite scores.
4. Selection: The highest-scoring candidate is selected for the request.

This evaluation occurs entirely at request time without persisting combo selections to the database.

Practical Implementation Examples

Trigger the default 15-factor scoring by specifying model: "auto" in your request:

import fetch from "node-fetch";

await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Explain the 15-factor scoring table." }],
  }),
});

Override default weights using the X-OmniRoute-Mode header to select predefined weight packs:

await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
    "X-OmniRoute-Mode": "fast",
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Prioritize low latency." }],
  }),
});

Customizing Behavior with Mode Packs

The modePacks.ts file defines alternative weight profiles that bias the engine toward specific operational goals:

• ship-fast: Prioritizes latencyInv and health for rapid response times.
• cost-saver: Maximizes costInv weighting to minimize token expenses.
• quality-first: Emphasizes the quality factor and stability metrics.
• offline-friendly: Optimizes for connectionDensity and session availability.

These packs modify the default weight distribution while maintaining the full 15-factor evaluation framework.

Summary

• OmniRoute's 15-factor scoring combines health, quota, cost, latency, and contextual signals into a normalized composite score.
• The DEFAULT_WEIGHTS table in scoring.ts allocates the highest weights to health (0.1605), quota (0.1429), and cost (0.1429).
• Two factors (cacheAffinity and resetWindowAffinity) are disabled by default with 0.00 weights but remain available for custom configurations.
• Mode packs allow runtime weight adjustments via the X-OmniRoute-Mode header without modifying source code.
• The entire scoring pipeline executes at request time in scorePool() without database persistence.

Frequently Asked Questions

What is the difference between tierPriority and tierAffinity?

tierPriority assigns base scores based on the user's account tier (Ultra, Pro, Standard, Free), while tierAffinity measures how well a specific model's tier matches the tier recommended in the request manifest. The first rewards high-tier accounts, and the second optimizes for tier-specific model selection.

How does OmniRoute handle disabled factors like cacheAffinity?

Factors with 0.00 weights such as cacheAffinity and resetWindowAffinity are calculated but do not contribute to the composite score in default configurations. Developers can enable them by assigning positive weights in custom mode packs or by modifying the DEFAULT_WEIGHTS constant in scoring.ts.

How is the quality factor calculated for new connections?

The quality factor relies on historical observations from the routing-event tracker. Candidates without prior observation data receive a neutral default score of 0.5, preventing new connections from being penalized while the system gathers performance data.

Can I implement custom weight packs beyond the predefined modes?

Yes. The modePacks.ts exports weight configurations that override DEFAULT_WEIGHTS. You can define custom weight objects that redistribute the 1.0 total across the 15 factors, then reference them through application-specific routing logic or extended header values.

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