How the Priority Routing Strategy Works in OmniRoute

The priority routing strategy in OmniRoute sorts combo targets by their numeric priority field (lower values first) and attempts them sequentially until one succeeds or the list is exhausted.

OmniRoute routes AI requests through combos—ordered lists of provider and model targets. The priority routing strategy serves as the default mechanism, offering deterministic failover by sorting targets based on their assigned priority values before executing requests.

Core Implementation of the Priority Strategy

The priority strategy operates through two critical components in the OmniRoute codebase.

Strategy Definition in Constants

The supported routing strategies are enumerated in src/shared/constants/routingStrategies.ts, where priority is registered as the default strategy. This constant defines the valid strategy names available for combo configuration and establishes the contract that the resolution engine expects.

Target Resolution and Sorting Logic

The actual sorting occurs in open-sse/services/combo.ts within the resolveComboTargets() function. When a combo uses the priority strategy, the engine:

1. Collects all viable targets for the specified provider and model.
2. Retrieves the priority numeric property from each account connection (lower integers indicate higher priority as stored in src/lib/db/connections.ts).
3. Sorts the ResolvedComboTarget[] array in ascending order of the priority field.
4. Returns the ordered list to the router for sequential execution.

This deterministic ordering ensures predictable routing behavior based on the priority values defined in the connection records.

How Priority Routing Handles Failures

When executing a request, OmniRoute attempts the first target in the priority-sorted list. If the target returns an error—such as a rate limit or network failure—the engine automatically proceeds to the next target in the sequence. This continues until either a successful response is received or the sorted list is exhausted, at which point the request returns a combo-level error. Because the strategy exhausts every defined target before failing, it provides comprehensive failover coverage within the combo.

Configuration Example for Priority Routing

Define a combo using the priority strategy by specifying "strategy": "priority" and including multiple accounts with different priority values:

{
  "name": "my-priority-combo",
  "strategy": "priority",
  "models": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "account": "primary-openai",
      "overrides": {}
    },
    {
      "provider": "openai",
      "model": "gpt-4o",
      "account": "backup-openai",
      "overrides": {}
    }
  ],
  "config": {}
}

In this configuration, assuming primary-openai has priority: 1 and backup-openai has priority: 5, OmniRoute will always attempt the primary account first, falling back to the backup only if the primary fails.

Interaction with Other Combo Features

The priority strategy integrates with several other OmniRoute mechanisms to refine target selection.

Metadata Tags Filtering

When a combo specifies metadata.tags, the engine filters the candidate targets to only those matching the requested tags (using any-match semantics) before applying the priority sort. This ensures that priority ordering only considers targets relevant to the current request context.

Cooldowns and Circuit Breakers

If a target enters a cooldown period or triggers a circuit breaker due to repeated failures, it is temporarily removed from the candidate set. The resolveComboTargets() function then sorts the remaining available targets, automatically promoting the next highest-priority account to the first position for that specific request.

Summary

• The priority routing strategy is the default behavior in OmniRoute, defined in src/shared/constants/routingStrategies.ts.
• Targets are sorted by the priority field (ascending numeric order) in open-sse/services/combo.ts via the resolveComboTargets() function.
• Lower priority values indicate higher precedence (priority 1 is tried before priority 5).
• The router attempts targets sequentially and falls back to the next target on any failure.
• Metadata tags filter the candidate list before sorting, while cooldowns temporarily exclude unhealthy targets from the priority queue.

Frequently Asked Questions

What is the default routing strategy in OmniRoute?

OmniRoute uses the priority strategy as its default routing method. This strategy is explicitly defined in the routing strategies constants file and automatically sorts combo targets by their assigned priority values to determine execution order.

How does OmniRoute handle priority ties between accounts?

When two accounts share identical priority values, the resolveComboTargets() function maintains stable sorting based on their position in the underlying data structure. While the order is deterministic, tie-breaking behavior depends on the specific implementation in open-sse/services/combo.ts, so distinct priority values are recommended for predictable failover.

Can I combine priority routing with metadata tags?

Yes. When metadata tags are specified on a combo, the priority strategy first filters the available targets to only those matching the requested tags, then applies the ascending priority sort to the filtered subset. This allows for contextual routing where priority is evaluated within specific tag categories.

What happens if all priority targets fail?

If every target in the priority-sorted list returns an error or becomes unavailable, the request surfaces as a combo-level error. The priority strategy does not consult additional providers outside the defined combo; it exhaustively attempts every configured target before failing the request.

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