OmniRoute Combo Routing Strategies: Complete Guide to the 17 Public Algorithms

OmniRoute exposes 17 distinct combo routing strategies—defined in src/shared/constants/routingStrategies.ts—that control how requests are distributed across multiple provider-model targets, ranging from simple round-robin to advanced Power-of-Two-Choices and context-aware selection algorithms.

OmniRoute's combo routing engine enables intelligent load distribution across multiple AI providers by applying configurable dispatch algorithms. In the diegosouzapw/OmniRoute repository, these algorithms are centrally defined as the combo routing strategies available to both the UI and API, with the complete enumeration stored in the ROUTING_STRATEGY_VALUES constant.

Complete List of the 17 Combo Routing Strategies

The public API and UI expose exactly 17 strategies. While the source distinguishes these from internal variants (such as quota-share), the following list represents the full set of selectable algorithms:

• priority — Selects the first target matching the requested priority tier (e.g., fastest, balanced, default). Use this when you need guaranteed precedence for high-tier models.

• weighted — Distributes traffic randomly but proportionally according to numeric weights assigned to each target. Ideal for fine-grained traffic shaping across providers with different capacities.

• fill-first — Saturates a single target until its quota or capacity limit is reached before falling back to the next. Useful for exhausting cheaper providers before utilizing premium ones.

• round-robin — Cycles through targets in a fixed sequential order, distributing requests evenly without regard to current load or cost.

• p2c (Power-of-Two-Choices) — Randomly selects two candidates and picks the one with lower current load. This improves distribution fairness while keeping selection computationally cheap.

• random — Chooses a target uniformly at random. Serves as a baseline fallback when no specific load-balancing policy is required.

• least-used — Selects the target that has processed the fewest requests in the current accounting period. Helps evenly spread usage over time across all providers.

• reset-aware — Prefers providers that have recently reset their usage counters (daily or monthly quotas). Optimizes for fresh quota windows.

• reset-window — Similar to reset-aware but operates within a configurable time window after a reset occurs, allowing fine-tuned handling of quota-reset periods.

• cost-optimized — Ranks targets by effective cost (price multiplied by estimated token usage) and selects the cheapest option. Minimizes spend when multiple providers offer equivalent models.

• strict-random — Random selection that excludes any target currently flagged as unhealthy or over-quota. Guarantees that only viable providers receive traffic.

• auto — Adaptive selection combining multiple heuristics; the exact algorithm adjusts based on runtime metrics including latency, cost, and availability.

• lkgp (Last-Known-Good-Provider) — Falls back to the most recent provider that successfully fulfilled a request. Provides resilience after transient failures by favoring proven-healthy endpoints.

• context-optimized — Chooses the target that can best satisfy the required context length or token limit for the specific request. Critical for long prompts or large context windows.

• context-relay — Routes to a provider capable of relaying context from previous turns (e.g., reasoning cache). Enables multi-turn reasoning across disparate providers.

• headroom — Selects the provider with the greatest remaining headroom (quota divided by cost). Balances usage to prevent premature quota exhaustion.

• fusion — Merges multiple providers into a single logical target, distributing parts of composite requests (such as tool results) among them. Supports advanced composite response generation.

How Combo Routing Strategies Work in OmniRoute

At runtime, the combo routing engine resolves available targets and applies the selected strategy through a handler function. In open-sse/services/combo.ts, the system retrieves the appropriate strategy implementation via getStrategyHandler before executing the selection logic.

// open-sse/services/combo.ts – runtime strategy application
import { resolveComboTargets } from "./combo";
import { getStrategyHandler } from "./strategies";

export async function handleComboChat(combo, request) {
  const targets = await resolveComboTargets(combo);
  const chooser = getStrategyHandler(combo.strategy);   // ← selects strategy handler
  const ordered = chooser(targets);                    // ← ordered list of targets
  
  for (const target of ordered) {
    const result = await handleSingleModel(target, request);
    if (result.success) return result;
  }
  throw new Error("All combo targets failed");
}

The chooser function returns an ordered array of targets based on the specific algorithm (e.g., weighted random, least-loaded, or cost-ranked), which the engine then iterates until a successful response is obtained.

Defining and Validating Strategies

