How to Use OmniRoute Compression Studio with Pluggable Engines: A Complete Guide

TLDR; OmniRoute’s compression subsystem uses a pluggable engine architecture that lets you chain, configure, and fine-tune compression strategies through a REST API, CLI, or visual Compression Studio interface, all validated by central Zod schemas.

OmniRoute is an open-source routing platform that includes a sophisticated compression subsystem designed to optimize token usage across LLM interactions. The OmniRoute Compression Studio provides a visual interface and programmatic APIs for configuring pluggable compression engines that can be stacked, customized, and triggered automatically based on token thresholds.

Understanding the Pluggable Architecture

The compression system is built around a runtime engine catalog and strict schema validation. Every engine is defined in the STACKED_PIPELINE_ENGINE_INTENSITIES map located in src/lib/db/compression.ts, which serves as the source of truth for available engines and their supported intensity levels. This catalog drives both the UI dropdowns in the Compression Studio and the API validation layer.

The central validation logic lives in src/shared/validation/compressionConfigSchemas.ts. Here, the compressionSettingsUpdateSchema Zod object defines the complete configuration contract, including the stackedPipeline array that allows you to chain multiple engines sequentially. Each pipeline step specifies an engine identifier, optional intensity level, and engine-specific config parameters.

Configuring Engines via the REST API

The HTTP API exposes compression settings through the /api/settings/compression endpoint. You can retrieve current settings with a GET request or update the entire configuration using PUT with a payload that conforms to the compressionSettingsUpdateSchema.

To enable a stacked pipeline with multiple engines:

curl -X PUT https://localhost:20128/api/settings/compression \
  -H "Authorization: Bearer $OMNIRoute_JWT" \
  -H "Content-Type: application/json" \
  -d '{
        "enabled": true,
        "defaultMode": "standard",
        "stackedPipeline": [
          { "engine": "caveman", "intensity": "lite", "config": { "compressRoles": ["assistant"] } },
          { "engine": "rtk",      "intensity": "standard" }
        ],
        "exclusions": ["^gpt-4.*$", "^anthropic/.*$"]
      }'

The stackedPipeline array processes engines in order, passing the output of one engine as input to the next. The exclusions array accepts regex patterns to bypass compression for specific model patterns.

Using the CLI for Compression Management

OmniRoute provides a dedicated CLI command at bin/cli/commands/compression.mjs for inspecting and modifying compression settings without writing HTTP clients.

To view current configuration:

omniroute compression get

This command internally executes a GET request to /api/settings/compression and formats the JSON response for terminal readability.

To set a global engine with specific intensity:

omniroute compression set --engine ultra --intensity ultra --enabled true

The CLI parses arguments, constructs a valid compressionSettingsUpdateSchema payload, and sends the PUT request automatically.

Building Stacked Pipeline Configurations

The stackedPipeline field in your configuration enables sophisticated processing chains. Each step in the array is validated against the stackedPipelineStepSchema, which ensures the engine value exists in the ENGINE_CATALOG and that the requested intensity is supported for that engine.

Key configuration fields include:

• autoTriggerTokens: Automatically switches from defaultMode to autoTriggerMode when requests exceed the specified token count
• comboOverrides: Per-combination engine selections stored in the compressionCombos table that override global defaults
• Per-engine blocks: Typed configuration objects like cavemanConfig, aggressiveConfig, or ultraConfig that expose engine-specific knobs

The database layer in src/lib/db/compression.ts persists these settings to SQLite, while compressionRunTelemetry.ts logs execution metrics for each compression run.

Programmatic Integration with Node.js

For custom tooling, interact directly with the compression API using standard HTTP clients:

import fetch from 'node-fetch';

const resp = await fetch('http://localhost:20128/api/settings/compression', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.OMNIRoute_JWT}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    defaultMode: 'lite',
    stackedPipeline: [{ engine: 'lite' }],
  }),
});

const data = await resp.json();
console.log('Compression updated:', data);

Extending the Engine Set

To add a custom compression engine to OmniRoute:

1. Define the schema: Add a new Zod schema (e.g., myEngineConfigSchema) in src/shared/validation/compressionConfigSchemas.ts
2. Register in catalog: Update STACKED_PIPELINE_ENGINE_INTENSITIES in src/lib/db/compression.ts with the engine ID and supported intensities
3. Update persistence: Modify the DB normalizer in src/lib/db/compression.ts to handle the new engine in migrations
4. Implement runtime logic: Create a handler under open-sse/handlers/chatCore/ if the engine requires request-time processing
5. Add UI support: Extend the Compression Studio in src/app/(dashboard)/dashboard/compression/studio/compressionFlowModel.ts if custom UI components are needed
6. Verify with tests: Add unit tests ensuring GET→PUT round-tripping works correctly, following patterns in compression-engines-map-migration.test.ts

The MCP server integration in open-sse/mcp-server/tools/compressionTools.ts automatically exposes new engines to remote debugging tools once registered.

Summary

• OmniRoute uses Zod schemas in compressionConfigSchemas.ts to validate all engine configurations type-safely
• The engine catalog in src/lib/db/compression.ts maintains the canonical list of available engines and intensity levels
• Configure engines via REST API (/api/settings/compression), CLI (omniroute compression), or the Compression Studio UI
• Use stacked pipelines to chain multiple engines, with output from each feeding into the next
• Auto-trigger tokens enable automatic mode switching based on request size
• Extend the system by adding schemas to the validation layer and registering engines in the database catalog

Frequently Asked Questions

How do I exclude specific models from compression?

Use the exclusions array in your compression settings payload. This field accepts JavaScript regex patterns as strings. For example, ["^gpt-4.*$", "^anthropic/.*$"] prevents compression on any GPT-4 or Anthropic models. The patterns are evaluated at runtime in open-sse/handlers/chatCore/compressionSettings.ts.

What is the difference between defaultMode and stackedPipeline?

The defaultMode specifies a single engine to use when stackedPipeline is empty or when auto-trigger conditions aren't met. The stackedPipeline array overrides this behavior by allowing you to chain multiple engines sequentially. If both are configured, stackedPipeline takes precedence for processing flow while defaultMode serves as a fallback label.

Can I use the Compression Studio UI and API simultaneously?

Yes. The Compression Studio (src/app/(dashboard)/dashboard/compression/studio/compressionFlowModel.ts) operates on the same underlying database tables and API endpoints as the REST interface. Changes made through the drag-and-drop UI immediately persist via the same PUT requests to /api/settings/compression, ensuring consistency across CLI, UI, and programmatic access.

How does the MCP server expose compression settings?

The MCP server loads compression configurations through open-sse/mcp-server/tools/compressionTools.ts, which interfaces with the same SQLite persistence layer used by the HTTP API. This allows remote debugging tools and AI assistants to read current engine configurations and trigger compression runs without direct database access.

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