How OmniRoute's Compression Engine Selection Works Across 12 Composable Engines

OmniRoute's compression engine selection uses a registry-based strategy selector that assembles pipelines from 12+ self-contained engines, composes them sequentially in an I² model, and validates each step against runtime flags and merged configurations.

OmniRoute's compression subsystem is architected around modular, interchangeable engines that can be chained together for complex transformations. The diegosouzapw/OmniRoute repository implements this through a deterministic pipeline builder that reads persistent plans, validates engine availability, and executes steps where each engine's output feeds the next engine's input.

The Engine Registry: 12+ Self-Contained Compression Units

Every compression engine in OmniRoute implements a standard interface defined in open-sse/services/compression/engines/registry.ts. This interface requires four methods:

• apply(data) – Execute compression
• compress(data) – Alternative entry point
• getConfigSchema() – Return JSON schema for validation
• validateConfig(config) – Runtime configuration checking

Engines register themselves at startup, making them discoverable by ID. The registry exposes getEngine(id) (also aliased as getCompressionEngine(id)) for lookup, setEngineEnabled(id, enabled) for runtime toggling, and updateEngineConfig(id, config) for dynamic reconfiguration.

Operators can disable engines without redeploying, which is critical for production incident response.

How the Strategy Selector Builds Compression Pipelines

The open-sse/services/compression/strategySelector.ts file implements the core selection logic. When processing a request, the selector performs a six-step validation and assembly process:

1. Plan retrieval – Reads the ordered list of steps from the compression_detail table, normalized through src/lib/db/compressionDetailNormalizers.ts
2. Engine lookup – Calls getEngine(id) for each step; unknown IDs trigger validation errors at lines 948 and 1060
3. Enabled check – Skips disabled engines silently
4. Config merging – Combines step-specific config with engine defaults via updateEngineConfig
5. Schema validation – Runs engine.validateConfig() on the merged result
6. Pipeline assembly – Produces an executable sequence of engine instances

Errors accumulate in a validation set rather than failing fast, allowing comprehensive feedback when multiple engines are misconfigured.

The I² Composable Execution Model

OmniRoute implements sequential composition through the I² (input-to-input) model realized in open-sse/services/compression/bodyAdapter.ts. This architecture works as follows:

• bodyAdapter normalizes the request payload before the first engine
• Each engine receives plain text and outputs transformed plain text
• Output from engine n becomes input to engine n+1
• Final output is restored to response format after the last engine

This enables arbitrary chains like session-dedup → headroom → llmlingua where deduplication runs first, then context window management, then token-level compression.

The adapter abstraction means engines remain agnostic to their position in the pipeline—they operate on normalized strings and need no awareness of predecessor or successor engines.

Runtime Selection: CLI, API, and MCP Interfaces

OmniRoute exposes three control surfaces for engine selection:

CLI Control

The omniroute set compression-engine command in bin/cli/commands/compression.mjs handles activation with legacy alias normalization:

# Activate default "caveman/stacked" engine

omniroute set compression-engine stacked

# Configure a specific engine with JSON options

omniroute set compression-engine llmlingua --config '{"model":"gpt-4o-mini"}'

The CLI maps hybrid → stacked for backward compatibility and defaults to stacked when no plan exists.

HTTP API

PUT /api/settings/compression HTTP/1.1
Content-Type: application/json

{
  "engine": "session-dedup",
  "config": { "maxDuplicates": 5 }
}

MCP Tool

The setCompressionEngine tool in open-sse/mcp-server/tools/compressionTools.ts provides the same functionality over Model Context Protocol transport, returning verbatim content blocks for audit trails.

Storing and Executing Multi-Engine Plans

Persistent plans support the full I² composition. A typical plan stored in compression_detail looks like:

{
  "steps": [
    { "engine": "session-dedup", "config": {} },
    { "engine": "headroom",    "config": { "maxRows": 1000 } },
    { "engine": "llmlingua",  "config": { "model": "gpt-4o-mini" } }
  ]
}

Execution flow: request → session-dedup → headroom → llmlingua → response.

Each step's config object merges with its engine's default schema. Empty objects {} accept all defaults. Step order is significant—deduplication before token compression preserves semantic coherence that would be lost if reversed.

Key Source Files and Their Roles

File	Purpose
open-sse/services/compression/engines/registry.ts	Engine registration, lookup, enable/disable, config merging
open-sse/services/compression/strategySelector.ts	Pipeline assembly, ID validation, error accumulation
open-sse/services/compression/bodyAdapter.ts	Payload normalization for I² sequential execution
src/lib/db/compressionDetailNormalizers.ts	Plan persistence and database normalization
open-sse/mcp-server/tools/compressionTools.ts	MCP transport for engine control
bin/cli/commands/compression.mjs	CLI entry point with alias handling

Summary

• Registry pattern: 12+ engines self-register with standardized interfaces in registry.ts
• Deterministic selection: strategySelector.ts builds validated pipelines from database plans
• I² composition: Engines chain sequentially via bodyAdapter.ts with normalized text passing
• Runtime control: Enable/disable flags and config merging avoid redeployment
• Triple interface: CLI, HTTP API, and MCP tools provide equivalent control surfaces
• Fallback behavior: stacked (caveman) engine activates when no explicit plan exists

Frequently Asked Questions

What happens if an engine ID in the plan doesn't exist?

The strategy selector adds a validation error at the lookup stage (lines 948 and 1060 in strategySelector.ts) but continues processing other steps. The pipeline execution will fail with a comprehensive error report rather than a single missing-engine failure.

Can engines be reordered without restarting OmniRoute?

Yes. Since plans are stored in compression_detail and read at request time, updating the database and calling PUT /api/settings/compression or the MCP equivalent immediately changes execution order. No restart or redeployment is required.

How does the I² model handle binary or non-text data?

The bodyAdapter.ts normalizes all payloads to plain text before the first engine and restores format after the last. Engines operate exclusively on strings, so binary data must be encoded (typically base64) before entering the compression pipeline.

What's the difference between stacked and hybrid engine aliases?

Both resolve to the same "caveman" engine implementation. The hybrid alias exists for backward compatibility and is normalized to stacked in bin/cli/commands/compression.mjs. For new deployments, use stacked explicitly.

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