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

> Learn about zero-config model IDs for OmniRoute's Auto-Combo Engine. Enable automatic provider selection with auto prefix, simplifying your setup. Get the complete guide.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```typescript
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:

```typescript
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:

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

```

Per [`src/sse/handlers/chatHelpers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/builtinCatalog.ts)** — Defines virtual combo mappings and `auto/*` pattern resolution
- **[`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts)** — Parses model strings and enforces zero-config routing rules
- **[`src/sse/handlers/chatHelpers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chatHelpers.ts)** — Implements fuzzy lookup with `auto/best-<suffix>` fallback
- **[`src/sse/handlers/autoRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/autoRouting.ts)** — High-level entry point for auto-routing resolution

Unit tests in [`tests/unit/auto-combo-engine.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/builtinCatalog.ts) (definitions), [`requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/requestControls.ts) (parsing), [`chatHelpers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/builtinCatalog.ts) version-controls category definitions.