How to Use Auto Model Prefixes for Zero-Config Routing in OmniRoute

OmniRoute's auto/* model identifiers enable zero-configuration routing by dynamically resolving requests to the best-scoring connected model without hard-coding specific providers.

OmniRoute ships with a built-in catalog of auto/* model prefixes that abstract away provider-specific details. When a request contains an auto prefix, the router dynamically resolves the identifier to the highest-scoring model currently available in the operator's backend pool, applying resilience, quota, cost, and latency heuristics automatically. This guide explains the resolution flow and implementation details based on the v3.8.51 source code.

How Auto Prefix Resolution Works

The resolution process involves four distinct stages that transform a generic auto request into a concrete model execution.

Request-Time Detection

The Task-Aware Smart Router located in open-sse/services/taskAwareRouter.ts maps incoming request intent to an auto/<category>[:<tier>] identifier. For example, coding-related prompts map to auto/coding, while general chat requests may map to auto/chat:fast. This mapping is defined in the DEFAULT_TASK_MODEL_MAP constant at lines 85-92.

Recognition and Validation

Upon receiving a request, the handler checks whether the model string starts with auto/. The helper function isRecognizedBuiltinAuto in open-sse/services/autoCombo/builtinCatalog.ts (lines 106-112) confirms the identifier exists within the built-in catalog, distinguishing between flat variants, tiered suffixes, and family identifiers.

Resolution Strategies

Depending on the specific auto prefix format, OmniRoute applies three distinct resolution strategies:

• Flat variants (e.g., auto/coding): The catalog entry in AUTO_TEMPLATE_VARIANTS maps directly to a router variant like coding (lines 23-38 in builtinCatalog.ts).
• Category-tier suffixes (e.g., auto/coding:fast): The parseAutoSuffix function parses the suffix into a structured {category, tier} specification (lines 64-71).
• Family identifiers (e.g., auto/glm): isValidModelFamily validates the family name against supported providers in open-sse/services/autoCombo/modelFamily.ts (lines 4-7).

The resolved specification is returned by resolveBuiltinAutoSpec (lines 61-78) for downstream processing.

Virtual Combo Materialization

The createBuiltinAutoCombo function in open-sse/services/autoCombo/virtualFactory.ts lazily builds a virtual auto-combo—a temporary combo object that selects concrete models based on the current pool of connected backends. This occurs without persisted database rows, maintaining the "zero-config" paradigm.

Supported Auto Prefix Patterns

OmniRoute recognizes several auto prefix patterns to accommodate different routing requirements.

Category-Based Routing

Use auto/<category> to route based on task type. Available categories include coding, chat, vision, and embedding. The router selects the best-connected model capable of handling the specific task category.

Tiered Preferences

Append tier suffixes to express latency or cost preferences while remaining provider-agnostic. Valid suffixes defined in AUTO_SUFFIX_VARIANTS (lines 64-73) include:

• :fast – Prioritizes low-latency models
• :cheap – Optimizes for cost efficiency
• :pro – Selects highest-capability models
• :free – Routes to no-cost tiers only

Example: auto/coding:fast selects the lowest-latency coding model available.

Model Family Routing

Use auto/<family> to constrain routing to specific model families (e.g., auto/glm, auto/gpt, auto/claude). The isValidModelFamily function validates these identifiers against the provider registry.

Benefits of Zero-Config Routing

Using auto prefixes provides automatic access to OmniRoute's advanced routing capabilities without manual configuration.

Built-In Resilience Layers

Because auto requests ultimately pass through the normal combo execution path, they automatically benefit from provider-wide circuit breakers, connection cooldowns, and model lockout mechanisms. You do not need to configure fallback logic manually.

Dynamic Pool Updates

As providers are added, removed, or change quota status, the auto-combo pool recomputes automatically. A request to auto/coding made at 09:00 may route to Provider A, while the same request at 09:05 may route to Provider B if Provider A exhausts its quota or experiences connectivity issues.

Tiered Optimization

Suffixes like :fast or :cheap allow you to express performance preferences while maintaining provider abstraction. The scoring algorithm weights latency, cost, and quality metrics according to the tier specification without requiring you to know which specific provider offers the best terms at any given moment.

Practical Implementation Examples

The following examples demonstrate how to use auto prefixes in API requests.

Basic Category Routing

Request the best available coding model without specifying a provider:

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

Latency-Optimized Routing

Use the :fast suffix to prioritize low-latency responses:

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: "Explain the difference between `let` and `const`." 
    }]
  })
});

Task-Aware Automatic Selection

Omit the model field entirely to let the Task-Aware Router detect intent and apply the appropriate auto prefix:

await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    messages: [{ 
      role: "user", 
      content: "Write a quicksort implementation in Python." 
    }]
  })
});

In this case, the router analyzes the prompt, determines it is a coding task, and internally substitutes auto/coding before execution.

Summary

• Auto prefixes (auto/<category>, auto/<category>:<tier>, auto/<family>) eliminate the need to hard-code provider-model pairs in OmniRoute.
• Resolution flow involves detection by taskAwareRouter.ts, validation via isRecognizedBuiltinAuto, parsing through parseAutoSuffix or resolveBuiltinAutoSpec, and materialization by createBuiltinAutoCombo in virtualFactory.ts.
• Tier suffixes (:fast, :cheap, :pro, :free) enable latency and cost optimization without provider-specific knowledge.
• Zero-config benefits include automatic resilience handling, dynamic backend pool updates, and maintenance-free failover.

Frequently Asked Questions

What happens if no backends support the requested auto category?

If no connected providers offer models matching the requested category (e.g., auto/vision when only text models are connected), OmniRoute returns a routing error indicating no eligible models were found in the current pool. The request fails fast rather than attempting execution on unsuitable hardware.

Can I combine tier suffixes with model family prefixes?

No, the current implementation in builtinCatalog.ts treats category-tier combinations and family identifiers as separate resolution paths. You cannot request auto/glm:fast because family routing (auto/glm) and tiered category routing (auto/coding:fast) use distinct parsing logic in resolveBuiltinAutoSpec.

How does the router choose between multiple models in the same tier?

The auto-combo scorer evaluates all connected models matching the specification using a weighted heuristic considering current latency measurements, token cost, remaining quota, and historical success rates. The highest-scoring model receives the request, with automatic fallback to the next highest if the first fails.

Do auto prefixes work with streaming responses?

Yes, because auto prefixes resolve to standard combo objects before execution, they support all standard OpenAI-compatible endpoints including streaming. The resolution occurs once at request initialization, after which the connection behaves identically to a directly-specified model request.

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