Where to Find OmniRoute's Combo Handler: Complete Source Code Guide

OmniRoute's combo handler lives in open-sse/services/combo.ts as the handleComboChat function, with supporting logic distributed across the open-sse/services/combo/ directory.

OmniRoute implements sophisticated model routing through its "combo" system, which orchestrates multiple AI providers and fallback strategies. If you are debugging routing behavior or extending the framework, you need to locate the core OmniRoute combo handler code. The implementation resides in the Open-SSE services layer of the diegosouzapw/OmniRoute repository.

Main Entry Point: open-sse/services/combo.ts

The primary entry point for all combo processing is open-sse/services/combo.ts. This file exports handleComboChat, the main async function that implements the full routing lifecycle including fallback chains, session stickiness, auto-combo selection, and quota management.

// open-sse/services/combo.ts
export async function handleComboChat(params: {
  body: any;
  combo: ComboDefinition;
  handleSingleModel: ModelExecutor;
  isModelAvailable?: ModelAvailabilityChecker;
  log: Logger;
  settings: Settings;
  allCombos: ComboMap | null;
  relayOptions: RelayOptions;
  signal?: AbortSignal;
}): Promise<Response> {
  // Full orchestration logic: pinning, strategy selection, retries, etc.
}

This function returns a standard Fetch API Response and is designed to be pure-async, making it easy to integrate into Next.js API routes or other server frameworks.

Supporting Modules in the Combo Directory

The handler delegates specific responsibilities to specialized modules within open-sse/services/combo/:

• comboStructure.ts – Contains resolveComboTargets, resolveComboRuntimeUnits, and filterTargetsByRequestCompatibility for turning combo definitions into executable target lists.
• applyStrategyOrdering.ts – Implements the 17 built-in routing strategies including priority, weighted, round-robin, and quota-share.
• autoStrategy.ts – Houses buildAutoCandidates and resolveAutoStrategyOrder for automatic model selection based on scoring heuristics.
• fusion.ts – Implements handleFusionChat for parallel model panels with a judging model.
• pipeline.ts – Implements handlePipelineChat for sequential model chaining.
• quotaShareStrategy.ts – Handles quota-share target selection and concurrency limits.
• comboCooldownRetry.ts – Manages the "cool-down-wait" mechanic for quota-share strategies.
• comboPredicates.ts – Provides predicate functions for target eligibility checks (model lockout, provider cooldown).
• rrState.ts – Maintains round-robin sticky state (counters and sticky targets).

How the Combo Handler Works (Execution Flow)

Understanding the handleComboChat implementation requires following its strict 11-phase execution pipeline:

1. Context Setup

The handler begins by calling phaseComboSetup to create a comboCtx object containing the request body, combo definition, runtime settings, and logger.

2. Pinned Model Shortcut

If a session-cache pin exists, the handler attempts the pinned model first, guarded by health checks before proceeding to the full strategy.

3. Strategy Shortcuts

For specialized modes, the handler routes directly to subsystem handlers:

• fusion → handleFusionChat (parallel execution with judge)
• pipeline → handlePipelineChat (sequential steps)

4. Target Expansion and Resolution

Wildcards like openai/* are expanded via expandProviderWildcardsInCombo. Then resolveComboTargets flattens the combo definition into a list of ResolvedComboTarget objects.

5. Strategy-Specific Ordering

Depending on the strategy defined in the combo:

• Simple strategies (priority, round-robin, weighted) build an ordered list directly.
• auto triggers resolveAutoStrategyOrder, which calls buildAutoCandidates to generate and score candidates.

6. Session Stickiness and Task Routing

The handler optionally re-orders targets based on recent successful targets. If enabled, classifyTask and reorderByTaskWeight further refine the order based on task-aware weights.

7. Pre-Screen and Quota Checks

Early validation prunes unavailable targets using provider cooldown checks and quota-share availability.

8. Execution Loop

The handler iterates through ordered targets, invoking handleSingleModelWithTimeout for each attempt. This loop includes:

• Quality validation via validateResponseQuality
• Retry logic with per-target back-off
• Global MAX_GLOBAL_ATTEMPTS enforcement
• Quota-share cooldown waits

9. Shadow Routing

Parallel "shadow" targets execute for telemetry purposes without affecting the primary response path.

If all targets fail, the function returns a comboModelNotFoundResponse (404-style error).

Practical Usage Example

The following pattern shows how higher-level routes (such as src/app/api/v1/chat/completions/route.ts) invoke the combo handler:

import { handleComboChat } from '@/open-sse/services/combo';

async function routeCombo(requestBody: any) {
  // Retrieve combo definition from your data store
  const combo = await getComboFromDb('my-awesome-combo');

  const response = await handleComboChat({
    body: requestBody,
    combo,
    handleSingleModel: (body, modelStr, target) => 
      defaultExecutor.execute(body, modelStr, target),
    isModelAvailable: undefined,
    log: console,
    settings: {},
    allCombos: null,
    relayOptions: {},
    signal: undefined,
  });

  return response; // Returns standard Fetch API Response
}

This structure delegates the complex routing orchestration to the combo service while keeping the API route thin and maintainable.

Summary

• Primary Location: open-sse/services/combo.ts contains the handleComboChat function that serves as the single source of truth for combo routing.
• Strategy Implementations: open-sse/services/combo/applyStrategyOrdering.ts defines the 17 built-in routing algorithms.
• Advanced Modes: Fusion and pipeline strategies live in fusion.ts and pipeline.ts respectively.
• State Management: Round-robin state and auto-combo scoring reside in rrState.ts and autoStrategy.ts.
• Integration: The handler is framework-agnostic, returning a standard Response object suitable for Next.js, Express, or other Node.js servers.

Frequently Asked Questions

What is the main function that handles combo routing in OmniRoute?

The main function is handleComboChat exported from open-sse/services/combo.ts. This async function orchestrates the entire combo lifecycle including strategy selection, target resolution, fallback retries, and session stickiness.

Where are the routing strategies like round-robin and weighted implemented?

These strategies are implemented in open-sse/services/combo/applyStrategyOrdering.ts. This module contains the logic for all 17 built-in strategies including priority, weighted distribution, round-robin, auto-selection, and quota-share.

How does OmniRoute handle automatic model selection in combos?

Auto-combo logic resides in open-sse/services/combo/autoStrategy.ts. The buildAutoCandidates function generates eligible model candidates, while resolveAutoStrategyOrder applies scoring heuristics to select the optimal target without manual configuration.

What file contains the fusion and pipeline strategy logic?

Fusion (parallel panel with judge) and pipeline (sequential chaining) have dedicated files: open-sse/services/combo/fusion.ts and open-sse/services/combo/pipeline.ts. These export handleFusionChat and handlePipelineChat, which are called as shortcuts within the main combo handler when those specific strategies are requested.

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