Auto Routing Strategy in OmniRoute: 15 Factors That Drive Provider Selection

The auto routing strategy in OmniRoute evaluates provider/model candidates using a 15‑factor weighted scoring function that balances quota availability, cost, latency, task fitness, tier alignment, and connection health.

OmniRoute's auto-combo engine eliminates manual provider configuration by dynamically selecting the optimal model for each request. This article breaks down every factor the routing strategy considers, how weights are normalized, and what preprocessing filters apply before scoring begins—all based on the diegosouzapw/OmniRoute source code.

The 15 Core Scoring Factors

All factors are defined in open-sse/services/autoCombo/scoring.ts (lines 53–71). Each contributes to a composite score through the DEFAULT_WEIGHTS map, with the final calculation performed by calculateProviderScore() (lines 44–66).

Resource Availability Factors

• quota – Percentage of remaining quota on the provider account. Higher remaining quota increases the score.
• health – Recent error rate and health status of the connection. Healthier connections score higher.
• sessionAvailability – Whether the connection is available for the current session.
• resetWindowAffinity – Preference for accounts whose quota-reset window arrives sooner, enabling faster resource refresh.

Cost and Performance Factors

• costInv – Inverse of cost; cheaper providers receive higher scores.
• latencyInv – Inverse of measured latency; faster providers receive higher scores.
• quality – Feedback-driven quality signal from the routing-event quality tracker (default weight 0.03). Optional but enabled in most deployments.

Task and Model Fit Factors

• taskFit – Alignment between provider/model capabilities and the requested task, resolved via taskFitness lookup tables.
• specificityMatch – How precisely the request's requirements match a model's declared capabilities.
• tierPriority – Preference for higher-tier models (premium over budget variants).
• tierAffinity – Alignment with the tier explicitly requested by the client through manifest routing.

Stability and Connection Factors

• stability – Observed failure-rate trend and historical reliability.
• contextAffinity – Preference for reusing the current session's provider/model to prevent context window loss.
• cacheAffinity – Advantage of staying on a provider that already holds a cached prompt (default weight 0).
• connectionDensity – Preference for providers with more active connections, reducing contention and improving throughput.

Weight Normalization and Custom Profiles

The engine ensures scoring consistency through normalizeScoringWeights() (lines 78–90). This function rescales any custom weight profile so the total sums to exactly 1.0, preventing dominance by individual factors.

You can define alternative weight profiles in open-sse/services/autoCombo/modePacks.ts for scenarios like quality-first or cost-saver routing without modifying core logic.

Pre-Scoring Filters and Enhancements

Before the 15-factor scoring runs, auto routing applies several preprocessing layers that can exclude candidates entirely:

Provider Diversity and Paid Model Filtering

The providerDiversity.ts and paidModelFilter.ts modules enforce business rules—such as spreading load across providers or restricting to paid-tier models—before candidates enter the scoring pool.

Self-Healing Exclusions

The selfHealing.ts module removes providers exhibiting recent failure patterns, ensuring unstable connections never receive traffic regardless of their theoretical score.

Live Arena ELO and Tier Data

When ARENA_ELO_SYNC_ENABLED is active, the engine incorporates:

• Live Arena ELO rankings for provider/model quality
• models.dev tier data to refine taskFit and tier-related scores

Auto-Prefix Parsing

The auto/<category>[:<tier>] syntax is parsed by autoPrefix.ts (lines 126–129) to select the appropriate candidate pool. Valid prefixes include:

• auto – balanced default across all categories
• auto/coding – task-optimized for code generation
• auto/coding:fast – coding category with low-latency tier preference
• auto:cheap – cost-optimized selection

Practical Usage Examples

Basic Auto Routing

await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Explain the Pythagorean theorem." }]
  })
});

Category and Tier Targeting

await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "auto/coding:fast",
    messages: [{ role: "user", content: "Write a TypeScript function to debounce." }]
  })
});

Inspecting Live Candidates

await fetch("http://localhost:20128/v1/auto-combo/fast/candidates")
  .then(r => r.json())
  .then(console.log);

Key Source Files Reference

File	Purpose
open-sse/services/autoCombo/scoring.ts	15 scoring factors, default weights, and calculateProviderScore()
open-sse/services/autoCombo/autoPrefix.ts	auto/ prefix parsing and variant extraction
open-sse/services/autoCombo/virtualFactory.ts	Per-request AutoComboConfig construction
open-sse/services/autoCombo/builtinCatalog.ts	Available auto variants (coding, fast, cheap, etc.)
open-sse/services/autoCombo/modePacks.ts	Pre-defined weight profiles for common scenarios
src/sse/handlers/chat.ts	Entry point for auto-routed requests

Summary

• The auto routing strategy uses 15 weighted factors covering quota, health, cost, latency, task fit, tier alignment, stability, and connection characteristics.
• Scores are normalized to 1.0 via normalizeScoringWeights() in scoring.ts.
• Preprocessing filters—provider diversity, paid model restrictions, and self-healing—can exclude candidates before scoring.
• Live Arena ELO data enhances task fitness when enabled.
• The auto/<category>[:<tier>] syntax parsed in autoPrefix.ts selects candidate pools before factor evaluation.

Frequently Asked Questions

How does OmniRoute normalize scoring weights?

The normalizeScoringWeights() function in open-sse/services/autoCombo/scoring.ts (lines 78–90) rescales all factor weights proportionally so their sum equals 1.0. This prevents any single factor from disproportionately influencing the final score when custom weight profiles are applied.

Can I disable specific scoring factors?

Yes. Set any factor's weight to 0 in a custom profile, or rely on cacheAffinity and quality defaults which are already 0 or near-zero. For complete exclusion, define a new profile in modePacks.ts with only your desired factors enabled.

What happens when multiple providers have identical scores?

The engine applies deterministic tie-breaking based on provider ID hash order, followed by connection density preference. This ensures consistent routing without arbitrary fluctuation between equivalent candidates.

How does the auto/coding:fast syntax work?

The autoPrefix.ts module splits the string at the slash and colon delimiters. coding maps to a task category in builtinCatalog.ts, while fast selects a tier profile that increases latencyInv and tierPriority weights. The resulting candidate pool is then scored with these adjusted priorities.

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