How the Auto-Combo Engine in OmniRoute Selects Routing Targets

The OmniRoute Auto-Combo Engine selects routing targets through a three-stage pipeline: building a filtered candidate pool, scoring candidates using real-time health, quota, cost, and latency data, and finalizing the highest-scoring provider/model pair.

The Auto-Combo Engine is OmniRoute's dynamic, data-driven router that makes runtime decisions about which provider and model should handle each request. Unlike static routing configurations, this engine continuously evaluates live system conditions to optimize for reliability, cost, and performance. This article explains exactly how the selection process works, from candidate gathering to final execution, based on the OmniRoute source code at release v3.8.51.

---

Stage 1: Building the Candidate Pool

The routing process begins in open-sse/services/combo/resolveAutoStrategy.ts. When a request specifies model: 'auto' with a combo name, the engine calls expandAutoComboCandidatePool() (lines 237–241) to gather every enabled target matching the combo's provider and model filters.

Filtering Out Unhealthy Targets

Before candidates proceed to scoring, the engine applies aggressive filtering via comboCooldownRetry.ts and comboData.ts:

Filter	Purpose
Connection cooldown	Excludes targets temporarily locked after failed connections
Provider circuit-breaker	Skips providers with open breakers indicating systemic failure
Model-level lockout	Removes specific models flagged as unavailable

Deduplication by Execution Key

The engine calls dedupeTargetsByExecutionKey() to eliminate redundant candidates. This prevents scenarios where multiple credentials point to the same upstream account, ensuring each physical endpoint is evaluated only once.

---

Stage 2: Scoring the Candidates

Once filtered, candidates move to selectAutoProvider() in autoCombo/engine.ts. Here the Intelligent Routing module (src/lib/combos/intelligentRouting.ts) constructs a composite score for each target.

The Four Scoring Dimensions

The buildIntelligentProviderScores function assembles a score object blending these weighted factors:

• Provider health — Circuit breaker state and recent error rates
• Quota and cost information — Per-provider quota consumption and cost-per-token metrics
• Latency and headroom — Historical response times plus current load capacity
• Intent configuration — The combo's system prompt and auto-config overrides, which adjust weighting to favor models suited for specific tasks

Tool-Calling Enforcement

Around line 189 of resolveAutoStrategy.ts, the engine performs an additional guard: if the combo requires tool-calling support, any target lacking sufficient tool capacity is rejected regardless of its score.

Scores are normalized, and the highest-scoring target wins selection.

---

Stage 3: Finalizing the Selection

The chosen target returns to the request-handling stack in chatCore.ts. Before execution proceeds:

1. The target's execution key is recorded via recordComboIntent() for combo metrics tracking
2. The request enters the standard executor pipeline (OAuth, API-key, or direct HTTP dispatch)

---

Code Example: Triggering Auto-Combo Routing

// Client request that activates the Auto-Combo Engine
import { fetchChat } from '@/lib/api';

await fetchChat({
  model: 'auto',                    // Triggers Auto-Combo strategy
  comboName: 'my-budget-aware-combo',
  messages: [{ 
    role: 'user', 
    content: 'Explain quantum tunnelling.' 
  }],
});

---

Implementation Reference: Key Files

File	Responsibility
open-sse/services/combo/resolveAutoStrategy.ts	Orchestrates candidate gathering, filtering, and provider selection
open-sse/services/combo/autoCombo/engine.ts	Implements scoring algorithm and final target selection
src/lib/combos/intelligentRouting.ts	Generates per-provider score objects
open-sse/services/combo/comboData.ts	Deduplication and candidate normalization
open-sse/services/combo/comboCooldownRetry.ts	Cooldown and circuit-breaker filtering
open-sse/services/combo/autoConfig.ts	Parses combo-level intent and system-prompt overrides

All paths reference the release/v3.8.51 tag of diegosouzapw/OmniRoute.

---

Summary

• Candidate pool expansion happens via expandAutoComboCandidatePool() with aggressive health filtering
• Real-time scoring blends health, quota, cost, latency, and intent-specific weighting through intelligentRouting.ts
• Tool-calling requirements are enforced as hard constraints during selection
• Execution keys deduplicate redundant credentials and enable metrics tracking
• The entire pipeline executes at request time, making Auto-Combo a truly dynamic routing strategy

---

Frequently Asked Questions

Can I force the Auto-Combo Engine to prefer cheaper models over faster ones?

Yes. Configure your combo's auto-config overrides in autoConfig.ts. The intent configuration allows weight adjustments that prioritize cost-per-token metrics over latency scores. The scoring normalizer in intelligentRouting.ts applies these weights when building provider scores.

What happens if all candidates fail the health filters?

If every candidate is excluded by cooldowns, circuit breakers, or model lockouts, selectAutoProvider() receives an empty candidate list. The engine returns a routing failure to chatCore.ts, which typically surfaces as a 503 error with details about which filters blocked selection.

How does the engine handle provider rate limiting?

Rate limit state feeds into the quota information dimension of the score object. Providers approaching quota exhaustion receive reduced scores. If a provider exceeds hard quota limits, comboData.ts filters it from the candidate pool before scoring begins.

Does Auto-Combo support fallback chains if the top-scored target fails?

The selection returns a single target to chatCore.ts. However, the combo system supports automatic retry with different targets through comboCooldownRetry.ts. Failed executions trigger cooldown marking and re-invocation of selectAutoProvider() with updated health data, effectively creating dynamic fallback behavior.

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