How the OmniRoute Auto-Combo Engine Scores Candidates for Model Selection

The OmniRoute Auto-Combo engine evaluates every active provider connection using a deterministic 15-factor weighted formula to select the highest-scoring candidate for each request.

The Auto-Combo feature in the OmniRoute repository dynamically routes LLM requests to the optimal provider and model by computing a composite score across multiple performance dimensions. When a request arrives with an auto model prefix, the engine builds a virtual pool of candidates and applies a normalized scoring function defined in open-sse/services/autoCombo/scoring.ts to determine the best match.

The 15-Factor Scoring Algorithm

The scoring pipeline operates per-request without persisting state, ensuring that new providers or refreshed credentials are immediately available for routing. The process begins in open-sse/services/autoCombo/virtualFactory.ts, which constructs an in-memory pool of VirtualAutoComboCandidate objects from all active connections. Each candidate is then evaluated by the scorePool() function using the following weighted factors:

Factor	Default Weight	Description
quota	0.1429	Remaining quota or rate-limit headroom, normalized to a 0–1 scale.
health	0.1605	Circuit-breaker health status (CLOSED = 1.0, HALF_OPEN = 0.5, OPEN = 0.0).
costInv	0.1429	Inverse blended cost (60% input + 40% output token pricing).
latencyInv	0.1143	Inverse of p95 latency, normalized across the candidate pool.
taskFit	0.0762	Task-type fitness matching (coding, review, planning, analysis, debugging, docs).
stability	0.0476	Low latency standard deviation and error rate signal.
tierPriority	0.0476	Account tier priority (Ultra = 1.0, Pro = 0.67, Standard = 0.33, Free = 0.0).
tierAffinity	0.0476	Alignment between the candidate’s tier and the manifest-recommended tier.
specificityMatch	0.0476	Match between request specificity hints and model capabilities.
contextAffinity	0.0476	Affinity between the request’s context-window requirements and the model’s capacity.
sessionAvailability	0.0476	OAuth session availability score (non-OAuth connections default to 1.0).
connectionDensity	0.0476	Anti-concentration factor to distribute load across multiple connections.
cacheAffinity	0.00	Rendezvous-hash affinity for cached prompt prefixes (disabled by default).
resetWindowAffinity	0.00	Bias toward connections with favorable quota reset windows (disabled by default).
quality	0.03	Feedback-driven quality signal from the routing-event tracker (neutral 0.5 if no data exists).

The default weights sum to 1.0, and custom weight profiles are normalized before application. The candidate with the highest total weighted score wins the request.

Mode Packs and Weight Profiles

OmniRoute provides four built-in mode packs that reconfigure the scoring weights to optimize for specific operational goals. These are defined in open-sse/services/autoCombo/modePacks.ts:

Mode Pack	Key Weight Adjustments	Use Case
ship-fast	latencyInv = 0.32, health = 0.28	Prioritize low-latency, healthy connections for rapid responses.
cost-saver	costInv = 0.37	Heavily favor the cheapest available providers.
quality-first	taskFit = 0.37, stability = 0.15	Select the best model for the specific task with high consistency.
offline-friendly	quota = 0.37, health = 0.28	Maximize quota headroom for resilient offline routing.

You can activate a mode pack using the X-OmniRoute-Mode request header with aliases like fast, cheap, quality, or the raw pack names.

Per-Request Controls

The engine accepts several HTTP headers to override scoring behavior dynamically. These are parsed in open-sse/services/autoCombo/requestControls.ts:

Header	Effect
X-OmniRoute-Mode	Selects a preset alias (fast, balanced, quality, cheap, reliable, offline) or a raw mode pack name to override weights for the current request.
X-OmniRoute-Budget	Specifies a USD budget cap; candidates exceeding this cost are filtered before scoring.
X-OmniRoute-Budget-Fallback	Controls budget enforcement: cheapest (allows cheapest candidate even if over budget) or strict (returns HTTP 402 if no candidate fits).

Implementation Architecture

The scoring system spans several key files in the OmniRoute codebase:

• open-sse/services/autoCombo/scoring.ts – Implements the scorePool() function and the DEFAULT_WEIGHTS constant containing the 15-factor formula.
• open-sse/services/autoCombo/virtualFactory.ts – Builds the candidate pool by aggregating active provider connections and their metadata.
• open-sse/services/autoCombo/modePacks.ts – Exports the weight profile definitions for the four built-in mode packs.
• open-sse/services/autoCombo/requestControls.ts – Handles header parsing and applies per-request overrides before scoring begins.
• open-sse/services/autoCombo/engine.ts – Orchestrates the full selection process, including bandit exploration and self-healing logic.
• src/sse/handlers/chat.ts – Detects the auto/ model prefix and routes the request to the virtual auto-combo engine.

Usage Examples

Zero-Config Request with Mode Selection

The following curl command demonstrates routing with the fast mode pack and a strict budget constraint:

curl -sS http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Mode: fast" \
  -H "X-OmniRoute-Budget: 0.05" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Explain the scoring algorithm"}]}'

In this flow, src/sse/handlers/chat.ts detects the auto prefix, virtualFactory.ts assembles the candidate pool, and scoring.ts computes the final scores using the ship-fast weight profile.

Persisted Auto-Combo with Custom Weights

For consistent custom scoring across requests, define a persisted combo with explicit weights:

{
  "name": "My-Auto-Combo",
  "strategy": "auto",
  "config": {
    "routerStrategy": "rules",
    "auto": {
      "weights": {
        "quota": 0.20,
        "health": 0.20,
        "costInv": 0.10,
        "latencyInv": 0.30,
        "taskFit": 0.15,
        "stability": 0.05
      }
    }
  }
}

POST this configuration to /api/combos. Subsequent requests using model: "My-Auto-Combo" will invoke the same scoring engine with your custom weight distribution, processed by open-sse/services/autoCombo/engine.ts.

Summary

• The OmniRoute Auto-Combo engine uses a deterministic 15-factor weighted formula to score candidates per-request.
• Key factors include health (0.1605), quota (0.1429), costInv (0.1429), and latencyInv (0.1143), with mode packs available to re-prioritize these weights.
• The scoring implementation resides in open-sse/services/autoCombo/scoring.ts, while candidate pool generation occurs in virtualFactory.ts.
• Users control routing behavior via the X-OmniRoute-Mode and X-OmniRoute-Budget headers, or by defining persisted combos with custom weight objects.

Frequently Asked Questions

How does OmniRoute handle circuit-breaker states during scoring?

The health factor (weight 0.1605) in open-sse/services/autoCombo/scoring.ts maps circuit-breaker states directly to numeric values: CLOSED connections score 1.0, HALF_OPEN score 0.5, and OPEN score 0.0. This ensures unhealthy providers are heavily penalized or eliminated from selection unless no alternatives exist.

Can I disable specific scoring factors?

Yes. While you cannot remove factors entirely, you can set their weights to 0.00 in a custom weight profile. Both cacheAffinity and resetWindowAffinity default to 0.00 in the standard configuration, effectively disabling them unless explicitly enabled.

What happens if multiple candidates receive the same score?

When scores tie, the engine applies secondary selection logic within open-sse/services/autoCombo/engine.ts, including bandit exploration for quality discovery and connection density balancing to prevent over-concentration on a single provider account.

Is the scoring deterministic for identical requests?

The core 15-factor formula is deterministic given identical candidate pools and weights. However, per-request factors like sessionAvailability, quota headroom, and circuit-breaker health states change dynamically, meaning the same request may route differently as provider conditions evolve.

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