Zero-Config Model IDs for OmniRoute's Auto-Combo Engine: The Complete Guide

OmniRoute's Auto-Combo Engine supports zero-config model IDs that start with the auto prefix, enabling automatic provider selection without specifying concrete provider-model pairs.

The zero-config model IDs in OmniRoute eliminate the need to hardcode provider names or model versions. By using the auto prefix, developers rely on the Auto-Combo Engine's real-time scoring algorithm to select optimal providers based on latency, cost, and capability filters.

How Zero-Config Model IDs Work

Zero-config IDs follow a predictable pattern: auto acts as the root keyword, with optional suffixes that refine the selection criteria. The builtin auto-combo catalog in open-sse/services/autoCombo/builtinCatalog.ts defines how these patterns map to candidate provider pools.

When a request arrives with a zero-config model ID, the engine in open-sse/services/autoCombo/requestControls.ts performs three operations:

1. Parses the model string to extract the category, tier, and any fuzzy shortcuts
2. Resolves the pattern against the current provider pool
3. Applies the 15-factor Auto-Combo scoring algorithm to select the best match

The routing helper in src/sse/handlers/chatHelpers.ts handles the fallback logic: it first attempts auto/best-<suffix> before falling back to auto/<suffix> when no explicit "best" combo exists.

Complete List of Zero-Config Model IDs

Generic Auto-Routing

Zero-Config ID	Purpose	Resolution Behavior
auto	Default auto-routing for chat	Selects the highest-scoring combo from the default chat category
auto/fast	Speed-optimized selection	Shortcut that tries auto/best-fast then auto/fast
auto/best-<category>	Highest-scoring in category	Uses the full scoring algorithm to pick the top-ranked combo

Category-Based Selection

Zero-Config ID	Example Use Case	Provider Filter
auto/coding	Code generation and analysis	Providers with coding capability tags
auto/reasoning	Complex problem-solving	Providers with reasoning/advertised reasoning models
auto/vision	Image understanding	Providers with multimodal vision support

Tiered Selection

Zero-Config ID	Format	Tier Meaning
auto/<category>:pro	auto/coding:pro	Professional-grade models (highest quality, higher cost)
auto/<category>:fast	auto/chat:fast	Latency-optimized models (faster response, potentially lower quality)
auto/<category>:lite	auto/vision:lite	Cost-optimized models (lower cost, acceptable quality trade-off)

Code Examples: Using Zero-Config IDs

Basic Auto-Routing

This example uses the simplest zero-config form. The engine selects any available provider without caller knowledge of the underlying model.

import { fetchChatCompletion } from "@omniroute/open-sse";

const response = await fetchChatCompletion({
  model: "auto",
  messages: [{ 
    role: "user", 
    content: "Explain quantum computing in simple terms." 
  }],
});

The builtin catalog expands auto to all connected providers with chat capability, then scores each based on current performance metrics.

Category-Specific with Tier

Target coding capabilities with professional-grade quality:

const response = await fetchChatCompletion({
  model: "auto/coding:pro",
  messages: [{ 
    role: "user", 
    content: "Refactor this Python function to use async/await" 
  }],
});

The engine builds a virtual combo including only providers advertising coding:pro capability, then applies latency and cost scoring within that filtered pool.

Fuzzy Shortcut Resolution

The auto/fast pattern demonstrates OmniRoute's fallback resolution:

const response = await fetchChatCompletion({
  model: "auto/fast",
  messages: [{ 
    role: "user", 
    content: "Summarize this text in one sentence." 
  }],
});

Per src/sse/handlers/chatHelpers.ts, this first attempts to match auto/best-fast. If no explicit "best-fast" combo exists in the catalog, it falls back to auto/fast and scores all fast-tier candidates.

Direct Auto-Combo API Access

For advanced use cases, resolve zero-config IDs manually:

import { 
  resolveAutoRoutingState, 
  createVirtualAutoCombo 
} from "@omniroute/open-sse/services/autoCombo";

const routingState = await resolveAutoRoutingState("auto/best-reasoning");
const virtualCombo = await createVirtualAutoCombo(
  routingState, 
  null,           // optional filter constraints
  apiKeyId        // authentication context
);

console.log(virtualCombo.selectedProviders); // inspect resolved providers

This exposes the internal virtual combo object, useful for debugging routing decisions or implementing custom middleware.

Source File Reference

The zero-config model ID system spans these core files in the diegosouzapw/OmniRoute repository:

• open-sse/services/autoCombo/builtinCatalog.ts — Defines virtual combo mappings and auto/* pattern resolution
• open-sse/services/autoCombo/requestControls.ts — Parses model strings and enforces zero-config routing rules
• src/sse/handlers/chatHelpers.ts — Implements fuzzy lookup with auto/best-<suffix> fallback
• src/sse/handlers/autoRouting.ts — High-level entry point for auto-routing resolution

Unit tests in tests/unit/auto-combo-engine.test.ts validate that all documented zero-config IDs behave correctly across provider pool changes.

Summary

• Zero-config IDs use the auto prefix to defer provider selection to runtime
• Patterns include: auto, auto/<category>, auto/<category>:<tier>, and auto/best-<category>
• Resolution order: auto/best-<suffix> attempts first, then auto/<suffix> fallback
• Core files: builtinCatalog.ts (definitions), requestControls.ts (parsing), chatHelpers.ts (routing)
• Tiers (:pro, :fast, :lite) filter candidates before scoring

Frequently Asked Questions

What happens if no provider matches a zero-config ID?

OmniRoute returns a routing error with available categories. The engine requires at least one connected provider advertising the requested capability or tier. Check provider health status and capability tags in the admin dashboard.

Can I combine multiple tiers in one zero-config ID?

No. The tier syntax accepts exactly one qualifier (:pro, :fast, or :lite). For complex requirements, use the direct API to build custom virtual combos with createVirtualAutoCombo and manual provider filtering.

How does the scoring algorithm rank providers?

The 15-factor Auto-Combo scoring algorithm evaluates: current latency, recent error rates, token throughput, cost per 1K tokens, model benchmark scores, context window size, and provider-specific reliability metrics. Scores recalculate every 30 seconds based on real performance data.

Are zero-config IDs stable across OmniRoute versions?

Yes. The auto prefix and core patterns (auto/coding, auto:pro, etc.) are stable APIs. New categories and tiers may be added, but existing patterns remain backward compatible. The builtin catalog in builtinCatalog.ts version-controls category definitions.

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