What Is Auto-Combo in OmniRoute and How Does Its Scoring System Work?

Auto-Combo is OmniRoute's zero-config routing engine that automatically selects the optimal provider-model for each request using a 14-factor weighted scoring function.

OmniRoute's Auto-Combo eliminates manual provider selection by building transient provider combinations on-the-fly. When you send model: "auto" or model: "auto/<variant>", the system evaluates every available provider-model through a multi-factor scoring pipeline—no persisted combo objects or extra API calls required. This article breaks down the scoring architecture, customization options, and implementation details from the OmniRoute source code.

How Auto-Combo Works: The Virtual Factory Pattern

The virtual factory pattern is the core mechanism behind Auto-Combo. Located in open-sse/services/autoCombo/virtualFactory.ts, this component constructs a temporary combo for each incoming request rather than maintaining static provider configurations.

When a request arrives with model: "auto", the factory immediately:

1. Generates a candidate pool from available providers
2. Applies filtering constraints (resilience, quota, tier)
3. Executes the scoring pipeline
4. Returns the highest-ranked provider-model

This transient approach means zero persisted state and no additional API overhead—the combo exists only for the duration of the request.

The 14-Factor Scoring System Explained

The scoring engine lives in open-sse/services/autoCombo/scoring.ts and evaluates candidates across 14 weighted factors. These factors capture cost, performance, reliability, and operational health:

Factor Category	Specific Factors
Resource Health	Quota health, provider health, circuit-breaker status
Cost & Performance	Cost per token, latency (TTFT, total), throughput
Stability	Latency variance, error rate, uptime history
Task Fit	Model capability alignment with request type
Tier & Operational	Provider tier, quota utilization, geographic proximity

The default weight sum is 1.05, allowing slight overweighting of critical reliability factors. Custom distributions are automatically normalized before scoring to maintain comparable score ranges.

Score Calculation Process

The scorePool() function—implemented as a 9-factor variant in the ranking stage—executes four sequential steps:

• Candidate Pool Filtering: Removes providers failing resilience checks, quota limits, or tier requirements
• Factor Evaluation: Computes normalized scores for each of the 14 factors
• Weighted Summation: Multiplies factor scores by their configured weights
• Rank & Select: Returns the provider-model with highest composite score

Here's a practical example requesting Auto-Combo with performance preferences:

// Request with "fast" preset for low-latency routing
fetch("https://omniroute.local/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-OmniRoute-Mode": "fast",      // Overrides default weights
    "X-OmniRoute-Budget": "0.02"     // Hard USD cost ceiling per request
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Explain quantum tunnelling." }]
  })
});

Customizing Auto-Combo with Mode Packs

The X-OmniRoute-Mode header in open-sse/services/autoCombo/requestControls.ts enables runtime weight customization through preset mode packs or custom pack names:

Mode Pack	Weight Emphasis	Ideal Use Case
fast / ship-fast	Latency, health	Real-time applications, streaming
cheap / cost-saver	Cost minimization	Batch processing, high-volume workloads
reliable	Circuit-breaker health, latency stability	Production-critical systems
offline	Uptime, low quota usage	Resilient fallback scenarios
balanced (default)	Even distribution across all factors	General-purpose routing

Custom packs defined in the OmniRoute UI can also be referenced directly:

// Using a UI-defined custom weight pack
fetch("/v1/chat/completions", {
  method: "POST",
  headers: {
    "X-OmniRoute-Mode": "quality-first"  // Custom accuracy-focused weights
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Write a haiku." }]
  })
});

The X-OmniRoute-Budget header provides an additional hard cost ceiling in USD—requests exceeding this threshold are rejected regardless of scoring outcomes.

Key Source Files and Their Roles

File Path	Purpose
open-sse/services/autoCombo/scoring.ts	Defines DEFAULT_WEIGHTS and scorePool() ranking logic
open-sse/services/autoCombo/virtualFactory.ts	Implements transient combo construction for model: "auto"
open-sse/services/autoCombo/requestControls.ts	Parses X-OmniRoute-Mode and X-OmniRoute-Budget headers
docs/routing/AUTO-COMBO.md	Complete user guide with full factor documentation
docs/diagrams/exported/auto-combo-12factor.svg	Visual reference for 13 of 14 scoring factors

Summary

• Auto-Combo automatically selects provider-models via transient combos—no manual configuration or persisted state required
• 14 weighted factors in scoring.ts evaluate cost, latency, reliability, and operational health
• X-OmniRoute-Mode header enables runtime weight customization through presets (fast, cheap, reliable, offline) or custom packs
• X-OmniRoute-Budget enforces hard USD cost ceilings per request
• scorePool() ranks candidates and returns the optimal provider-model for each request

Frequently Asked Questions

How many factors does OmniRoute Auto-Combo evaluate?

OmniRoute Auto-Combo evaluates 14 factors by default, including quota health, provider health, cost, latency metrics, task-fit, stability measures, and tier-related indicators. The scorePool() ranking function uses a 9-factor subset for final candidate ordering. All factors and their default weights are defined in open-sse/services/autoCombo/scoring.ts.

Can I use Auto-Combo without any configuration?

Yes. Auto-Combo is designed as a zero-config routing layer. Simply set model: "auto" in your request body. The system uses the balanced weight preset by default and automatically filters providers by health, quota, and resilience status. No combo objects need to be created or maintained.

What happens if no provider passes the scoring filters?

If all candidates fail the filtering stage—due to circuit-breaker states, quota exhaustion, or budget constraints—the request is rejected with an appropriate error response. The open-sse/services/autoCombo/virtualFactory.ts handles this graceful degradation path.

How do custom mode packs interact with the default weights?

Custom mode packs specified via X-OmniRoute-Mode completely override the DEFAULT_WEIGHTS table defined in scoring.ts. The override occurs in requestControls.ts, and any custom weight distribution is normalized before scoring to ensure comparable score ranges across different configurations.

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