How to Use the Auto Model ID for OmniRoute Routing: Zero-Configuration Virtual Combos

OmniRoute's auto/* model IDs create virtual routing combos on-the-fly, eliminating the need to pre-configure database entries by dynamically selecting candidates from built-in templates, variants, or model families.

The auto model ID system in the OmniRoute repository provides a zero-configuration catalog for intelligent request routing. By prefixing model identifiers with auto/, you trigger a virtual combo creation pipeline that materializes routing strategies dynamically without persisting anything to the database. This architecture allows you to use expressive identifiers like auto/best-coding or auto/gemini while OmniRoute handles candidate pool selection, tier filtering, and resilience logic automatically.

Detecting Auto Routing in Request Handlers

OmniRoute intercepts auto-routed requests at the entry point of the chat completion flow. When a request arrives at the /v1/chat/completions endpoint, the handler in src/sse/handlers/chat.ts evaluates whether the model parameter requires auto-routing resolution.

The detection logic checks for two patterns:

• Exact match: model === "auto"
• Prefix match: model.startsWith("auto/")

When either condition is true, the handler invokes resolveAutoRoutingState() to analyze the ID and prepare the virtual routing context. This occurs at lines 123-129 of src/sse/handlers/chat.ts, ensuring that auto-routed requests bypass the standard persisted combo lookup and enter the virtual combo creation pipeline instead.

Classifying Auto Model ID Patterns

The core classification logic resides in src/sse/handlers/autoRouting.ts, where resolveAutoRoutingState() delegates to classifyAutoModel() to determine the routing strategy. This function implements a cascading recognition system across three distinct pattern types.

Built-in Templates and Flat Variants

OmniRoute maintains two constant registries for recognized auto patterns:

• AUTO_TEMPLATE_VARIANTS: Contains built-in template IDs such as auto/best-coding, auto/pro-vision, and other curated routing profiles
• VALID_AUTO_VARIANTS: Defines simple flat variants like coding, fast, and smart

When classifyAutoModel() matches the incoming ID against these registries, it immediately resolves the variant specification without additional parsing overhead.

Suffix-Based Category and Tier Parsing

For dynamic compositions following the pattern auto/<category>[:<tier>], OmniRoute invokes parseAutoSuffix from the suffix composition module. Examples include:

• auto/coding:fast — selects the coding category with fast tier constraints
• auto/writing:free — targets the writing category filtered to free-tier providers

The parser extracts the category and optional tier components, allowing granular control over the candidate pool without predefined database entries. This logic is implemented in open-sse/services/autoCombo/suffixComposition.ts.

Model Family Detection

When the suffix does not match built-in templates or flat variants, OmniRoute falls back to model-family detection. IDs like auto/gemini or auto/glm trigger family-based routing, where the virtual combo's candidate pool includes all providers advertising that specific model family. The family detection logic is handled in open-sse/services/autoCombo/modelFamily.ts.

Creating and Materializing Virtual Combos

Once the auto ID is classified, OmniRoute materializes a virtual combo object that mimics the structure of persisted database combos without requiring actual storage.

Virtual Factory and Spec Resolution

The createVirtualAutoCombo() function (called from src/sse/handlers/autoRouting.ts lines 22-31) delegates to virtualFactory.ts to construct the combo. For built-in identifiers, createBuiltinAutoCombo() in open-sse/services/autoCombo/builtinCatalog.ts performs the following steps:

