OmniRoute/docs/combo-context-requirements.md

title, version, lastUpdated

title	version	lastUpdated
Combo Context Requirements Feature	3.8.50	2026-08-06

Combo Context Requirements Feature

Overview

The Context Requirements feature allows combo configurations to filter and sort targets based on their context window size. This is useful for use cases requiring large context windows like:

• Long document processing (100k+ tokens)
• Large codebase analysis
• Extensive conversation histories
• Multi-file code reviews

Configuration

Schema

Add contextRequirements to your combo's runtime config:

{
  "contextRequirements": {
    "minContextWindow": 128000,
    "preferLargeContext": true,
    "contextFilterMode": "strict"
  }
}

Fields

minContextWindow (optional)

• Type: number (0 to 10,000,000)
• Default: undefined (no filtering)
• Description: Filters out models with context windows below this threshold

Examples:

• 32000 - Filter out models with <32K context
• 128000 - Require 128K+ context (GPT-4 Turbo, Claude 3)
• 200000 - Require 200K+ context (Claude 3 Opus)
• 1000000 - Require 1M+ context (Gemini 1.5 Pro)

preferLargeContext (optional)

• Type: boolean
• Default: false
• Description: When true, sorts remaining targets by context size (descending). Large context models are tried first.

contextFilterMode (optional)

• Type: "strict" | "lenient"
• Default: "lenient"
• Description: How to handle models with unknown context window limits
  • "strict": Excludes models with unknown context limits when a known-good target remains; fail-opens to unknowns if the pool would otherwise be empty (#8786)
  • "lenient": Includes models with unknown context limits

Behavior

Filtering Pipeline

Context requirements are applied after filterTargetsByRequestCompatibility():

1. Request compatibility filtering - Removes models incompatible with request (tools, vision, structured output)
2. Context requirements filtering - Applies minContextWindow and contextFilterMode
3. Context-based sorting - If preferLargeContext is true, sorts by context size descending

Filter Mode Logic

When minContextWindow is set:

Lenient mode (default):

• ✅ Includes models with context >= minContextWindow
• ✅ Includes models with unknown context limits
• ❌ Excludes models with context < minContextWindow

Strict mode:

• ✅ Includes models with context >= minContextWindow
• ❌ Excludes models with unknown context limits (when at least one known-good target remains)
• ❌ Excludes models with context < minContextWindow
• ⚠️ Fail-open (#8786): if strict filtering would empty the pool and at least one unknown-context target exists, those unknowns are restored instead of returning 404 Combo has no executable targets. Known-too-small targets are never resurrected. When the pool is still empty (every known target is below minContextWindow), the API returns terminalReason: "context_requirements_exhausted" with a recovery hint.

Sorting Logic

When preferLargeContext is true:

• Models are sorted by context window size (descending)
• Unknown context models sort to the end
• Original strategy order is used as a tiebreaker

Use Cases

Example 1: Long Document Processing

{
  "name": "Document Analysis",
  "strategy": "fusion",
  "config": {
    "contextRequirements": {
      "minContextWindow": 128000,
      "preferLargeContext": true,
      "contextFilterMode": "strict"
    }
  }
}

This configuration:

• Requires 128K+ context window
• Prefers larger context models (Gemini 1.5 Pro > Claude 3 Opus > GPT-4 Turbo)
• Excludes models with unknown context limits

Example 2: Large Codebase Analysis

{
  "name": "Code Review",
  "strategy": "auto",
  "config": {
    "contextRequirements": {
      "minContextWindow": 200000,
      "preferLargeContext": true,
      "contextFilterMode": "lenient"
    }
  }
}

This configuration:

• Requires 200K+ context window
• Prefers larger context models
• Includes models with unknown limits (lenient)

Example 3: Prefer Large Context Without Strict Requirements

{
  "name": "Flexible Chat",
  "strategy": "weighted",
  "config": {
    "contextRequirements": {
      "preferLargeContext": true
    }
  }
}

This configuration:

• No minimum requirement (all models eligible)
• Sorts by context size (largest first)
• Useful when large context is preferred but not required

API Response

When context requirements filter targets, the combo logger outputs:

[COMBO] Context requirements: filtered 10 → 3 targets (minContextWindow: 128000, mode: strict)
[COMBO] Context requirements: kept models gemini-1.5-pro, claude-3-opus-20240229, gpt-4-turbo
[COMBO] Context requirements: sorted by context size (descending): gemini-1.5-pro(1000000), claude-3-opus-20240229(200000), gpt-4-turbo(128000)

Implementation Details

Backend Module

open-sse/services/combo/contextRequirements.ts:

• applyContextRequirements() - Main filtering function
• getTargetContextWindow() - Context lookup helper
• Uses getModelContextLimit() from modelCapabilities.ts

Integration Point

open-sse/services/combo.ts line 1187:

orderedTargets = filterTargetsByRequestCompatibility(orderedTargets, body, log);
orderedTargets = applyContextRequirements(orderedTargets, config.contextRequirements, log);

Schema Definition

src/shared/validation/schemas/combo.ts:

contextRequirements: z
  .object({
    minContextWindow: z.coerce.number().int().min(0).max(10_000_000).optional(),
    preferLargeContext: z.boolean().optional(),
    contextFilterMode: z.enum(["strict", "lenient"]).optional(),
  })
  .strict()
  .optional(),

Testing

Run Tests

# Unit tests (schema + logic)
npm test tests/unit/combo-context-requirements.test.ts

# Integration tests (end-to-end)
npm test tests/unit/combo/context-requirements-integration.test.ts

Test Coverage

• Schema validation: 6 tests
• Filtering logic: 6 tests
• Integration: 5 tests
• Total: 17/17 passing ✅

Troubleshooting

All targets filtered out

Problem: All targets removed, combo returns "no compatible models"

Solutions:

1. Lower minContextWindow threshold
2. Switch to "lenient" mode to include unknown context models
3. Remove minContextWindow and use only preferLargeContext

Unknown context models excluded

Problem: Custom/new models excluded even though they have large context

Solutions:

1. Switch to "lenient" mode (default)
2. Add model context limit to modelCapabilities.ts
3. Remove context filtering and rely on strategy order

Sorting not applied

Problem: preferLargeContext doesn't change order

Check:

1. Verify preferLargeContext: true in config
2. Check if all targets have unknown context (all sort equal)
3. Verify multiple targets remain after filtering

Related

• Auto-Combo Routing Strategies
• Resilience Guide

Version History

• v3.8.47: Initial implementation
  • Added contextRequirements config
  • Created backend filtering module
  • Full test coverage (no dedicated dashboard UI yet — configure via combo JSON)