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

> Learn how to use OmniRoute's auto model ID for zero-configuration virtual routing combos. Dynamically select candidates from built-in templates and variants.

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

---

**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](https://github.com/diegosouzapw/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/autoRouting.ts) lines 22-31) delegates to [`virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/virtualFactory.ts) to construct the combo. For built-in identifiers, `createBuiltinAutoCombo()` in [`open-sse/services/autoCombo/builtinCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

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

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/targetResolution.ts) and [`strategyDispatch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/strategyDispatch.ts).

## Summary

- **Zero-configuration routing**: The `auto/*` prefix triggers virtual combo creation without database persistence, implemented in [`src/sse/handlers/autoRouting.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.