All 17 strategies are enumerated in ROUTING_STRATEGY_VALUES within src/shared/constants/routingStrategies.ts. The system validates combo configurations against this enumeration using Zod schemas to prevent invalid strategy assignments.

// src/shared/validation/schemas/combo.ts
import { ROUTING_STRATEGY_VALUES } from "@/shared/constants/routingStrategies";

export const comboStrategySchema = z.enum(ROUTING_STRATEGY_VALUES);

Unit tests in tests/unit/autocombo-unification.test.ts enforce that the validation schema remains synchronized with the source constants, ensuring that only the defined 17 strategies are accepted by the API.

// tests/unit/autocombo-unification.test.ts – validation testing
import { ROUTING_STRATEGY_VALUES } from "@/shared/constants/routingStrategies";
import { comboStrategySchema } from "@/shared/validation/schemas/combo";

describe("combo strategy schema", () => {
  it("exposes exactly the 17 public strategies", () => {
    const schemaValues = comboStrategySchema.options;
    expect(schemaValues).toEqual([...ROUTING_STRATEGY_VALUES]);
  });
});

Code Implementation Examples

When creating a combo via the API endpoint in src/app/api/v1/combo/route.ts, you specify the strategy by passing one of the 17 valid string values to the createCombo function:

// src/app/api/v1/combo/route.ts – creating a combo with specific strategy
import { createCombo } from "@/lib/db/combo";
import { ROUTING_STRATEGY_VALUES } from "@/shared/constants/routingStrategies";

await createCombo({
  name: "fast-priority-combo",
  strategy: "priority",               // ← must be in ROUTING_STRATEGY_VALUES
  models: [
    { provider: "openai", model: "gpt-4o-mini", tier: "priority" },
    { provider: "anthropic", model: "claude-3-haiku-20240307", tier: "flex" },
  ],
});

Selecting the correct strategy depends on whether your priority is cost reduction (cost-optimized), high availability (strict-random, lkgp), or quota utilization (headroom, fill-first).

Internal vs. Public Strategies

Beyond the 17 public strategies listed above, OmniRoute maintains internal routing logic in INTERNAL_ROUTING_STRATEGY_VALUES. For example, quota-share operates server-side for quota-sharing logic between instances but is not exposed as a user-selectable option. When configuring combos through the UI or REST API, only the public 17 strategies are valid inputs.

Summary

• OmniRoute defines 17 public combo routing strategies in src/shared/constants/routingStrategies.ts, enumerated in ROUTING_STRATEGY_VALUES.
• Strategies range from simple distribution algorithms (random, round-robin) to sophisticated load-aware and cost-aware selectors (p2c, cost-optimized, headroom).
• The comboStrategySchema in src/shared/validation/schemas/combo.ts validates all strategy assignments against the canonical list.
• Runtime selection occurs in open-sse/services/combo.ts via getStrategyHandler, which returns a function to order targets according to the specified algorithm.
• Internal strategies exist for server-side operations but are not exposed through the public API.

Frequently Asked Questions

What are the 19 combo routing strategies available in OmniRoute?

The public API exposes 17 combo routing strategies, not 19. These are defined in src/shared/constants/routingStrategies.ts and include algorithms like priority, weighted, p2c, lkgp, and fusion. Additional internal strategies such as quota-share exist in INTERNAL_ROUTING_STRATEGY_VALUES for server-side use but are not user-configurable, bringing the total number of implemented algorithms higher while keeping the public interface at 17 options.

How do I configure a combo routing strategy in OmniRoute?

Specify the strategy key when calling createCombo in src/app/api/v1/combo/route.ts. The value must be a string present in ROUTING_STRATEGY_VALUES (e.g., "cost-optimized" or "round-robin"). The system validates your input against comboStrategySchema before persisting the configuration.

Which strategy should I use to minimize API costs?

Use cost-optimized, which ranks targets by effective cost (price per token) and always selects the cheapest viable provider. Alternatively, fill-first minimizes costs by exhausting low-cost providers completely before routing to expensive alternatives, though this may affect latency during quota transitions.

What is the difference between reset-aware and reset-window strategies?

reset-aware gives preference to providers that have recently reset their usage counters without time constraints. reset-window adds a configurable temporal boundary, only prioritizing recently-reset providers within a specific duration after the reset event. Use reset-window when you want to limit preferential routing to a narrow grace period following quota renewal.

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