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

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, 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. 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:

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. 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, 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 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

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.

Zero-Configuration Auto Routing

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

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, limiting selection to models meeting specific performance criteria.

Managing Combos via the CLI

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.
• 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, 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, the buildAutoCandidates() function generates an in-memory combo from currently healthy connections without querying the combos table in 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. The active strategy for a specific combo is determined by the config.routerStrategy field, which is validated against src/shared/validation/schemas/combo.ts at request time.

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