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

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, 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 counts tokens in the incoming prompt
• Pricing data: The pricing sync module (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 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:

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.

// 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 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
• Input scores rely on token estimation (src/lib/db/compression.ts) and pricing data (src/lib/pricingSync.ts)
• The auto-combo engine (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, 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.

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