OmniRoute Compression Engines: A Complete Guide to Available Engines and Stacking Strategies

OmniRoute provides four built-in compression engines (rtk, caveman, lite, and headroom) that can be used individually or stacked in configurable pipelines to reduce token usage before prompts reach language models.

The OmniRoute repository (diegosouzapw/OmniRoute) ships with a Prompt-Compression subsystem designed to rewrite user prompts before they are transmitted to upstream language models. This system centers on a catalog of interchangeable compression engines and a flexible pipeline model that determines how those engines combine. Understanding these engines and their stacking behavior helps developers optimize token budgets without sacrificing answer quality.

Available Compression Engines in OmniRoute

According to the source code in open-sse/services/compression/engineCatalog.ts, OmniRoute defines four distinct engines through the ENGINE_IDS enum. Each engine targets different trade-offs between compression ratio and output fidelity.

Engine ID	Strategy	Quality Impact	Best For
rtk	Lossless token reduction via common-prefix sharing and whitespace compaction	None	Safe default when token limits are tight
caveman	Aggressive heuristic pruning of "less-important" tokens	Lossy	Maximum reduction when some fidelity loss is acceptable
lite	Rule-based removal of obvious redundancy (duplicate stop words, etc.)	Minimal	Moderate reduction without full lossy compression
headroom	Tail-trimming based on remaining token budget	Context-dependent	Automatic guard-rail for strict provider caps

Engine Implementation Details

New engines can be added by extending the ENGINE_IDS enum in engineCatalog.ts and providing a concrete implementation in open-sse/services/compression/engines/. The existing four engines cover the majority of production use cases.

How OmniRoute Compression Engines Stack

The compression system operates in two distinct modes controlled by user settings in compressionSettings.ts:

• Heuristic (single-engine) mode: One engine processes the prompt
• Stacked mode: Multiple engines execute sequentially as a pipeline

Pipeline Structure and Execution

In stacked mode, the pipeline is stored as an ordered array of { engine: string } objects defined in compressionPipelineModel.ts. Each engine receives the output of the previous engine, creating compositional token reduction.

A typical three-step pipeline configuration:

[
  { "engine": "lite" },
  { "engine": "caveman" },
  { "engine": "rtk" }
]

Execution flow: lite → caveman → rtk

Token savings accumulate at each stage. The final token count reflects the cumulative effect of all transformations. The UI renders this as a flow diagram (see docs/diagrams/compression-pipeline.svg) where users can reorder, add, or remove steps.

The pipeline graph structure follows a verified formula: 1 input node + N engine nodes + 1 output node. Tests in compressionFlowModel.test.ts and compressionPipelineModel.test.ts validate this graph construction.

Configuring Engine Stacks in OmniRoute

Via the React UI Component

The CompressionPanel component (open-sse/components/compression/compressionPanel) provides interactive pipeline editing:

import { ENGINE_IDS } from "@/open-sse/services/compression/engineCatalog";
import { CompressionPanel } from "@/open-sse/components/compression/compressionPanel";

<CompressionPanel
  initialPipeline={[
    { engine: ENGINE_IDS.rtk },
    { engine: ENGINE_IDS.caveman, enabled: true, intensity: "full" },
  ]}
/>

The panel renders validation feedback through test suites in compressionPanel.test.tsx.

Programmatic Pipeline Construction

For server-side or automated configurations, use the pipeline builder:

import { buildCompressionPipeline } from "@/open-sse/services/compression/pipelineBuilder";

const pipeline = buildCompressionPipeline([
  { engine: "lite" },
  { engine: "caveman", intensity: "aggressive" },
  { engine: "rtk" },
]);

await handleChatCore(request, { compressionPipeline: pipeline });

The builder validates engine IDs against the catalog and normalizes intensity parameters per compressionPipelineModel.ts.

CLI Configuration

Compression settings persist in SQLite and can be manipulated via CLI:

# View current configuration

omniroute compression get-settings

# Update pipeline directly

omniroute compression set-pipeline '{"pipeline":[{"engine":"rtk"},{"engine":"caveman"}]}'

Implementation resides in bin/cli/commands/compression.mjs.

Automatic Stack Selection with Combo Predicates

The system supports dynamic pipeline switching through compression combo predicates defined in compressionComboPredicates.ts. These predicates automatically adjust the active stack based on routing context.

Common automatic triggers include:

• Provider token limits: Automatically enable headroom when approaching strict caps
• Model-specific rules: Switch to rtk-only for models with known sensitivity
• Request characteristics: Apply caveman for long context windows where tail loss is acceptable

The default configuration uses "stacked" mode with a single rtk engine, providing lossless baseline compression while preserving user flexibility to extend the stack.

Database Persistence and API Layer

Compression configurations survive application restarts through SQLite migrations:

• 102_compression_engines_map.sql: Engine catalog mapping
• 043_default_compression_combo_pipeline.sql: Default pipeline storage

The REST API under /api/compression/* exposes CRUD operations for engine settings, with comprehensive test coverage in api/compression-engines-route.test.ts.

Performance Considerations for Stacked Compression

When stacking OmniRoute compression engines, consider these factors:

• Order matters: Place lossless engines (rtk, lite) before aggressive ones (caveman) to preserve maximum information for heuristic decisions
• Intensity cascading: Later engines operate on already-reduced text, amplifying both savings and potential quality degradation
• Latency: Each engine adds processing time; monitor handleChatCore execution when using deep stacks

Summary

• OmniRoute provides four compression engines (rtk, caveman, lite, headroom) with distinct loss/performance trade-offs
• Engines stack sequentially in configurable pipelines where each stage receives the previous stage's output
• The default configuration uses single-engine rtk mode for safe, lossless compression
• Combo predicates enable automatic pipeline switching based on routing context and provider constraints
• All configurations persist through SQLite migrations and expose CLI and API interfaces

Frequently Asked Questions

What is the safest OmniRoute compression engine for production use?

The rtk engine is explicitly designed as the safe default. It performs lossless token reduction through common-prefix sharing and whitespace compaction, meaning it never degrades answer quality. This is why rtk occupies the default position in fresh installations.

Can I create custom compression engines in OmniRoute?

Yes. Extend the ENGINE_IDS enum in engineCatalog.ts and implement your engine in open-sse/services/compression/engines/. The pipeline builder automatically recognizes new enum values, and the UI will display them in the CompressionPanel without additional frontend changes.

How does the headroom engine differ from other OmniRoute compressors?

Unlike content-aware engines (rtk, caveman, lite), headroom is a budget-aware trimmer. It evaluates the remaining token allowance for a specific provider and truncates prompt tails to fit. The headroom engine is primarily invoked by the auto-combo routing layer rather than user pipelines, serving as a last-resort guard against hard token limits.

What happens if I disable all engines in a stacked pipeline?

OmniRoute treats an empty pipeline as a pass-through: prompts transmit unmodified to upstream models. The compressionSettings.ts model permits this configuration, though the UI may display a warning that no compression is active.

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