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

> Discover how OmniRoute's compression engine selection works, assembling pipelines from 12+ composable engines using a registry-based strategy selector for efficient data compression.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash

# 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

```http
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```json
{
  "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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engines/registry.ts) | Engine registration, lookup, enable/disable, config merging |
| [`open-sse/services/compression/strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/strategySelector.ts) | Pipeline assembly, ID validation, error accumulation |
| [`open-sse/services/compression/bodyAdapter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/bodyAdapter.ts) | Payload normalization for I² sequential execution |
| [`src/lib/db/compressionDetailNormalizers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compressionDetailNormalizers.ts) | Plan persistence and database normalization |
| [`open-sse/mcp-server/tools/compressionTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/registry.ts)
- **Deterministic selection**: [`strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/strategySelector.ts) builds validated pipelines from database plans
- **I² composition**: Engines chain sequentially via [`bodyAdapter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.