# How Auto-Combo Uses the I²-Factor Model for Intelligent Routing in OmniRoute

> Discover how OmniRoute's auto-combo leverages the I²-factor model for intelligent routing. Optimize task suitability and cost efficiency for every request.

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

---

**OmniRoute's auto-combo engine calculates an I²-factor score (Intent × Input) for every provider-model pair to route requests toward the combination that optimally balances task suitability and cost efficiency.**

OmniRoute's intelligent routing system uses a data-driven approach to select the best AI provider-model combination for each request. The **auto-combo** feature implements an **I²-factor model**—often referred to as the **12-factor approach**—that evaluates two critical dimensions: the request's **Intent** and the request's **Input** characteristics. This deterministic scoring system, implemented across the TypeScript codebase, ensures requests are handled by the most capable and economical available combo.

## Understanding the I²-Factor Dimensions

The I²-factor model derives its name from the multiplication of two normalized scores: **Intent** (capability alignment) and **Input** (cost efficiency). Each dimension is scored between 0 and 1, then multiplied to produce a final ranking score.

### Intent Dimension: Capability Matching

The **Intent** dimension measures whether a specific provider-model combo actually supports the type of task being requested. When a request hits the OmniRoute API, the system extracts the intent from the route path—for example, `/api/v1/chat/completions` maps to a *chat* intent, while embedding routes map to *embeddings*.

In [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts), the **combo catalog** maintains a registry of which models support which intents. The router queries this catalog using `getModelCapabilities()` to verify that a candidate combo can handle the request. If the model supports the intent, the Intent score is **1**; otherwise, it is **0**, immediately disqualifying that combo from selection.

### Input Dimension: Cost Efficiency

The **Input** dimension analyzes the economic efficiency of processing the request given its specific token characteristics. This score ensures that expensive models are not used for simple requests when cheaper alternatives exist.

Three components feed into this calculation:

- **Token estimation**: The `estimateTokens()` function in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) counts tokens in the incoming prompt
- **Pricing data**: The pricing sync module ([`src/lib/pricingSync.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/pricingSync.ts)) retrieves per-token costs for each provider-model pair
- **Normalization**: The system computes **1 - (cost / maxCost)** across all candidates, where `maxCost` is the highest price among available options

Higher Input scores indicate better value, with 1 representing the cheapest option and 0 approaching the maximum cost threshold.

## The Scoring Algorithm Implementation

The auto-combo routing engine in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) implements a deterministic six-step scoring flow via the `handleComboChat` service:

1. **Extract intent** from the request path (e.g., `/api/v1/chat/completions` → *chat*)
2. **Gather input metrics** including token count, context window limits, and per-token pricing
3. **Compute normalized Intent** = 1 if the model supports the intent, otherwise 0
4. **Compute normalized Input** = 1 - (cost / maxCost) where `maxCost` is the highest cost among all candidates
5. **Calculate I²-factor** = Intent × Input (values range 0 to 1)
6. **Sort candidates** by descending I²-factor and dispatch to the highest-scoring combo

This multiplication logic automatically eliminates unsuitable providers (Intent = 0) and deprioritizes expensive options (low Input), creating a lightweight but effective ranking system.

### Computing Scores in Code

You can replicate the I²-factor calculation using the internal utilities:

```typescript
import { getModelCapabilities } from '@/lib/db/combo.ts';
import { estimateTokens, getPricing } from '@/lib/pricingSync.ts';

async function computeI2Score(
  providerId: string,
  modelId: string,
  requestIntent: string,
  prompt: string
) {
  // Intent factor: binary capability check
  const caps = await getModelCapabilities(providerId, modelId);
  const intentScore = caps.includes(requestIntent) ? 1 : 0;

  // Input factor: cost efficiency calculation
  const tokenCount = estimateTokens(prompt);
  const priceInfo = await getPricing(providerId, modelId);
  const cost = tokenCount * priceInfo.perToken;
  const maxCost = 0.01; // configurable upper bound used by the router
  const inputScore = 1 - cost / maxCost;

  // I²-factor: product of both dimensions
  return intentScore * inputScore;
}

```

## Real-World Usage with Auto-Combo

To leverage the I²-factor model in production, clients send requests to the OmniRoute API with `model: "auto"`. The system automatically applies the scoring algorithm and selects the optimal provider-model pair.

```typescript
// Example: Using the auto-combo API
import { fetch } from 'node-fetch';

await fetch('https://my.omniroute.instance/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // Optional: override auto-selection with specific combo
    // 'x-omniroute-combo-id': 'my-preferred-combo'
  },
  body: JSON.stringify({
    model: 'auto',
    messages: [{ role: 'user', content: 'Explain I²-factor routing.' }],
  }),
});

```

The `handleComboChat` function in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) processes this request by evaluating all available combos, ranking them by I²-factor, and attempting them sequentially until one succeeds. This provides both intelligent selection and automatic fallback resilience.

## Summary

- The **I²-factor model** evaluates routing candidates using **Intent × Input** scoring, balancing capability with cost
- **Intent** is derived from API route patterns in `src/app/api/v1/**/route.ts` and validated against the combo catalog in [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts)
- **Input** scores rely on token estimation ([`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts)) and pricing data ([`src/lib/pricingSync.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/pricingSync.ts))
- The **auto-combo engine** ([`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) sorts providers by descending I²-factor and attempts them sequentially
- Unsuitable combos score 0 on Intent and are automatically skipped, while expensive options are deprioritized via low Input scores

## Frequently Asked Questions

### What does I² stand for in the OmniRoute routing system?

I² stands for **Intent × Input**, representing the two dimensions multiplied together to calculate a combo's suitability score. The term distinguishes this two-factor approach from single-metric routing algorithms, ensuring both capability alignment and cost efficiency are considered simultaneously.

### How does the auto-combo engine handle unsupported intents?

If a provider-model combo does not support the request's intent according to the catalog in [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts), it receives an Intent score of **0**. When multiplied by any Input score, this results in an I²-factor of 0, effectively filtering that combo from the candidate list entirely.

### What happens if the highest-scoring provider-model combo fails?

The auto-combo engine maintains the full sorted list of candidates by I²-factor. If the top-ranked combo fails—due to rate limits, downtime, or errors—the engine automatically falls back to the next highest-scoring combo in the sequence, preserving request resilience without client intervention.

### Can developers manually override the I²-factor scoring?

Yes. Developers can bypass the automatic selection by including the `x-omniroute-combo-id` header in the API request, specifying a preferred provider-model pair directly. When this header is present, the auto-combo engine skips I²-factor calculation and routes to the specified combo.