# OmniRoute Auto-Combo Category and Tier Compositions: Complete Routing Guide

> Unlock OmniRoute's auto-combo routing with this guide. Learn category and tier compositions using auto/<category>[:<tier>] syntax for dynamic request filtering and optimization.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-29

---

**OmniRoute's auto-combo feature uses the syntax `auto/<category>[:<tier>]` to dynamically route requests by filtering models through capability-based categories and optimization-driven tier profiles.**

The **auto-combo** system in [diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) provides a declarative routing mechanism that eliminates manual provider selection. By combining **category** filters with **tier** weight profiles, you can precisely control which models participate in request routing and how the final provider is selected.

## Understanding the Auto-Combo Syntax

The auto-combo engine parses model identifiers using the pattern `auto/<category>[:<tier>]`, where the colon acts as a delimiter between the two compositional elements.

- **Category** (required): Defines the capability filter applied to the candidate pool
- **Tier** (optional): Specifies the scoring algorithm and weight profile used for provider selection

If you omit the tier, the system applies default balanced weights. If your category-tier combination yields an empty candidate pool, the engine implements a **fail-open** strategy, falling back to the full model pool to prevent routing failures.

## Category Options in OmniRoute

Categories filter the virtual candidate pool by model capabilities. These classifications are defined in [[`open-sse/services/autoCombo/suffixComposition.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/suffixComposition.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/open-sse/services/autoCombo/suffixComposition.ts#L33-L35) (lines 33-35) and applied during pool construction.

| Category | Capability Filter |
|----------|-----------------|
| **coding** | Retains only code-generation capable models |
| **reasoning** | Selects thinking/reasoning optimized models |
| **vision** | Keeps only vision-capable models |
| **chat** | Filters for chat-oriented models |
| **multimodal** | Limits pool to vision-plus-text multimodal models |

The category filter executes first in the resolution pipeline, creating the initial virtual candidate pool before tier weights are applied.

## Tier Compositions and Weight Profiles

**Tiers** determine the scoring mechanism that selects the final provider from the filtered pool. According to the source code in [`suffixComposition.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/suffixComposition.ts) (lines 34-35) and weight definitions in [[`open-sse/services/autoCombo/modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/modePacks.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/open-sse/services/autoCombo/modePacks.ts), the following tier options are available:

| Tier | Alias | Optimization Strategy |
|------|-------|----------------------|
| **fast** | `ship-fast` | Maximizes `latencyInv` to prioritize low-latency providers |
| **cheap** | `floor` | Maximizes `costInv` to select the cheapest token cost |
| **reliable** | — | Optimizes for health status and latency stability |
| **free** | — | Filters by `classifyTier` to include only free-tier models |
| **pro** | — | Filters by `classifyTier` to include only premium-tier models |

The `free` and `pro` tiers function as both filters and weight profiles, restricting the candidate pool by subscription tier before applying standard scoring.

## How the Auto-Combo Engine Resolves Requests

The resolution process involves three core components:

1. **Prefix Parsing**: [[`open-sse/services/autoCombo/autoPrefix.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/autoPrefix.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/open-sse/services/autoCombo/autoPrefix.ts) parses the `auto/<category>[:<tier>]` string into structured components
2. **Pool Construction**: [[`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/open-sse/services/autoCombo/virtualFactory.ts) builds the virtual candidate pool by applying category filters
3. **Provider Selection**: The engine applies tier-specific weights from [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts) to score candidates and select the optimal provider

Request detection occurs in [[`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts)](https://github.com/diegosouzapw/OmniRoute), which routes `auto/` prefixed requests through the specialized auto-combo resolution path rather than standard model mapping.

## Practical Implementation Examples

Use the auto-combo syntax in API requests to dynamically route workloads:

```typescript
// Route coding tasks to the fastest available provider
await fetch('http://localhost:20128/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto/coding:fast',
    messages: [{ 
      role: 'user', 
      content: 'Write a Node.js function to parse CSV.' 
    }],
  }),
});

```

Programmatically inspect candidate pools for specific auto-combo configurations:

```typescript
// Retrieve candidate list for a specific auto channel
const res = await fetch(
  'http://localhost:20128/v1/auto-combo/coding/candidates',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const candidates = await res.json();

```

Parse auto-combo prefixes in custom implementations using the internal utility:

```typescript
import { parseAutoPrefix } from '@omniroute/open-sse/services/autoCombo/autoPrefix';

const { variant, tier } = parseAutoPrefix('auto/reasoning:pro');
// variant = 'reasoning', tier = 'pro'

```

## Summary

- OmniRoute auto-combos use the syntax **`auto/<category>[:<tier>`]** to compose routing requests
- **Categories** (`coding`, `reasoning`, `vision`, `chat`, `multimodal`) filter models by capability in [`suffixComposition.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/suffixComposition.ts)
- **Tiers** (`fast`, `cheap`, `reliable`, `free`, `pro`) define scoring weights in [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts), with `free` and `pro` also filtering by subscription tier
- The **virtual factory** ([`virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/virtualFactory.ts)) constructs candidate pools dynamically, falling back to the full pool if filters result in empty sets
- Implementation files: [`suffixComposition.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/suffixComposition.ts) for definitions, [`autoPrefix.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoPrefix.ts) for parsing, and [`chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/chat.ts) for request handling

## Frequently Asked Questions

### What happens if I specify an invalid category or tier combination?

If your category-tier combination produces an empty candidate pool, OmniRoute implements a **fail-open** mechanism. The engine automatically falls back to the full model pool to ensure requests never fail due to overly restrictive filters, though this may result in suboptimal provider selection.

### Can I use tiers without specifying a category?

No, the category is a required component of the auto-combo syntax. You must provide a valid category (`coding`, `reasoning`, `vision`, `chat`, or `multimodal`) after the `auto/` prefix. The tier, however, remains optional—omitting it applies default balanced weighting to the filtered pool.

### What is the difference between `fast` and `ship-fast` tiers?

There is no functional difference. **`ship-fast`** is an alias for the `fast` tier, as defined in the composition logic. Both prioritize low-latency providers using the `latencyInv` weight profile located in [`modePacks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modePacks.ts). Similarly, **`floor`** serves as an alias for the `cheap` tier.

### How does the `free` tier filter differ from the `cheap` tier?

The **`free`** tier filters the candidate pool to include only free-tier models using the `classifyTier` attribute before applying standard scoring, making it a **filtering tier**. The **`cheap`** tier (alias `floor`) does not filter by subscription level; instead, it purely optimizes for the lowest token cost across all available models, including premium ones.