# How the Auto-Combo Engine in OmniRoute Selects Routing Targets

> Discover how the OmniRoute Auto-Combo Engine selects routing targets via a three-stage pipeline: filtering candidates, scoring based on real-time data, and finalizing the best provider/model.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboCooldownRetry.ts) and [`comboData.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoCombo/engine.ts). Here the **Intelligent Routing** module ([`src/lib/combos/intelligentRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/resolveAutoStrategy.ts) | Orchestrates candidate gathering, filtering, and provider selection |
| [`open-sse/services/combo/autoCombo/engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoCombo/engine.ts) | Implements scoring algorithm and final target selection |
| [`src/lib/combos/intelligentRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/combos/intelligentRouting.ts) | Generates per-provider score objects |
| [`open-sse/services/combo/comboData.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/comboData.ts) | Deduplication and candidate normalization |
| [`open-sse/services/combo/comboCooldownRetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/comboCooldownRetry.ts) | Cooldown and circuit-breaker filtering |
| [`open-sse/services/combo/autoConfig.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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](https://github.com/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoConfig.ts). The **intent configuration** allows weight adjustments that prioritize cost-per-token metrics over latency scores. The scoring normalizer in [`intelligentRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/chatCore.ts). However, the combo system supports automatic retry with different targets through [`comboCooldownRetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboCooldownRetry.ts). Failed executions trigger cooldown marking and re-invocation of `selectAutoProvider()` with updated health data, effectively creating dynamic fallback behavior.