The 17 Routing Strategies in OmniRoute: Complete Guide to I-7 Auto-Combo Selection

OmniRoute's I-7 auto-combo routing engine provides 17 distinct routing strategies—from priority-based failover to cost-optimized and context-aware selection—that determine how requests are distributed across AI providers and models based on health, cost, and capacity constraints.

The I-7 auto-combo routing engine intelligently selects target providers using predefined algorithms declared in src/shared/constants/routingStrategies.ts. These 17 routing strategies control load balancing, cost optimization, and failover behavior for every request processed through the OmniRoute system.

Where the 17 Strategies Are Defined

All user-facing routing strategies are declared in the constant file [src/shared/constants/routingStrategies.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts). This file exports three arrays that govern strategy availability:

• ROUTING_STRATEGY_VALUES – Contains the 17 public strategies available to the UI, API, and combo definitions.
• INTERNAL_ROUTING_STRATEGY_VALUES – Contains "quota-share", which is reserved for internal combo-dispatcher logic and not exposed to end-users.
• AUTO_ROUTING_STRATEGY_VALUES – Contains the same 17 strategies as ROUTING_STRATEGY_VALUES, representing the subset the auto-combo logic may automatically select when no explicit strategy is specified.

The file defines these arrays using TypeScript's as const assertion and exports corresponding types (e.g., RoutingStrategyValue). The utility function normalizeRoutingStrategy() validates supplied strings against these constants and falls back to "priority" if the value is unknown.

The Complete List of Routing Strategies

The following 17 strategies determine how OmniRoute distributes requests across provider targets:

priority – Uses the first target that reports healthy status; falls back to the next target only on failure.

weighted – Assigns a numeric weight to each target; selects providers proportionally to their weight values.

fill-first – Sends all requests to the first target until its quota is exhausted, then moves to the next target in sequence.

round-robin – Cycles through healthy targets in order, spreading request load evenly across all available providers.

p2c (Power-of-Two-Choices) – Randomly picks two targets, then chooses the one with the lower current load.

random – Selects among all healthy targets using pure random distribution.

least-used – Picks the target with the smallest recent usage counter, favoring underutilized providers.

reset-aware – Avoids targets that have recently been reset (e.g., after a crash), preferring stable providers.

reset-window – Similar to reset-aware, but respects a configurable time-window before considering a reset target eligible again.

cost-optimized – Chooses the cheapest target that satisfies the request's token budget constraints.

strict-random – Performs random selection that never falls back once a target is chosen, even if the request fails.

auto – Allows the combo dispatcher to automatically select the most appropriate strategy based on the combo's composition.

lkgp (Last-Known-Good-Provider) – Defaults to the most recent provider that successfully processed a request.

context-optimized – Prefers providers with the highest available context window for large prompt payloads.

context-relay – Routes requests to a provider capable of continuing a conversation using previous context tokens.

headroom – Selects a provider with sufficient remaining token headroom to accommodate the full request.

fusion – Combines multiple providers in parallel and merges their responses (experimental feature).

How to Configure Routing Strategies

Via the Settings REST API

Configure a strategy when creating or updating a combo through the REST endpoint src/app/api/settings/combo/route.ts:

POST /api/v1/settings/combo
{
  "name": "my-combo",
  "targets": [
    { "providerId": "openai", "modelId": "gpt-4o-mini" }
  ],
  "strategy": "cost-optimized"
}

The strategy field must be one of the 17 values listed in ROUTING_STRATEGY_VALUES. The request body is validated by the Zod schema defined in src/shared/validation/schemas/combo.ts.

In a Combo JSON Configuration File

Define strategies in local JSON files for CLI usage:

{
  "name": "fast-fallback",
  "targets": [
    { "providerId": "anthropic", "modelId": "claude-3-sonnet-20240229" },
    { "providerId": "openai", "modelId": "gpt-4o-mini" }
  ],
  "strategy": "reset-aware"
}

Save this configuration under ~/.omniroute/combo/fast-fallback.json and load it using omniroute combo import.

Through the MCP Tool

Change strategies at runtime using the Model Context Protocol (MCP) tool defined in open-sse/mcp-server/tools/advancedTools.ts:

omniroute mcp --tool set_routing_strategy --args '{"combo":"fast-fallback","strategy":"headroom"}'

The tool validates the supplied strategy against ROUTING_STRATEGY_VALUES and updates the combo's strategy column in the database via src/lib/db/combo.ts.

Implementation and Validation

The core dispatch logic resides in open-sse/services/combo/comboSetup.ts, which interprets a combo's strategy field and selects the appropriate target provider. Supporting modules like rateLimitManager.ts and usage.ts track the metrics (cost, usage counters, reset windows) required by the various strategies.

When processing requests, the system resolves combo targets through resolveComboTargets() in src/lib/db/combo.ts. If the SDK is used, the OmniRouteClient validates the strategy at compile-time against the same Zod schemas used server-side:

import { OmniRouteClient } from '@omniroute/sdk'

const client = new OmniRouteClient({ apiKey: process.env.OMNIRoute_API_KEY })

await client.createCombo({
  name: 'price-aware',
  targets: [
    { providerId: 'openai', modelId: 'gpt-4o-mini' },
    { providerId: 'anthropic', modelId: 'claude-3-opus-20240229' }
  ],
  strategy: 'cost-optimized'
})

For chat completions, include the x-omniroute-combo header to trigger routing:

await fetch('https://my-omniroute-instance.com/api/v1/chat/completions', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json', 
    'x-omniroute-combo': 'price-aware' 
  },
  body: JSON.stringify({
    model: 'combo',
    messages: [{ role: 'user', content: 'Explain I-7 routing' }]
  })
})

Summary

• 17 public strategies are defined in src/shared/constants/routingStrategies.ts via ROUTING_STRATEGY_VALUES.
• Strategy selection controls failover, load balancing, cost optimization, and context handling across AI providers.
• Configuration is supported through REST API, JSON files, and MCP tools, with validation in src/shared/validation/schemas/combo.ts.
• Implementation executes in open-sse/services/combo/comboSetup.ts, utilizing usage metrics and health checks to apply the selected algorithm.
• Normalization automatically falls back to "priority" if an invalid strategy string is supplied.

Frequently Asked Questions

What happens if I specify an invalid routing strategy?

If you provide a strategy value not included in ROUTING_STRATEGY_VALUES, the normalizeRoutingStrategy() function in src/shared/constants/routingStrategies.ts automatically falls back to "priority". The Zod validation schema in src/shared/validation/schemas/combo.ts will also reject invalid values at the API boundary, returning a validation error before the request is processed.

Can I switch routing strategies without restarting OmniRoute?

Yes. You can change the strategy at runtime using the MCP set_routing_strategy tool or by updating the combo via the REST API at /api/v1/settings/combo. The change takes effect immediately for subsequent requests, as the combo dispatcher reads the updated strategy field from the database on each request resolution.

What is the difference between "random" and "strict-random"?

random selects a target randomly from healthy providers but may fall back to alternatives if the chosen target fails. strict-random also selects randomly, but once a target is chosen, the system does not fall back to other providers if that target fails, making it suitable for testing specific provider failure modes.

Which strategy is best for minimizing API costs?

Use cost-optimized to automatically select the cheapest provider that satisfies your token budget constraints. For additional control, combine cost-optimized with headroom to ensure the selected provider has sufficient capacity to handle the request without overages.

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