# What Is a Combo in OmniRoute? Structure, Routing, and Usage

> Discover OmniRoute combos: a powerful routing abstraction dispatching single API requests to multiple targets using configurable strategies like priority, weighted, or fusion for efficient response selection and aggregation.

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

---

**A combo in OmniRoute is a routing abstraction that dispatches a single API request to a panel of model targets instead of one provider, using configurable strategies like priority, weighted, or fusion to select or aggregate responses.**

A combo in OmniRoute serves as the core mechanism for intelligent request distribution across multiple AI models. Unlike standard single-model routing, combos let you define sophisticated fallback chains, parallel execution pools, and budget-aware selections through a declarative configuration stored in the database.

## Combo Structure and Database Schema

In [`src/shared/validation/schemas/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/combo.ts), a combo is defined as a Zod-validated object containing a unique `name`, an ordered array of `steps`, and a `config` blob that controls routing behavior. Each step uses discriminated schemas such as `comboModelStepInputSchema` for direct model references or `comboRefStepInputSchema` for recursive combo nesting.

The persisted record lives in the `combos` table, accessed through [`src/domain/persistence/comboRepositories.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/persistence/comboRepositories.ts). When resolved, the `steps` array deserializes into concrete execution instructions, while the `config` JSON determines the **routing strategy**, budget caps, and SLA parameters.

## The Combo Resolution Pipeline

The combo engine processes every request through a three-phase pipeline implemented in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts):

1. **`getComboForModel()`** – Resolves the incoming model string to either a persisted combo definition or a bare single-model target.

2. **`resolveComboTargets()`** – Expands combo steps into an array of `ResolvedComboTarget` objects. This phase applies provider-level filters including rate limits, circuit-breaker state, and per-model quotas.

3. **`handleComboChat()`** – Executes the request against the selected target(s), streaming responses back to the client. For strategies like `fusion`, this iterates multiple targets concurrently.

## Routing Strategies and Auto-Combo Scoring

OmniRoute supports **19 built-in routing strategies** enumerated in [`src/shared/constants/routingStrategies.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts). Valid values for `config.routerStrategy` include `priority`, `weighted`, `fusion`, and `auto`.

### The 15-Factor Auto-Combo Algorithm

When the strategy is set to `auto`, the engine invokes `scoreAutoTargets()` using a 15-factor scoring matrix (`DEFAULT_WEIGHTS`). As documented in [`docs/routing/AUTO-COMBO.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/AUTO-COMBO.md), this algorithm ranks candidates by latency, cost, success rate, token capacity, and provider health before making a selection.

### Virtual Zero-Config Combos

You can invoke combos without database entries by using the `model: "auto"` prefix. The `buildAutoCandidates()` function in [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts) constructs an in-memory combo on-the-fly from currently healthy connections, requiring no persistence layer interaction.

## Practical Code Examples

### Invoke a Persisted Combo with Fusion Strategy

```bash
curl -X POST http://localhost:20128/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "fusion-panel",
        "messages": [{ "role": "user", "content": "Explain quantum tunneling." }]
      }'

```

This targets a combo named "fusion-panel" defined in the database, which fans out to multiple models and merges the responses according to the `fusion` strategy logic in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts).

### Zero-Configuration Auto Routing

```bash
curl -X POST http://localhost:20128/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "auto",
        "messages": [{ "role": "user", "content": "Write a haiku about rain." }]
      }'

```

The `auto` value triggers the virtual combo factory, routing through the highest-scored candidate without any persisted configuration.

### Tiered Auto Variants

```bash
curl -X POST http://localhost:20128/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "auto/fast:2",
        "messages": [{ "role": "user", "content": "Summarize the plot of *Dune*." }]
      }'

```

The suffix `/fast:2` filters the candidate pool using category and tier constraints defined in [`open-sse/services/autoCombo/builtinCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/builtinCatalog.ts), limiting selection to models meeting specific performance criteria.

### Managing Combos via the CLI

```bash
node bin/cli/commands/combo.mjs create \
  --name my-priority-combo \
  --strategy priority \
  --steps '[{"kind":"model","modelId":"gpt-4"}]' \
  --config '{"budgetCap":5000}'

```

This command writes directly to the SQLite `combos` table via the repository layer, wrapping the same validation schemas used by the HTTP API.

## Summary

- A **combo in OmniRoute** is a declarative routing construct that maps one request to multiple model targets using configurable strategies.
- The structure consists of **steps** (validated by `comboModelStepInputSchema` or `comboRefStepInputSchema`) and a **config** blob controlling strategy, budget, and SLA.
- The resolution pipeline runs through `getComboForModel()`, `resolveComboTargets()`, and `handleComboChat()` in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts).
- **Auto-Combo** provides dynamic scoring via a 15-factor matrix, available both as a persisted strategy and as virtual zero-config combos (`model: "auto"`).
- All combos inherit **resilience features** including circuit breakers, sticky pins, and connection cooldowns managed during the `handleComboChat()` execution phase.

## Frequently Asked Questions

### How does a combo differ from a single model request in OmniRoute?

While a single model request routes directly to one provider, a combo evaluates a panel of targets before execution. According to [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), the combo engine inserts a resolution phase that scores, filters, and selects targets based on real-time health and configuration, whereas single-model requests skip this panel evaluation entirely.

### Can I use combos without creating database entries?

Yes. The virtual auto-combo feature allows zero-configuration routing using the `model: "auto"` prefix. As implemented in [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts), the `buildAutoCandidates()` function generates an in-memory combo from currently healthy connections without querying the `combos` table in [`src/domain/persistence/comboRepositories.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/persistence/comboRepositories.ts).

### What happens if all targets in a combo fail?

The combo engine integrates with OmniRoute's resilience layers. In `handleComboChat()`, failures trigger circuit breaker increments, connection cooldowns, and optional sticky-pin releases via `releaseStickyPinOnFailure`. If all candidates exhaust their retry budgets, the request returns an aggregated error or fallback response depending on the configured strategy.

### Where are combo routing strategies defined?

The 19 supported strategies—including `priority`, `weighted`, `fusion`, and `auto`—are enumerated as constants in [`src/shared/constants/routingStrategies.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts). The active strategy for a specific combo is determined by the `config.routerStrategy` field, which is validated against [`src/shared/validation/schemas/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/combo.ts) at request time.