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

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 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/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 (lines 34-35) and weight definitions in [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/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/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 to score candidates and select the optimal provider

Request detection occurs in [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:

// 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:

// 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:

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
• Tiers (fast, cheap, reliable, free, pro) define scoring weights in modePacks.ts, with free and pro also filtering by subscription tier
• The virtual factory (virtualFactory.ts) constructs candidate pools dynamically, falling back to the full pool if filters result in empty sets
• Implementation files: suffixComposition.ts for definitions, autoPrefix.ts for parsing, and 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. 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.

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