1. Calls resolveBuiltinAutoSpec() to normalize the variant, tier, and category specifications
2. Invokes createVirtualAutoCombo (or its "prepared" variant) to generate a combo object
3. Sets the name and id properties to the original auto/* string for transparency in logs and telemetry

Prefix Default Application

When a request specifies only "auto" without a suffix, applyAutoPrefix() (lines 64-90 of src/sse/handlers/autoRouting.ts) loads the user-configured default from settings.autoRoutingDefaultVariant. This fallback ensures that bare auto requests still resolve to a meaningful routing strategy based on deployment preferences defined in open-sse/services/autoCombo/autoPrefix.ts.

Practical Implementation Examples

You can invoke auto-routed models through standard OpenAI-compatible API calls. The following examples demonstrate the three primary usage patterns.

Using Built-in Template Variants

Request a curated routing profile optimized for specific capabilities:

await fetch("/v1/chat/completions", {
  method: "POST",
  body: JSON.stringify({
    model: "auto/best-coding",
    messages: [{ role: "user", content: "Explain quantum tunneling." }],
  }),
});

This triggers the built-in catalog resolver in open-sse/services/autoCombo/builtinCatalog.ts, creating a virtual combo pre-filtered for code-generation capabilities.

Category with Explicit Tier Suffix

Force specific performance and cost constraints using the suffix syntax:

await fetch("/v1/chat/completions", {
  method: "POST",
  body: JSON.stringify({
    model: "auto/coding:fast",
    messages: [{ role: "user", content: "Write a quick sort implementation." }],
  }),
});

The parseAutoSuffix function extracts coding as the category and fast as the tier, limiting the candidate pool to providers meeting both criteria.

Model Family Routing

Route to any provider serving a specific model family without specifying capabilities:

await fetch("/v1/chat/completions", {
  method: "POST",
  body: JSON.stringify({
    model: "auto/gemini",
    messages: [{ role: "user", content: "Summarize the latest news." }],
  }),
});

OmniRoute constructs the virtual combo from all providers exposing the gemini family, then applies standard scoring and resilience logic through the execution pipeline in open-sse/services/combo/targetResolution.ts and strategyDispatch.ts.

Summary

• Zero-configuration routing: The auto/* prefix triggers virtual combo creation without database persistence, implemented in src/sse/handlers/autoRouting.ts.
• Pattern recognition: OmniRoute classifies IDs through classifyAutoModel() using built-in templates (AUTO_TEMPLATE_VARIANTS), flat variants (VALID_AUTO_VARIANTS), suffix parsing, or family detection.
• Dynamic materialization: Virtual combos are instantiated via createVirtualAutoCombo() and createBuiltinAutoCombo(), producing objects compatible with the standard execution pipeline.
• Flexible syntax: Support for auto/best-coding (templates), auto/coding:fast (category:tier), and auto/gemini (family routing) provides granular control over candidate selection.
• Seamless execution: Virtual combos execute through the standard combo resolution flow in open-sse/services/combo/, ensuring resilience, cost optimization, and streaming behavior identical to persisted combos.

Frequently Asked Questions

What happens if I use just "auto" without any suffix?

OmniRoute applies the user-configured default variant specified in settings.autoRoutingDefaultVariant. The applyAutoPrefix() function in src/sse/handlers/autoRouting.ts handles this fallback, ensuring the request still resolves to a valid routing strategy even without explicit category or tier specification.

Can I combine auto model IDs with custom resilience settings?

Yes. Once the virtual combo is materialized by createBuiltinAutoCombo() or createVirtualAutoCombo(), it enters the standard combo execution pipeline. This means all resilience, retry, and fallback logic defined in open-sse/services/combo/strategyDispatch.ts applies to auto-routed requests exactly as it does for persisted combos.

How does OmniRoute distinguish between a model family and a built-in template?

The classification occurs in classifyAutoModel() within src/sse/handlers/autoRouting.ts. The function checks AUTO_TEMPLATE_VARIANTS and VALID_AUTO_VARIANTS first, then attempts suffix parsing. If no template or variant matches, it falls back to checking against known model families via the logic in open-sse/services/autoCombo/modelFamily.ts. This cascading approach ensures auto/best-coding (template) resolves differently from auto/gemini (family).

Are auto model IDs slower than pre-configured combos?

No. While auto IDs require an additional classification step via resolveAutoRoutingState(), the virtual combo creation in open-sse/services/autoCombo/builtinCatalog.ts executes entirely in memory without database I/O. The resulting combo object is then processed by the same high-performance execution pipeline used for persisted combos, making the latency impact negligible for most deployments.

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