How OmniRoute's Caveman Compression Engine Works: Rule-Based Token Reduction Explained

OmniRoute's Caveman compression engine reduces token counts in chat-completion payloads using a deterministic, rule-based pipeline that preserves code blocks and URLs while applying intensity-configured transformations to minimize upstream API costs.

The OmniRoute repository implements an intelligent compression layer designed to minimize token usage in LLM requests without sacrificing semantic meaning. Located in the open-sse/services/compression package, the Caveman engine processes each message through a sophisticated pipeline of extraction, transformation, and validation before forwarding requests to upstream providers.

Entry Point and Early Exit Conditions

The compression process begins at cavemanCompress in [open-sse/services/compression/caveman.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/caveman.ts) (line 445). This function receives a ChatRequestBody and optional CavemanConfig, then implements several guard clauses to avoid unnecessary processing:

• Disabled state: Returns immediately if compression is disabled in configuration
• Empty messages: Aborts when the request contains no messages
• Length thresholds: Skips messages below minimum token counts
• Role exclusions: Bypasses compression for system messages or other excluded roles

For eligible messages, the engine extracts text content—handling both string and array part formats—and measures the original token count using estimateCompressionTokens before any modifications occur.

Preservation Handling and Protected Blocks

Before applying transformations, the engine identifies protected structures that must remain intact. The extractPreservedBlocks routine, imported from [open-sse/services/compression/preservation.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/preservation.ts), scans for:

• Code fences (Markdown blocks)
• URLs and URI references
• Environment variable references
• Other patterns matching preservePatterns configuration

These spans are extracted from the extractedText and stored securely, leaving a clean working surface for rule processing. After transformations complete, restorePreservedBlocks reinserts the original content at the correct positions, ensuring that technical content remains unaltered.

Language Detection and Rule Selection

When autoDetectLanguage is enabled in the configuration, the engine leverages [open-sse/services/compression/languageDetector.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/languageDetector.ts) to identify the message language. This detection determines which localized rule pack to load; otherwise, the system defaults to English rules.

Rules are fetched via getRulesForContext in [open-sse/services/compression/cavemanRules.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/cavemanRules.ts) (line 94). Each rule (CavemanRule) contains:

• Pattern: A regex defining what to match
• Replacement: A string or function for substitution
• Category: Classification such as filler, structural, or dedup
• MinIntensity: Activation threshold (lite, full, or ultra)
• Context: Applicable roles (user, assistant, or all)

The intensity parameter acts as a filter: lite applies only the most conservative rules, full enables aggressive compression, and ultra activates maximum token reduction.

Rule Application and Text Transformation

The core transformation logic resides in applyRulesToText within [caveman.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/caveman.ts) (line 175). This function iterates through the selected rule set sequentially:

1. Pre-validation: shouldAttemptRule checks quick-keyword heuristics (e.g., article removal only proceeds if "a", "an", or "the" appear in the text)
2. Execution: If the replacement is a function, it receives the regex match object; otherwise, standard string replacement occurs
3. Tracking: Applied rule names are collected into the rulesApplied array for statistics generation

Rules execute in a specific order to prevent conflicts, with structural modifications typically preceding semantic substitutions.

Post-Processing, Validation, and Statistics

After rule application, the text passes through whitespace normalization helpers defined later in the same file:

• collapseHorizontalWhitespaceRuns: Removes excessive spaces
• removeHorizontalWhitespaceBeforePunctuation: Fixes spacing around punctuation
• collapseRepeatedSentencePunctuation: Normalizes duplicated punctuation marks

The validateCompression function then compares the compressed output against the original. If validation detects corruption or excessive meaning loss, the engine triggers a fallback, returning the uncompressed text and setting fallbackApplied: true in the statistics.

Finally, createCavemanStats (lines 995-1015) generates a CompressionStats object containing:

• Original and compressed token counts with percentage savings
• techniquesUsed: Array of applied categories
• rulesApplied: Specific rule identifiers
• preservedBlockCount: Number of protected blocks handled
• validationWarnings and errors: Any quality issues detected

Configuration and Usage Examples

Basic compression with default settings:

import { cavemanCompress } from "@omniroute/open-sse/services/compression/caveman";

const requestBody = {
  messages: [
    { role: "user", content: "Please, can you explain why we need to make sure to initialize the database?" },
  ],
};

const result = cavemanCompress(requestBody);
// result.body contains the compressed message
// result.stats contains token savings data

Custom configuration with intensity control and rule exclusions:

import { cavemanCompress } from "@omniroute/open-sse/services/compression/caveman";

const customConfig = {
  enabled: true,
  intensity: "lite",
  skipRules: ["passive_voice"],
  preservePatterns: [ /```[\s\S]*?```/g ], // Protect Markdown code blocks
};

const result = cavemanCompress(requestBody, customConfig);

Inspecting compression results:

console.log(result.stats.techniquesUsed);   // ["caveman-rules"]
console.log(result.stats.rulesApplied);     // ["redundant_phrasing", "pleasantries"]
console.log(result.compressed);             // true if transformation succeeded

Key Source Files and Implementation Details

File	Purpose	Location
open-sse/services/compression/caveman.ts	Main pipeline implementation containing cavemanCompress, applyRulesToText, and cleanup helpers	[caveman.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/caveman.ts)
open-sse/services/compression/cavemanRules.ts	Rule definitions and getRulesForContext selector	[cavemanRules.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/cavemanRules.ts)
open-sse/services/compression/preservation.ts	Protected block extraction and restoration logic	[preservation.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/preservation.ts)
open-sse/services/compression/languageDetector.ts	Automatic language detection for localized rule packs	[languageDetector.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/languageDetector.ts)
open-sse/services/compression/strategySelector.ts	Chooses Caveman or alternative compression modes per request	[strategySelector.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/strategySelector.ts)
open-sse/services/compression/engines/cavemanAdapter.ts	Adapter interface between the generic compression framework and Caveman engine	[cavemanAdapter.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engines/cavemanAdapter.ts)

Summary

• OmniRoute's Caveman engine operates through a deterministic rule-based pipeline defined in open-sse/services/compression/caveman.ts
• Protected block extraction ensures code, URLs, and technical content remain intact during compression
• The system supports three intensity levels (lite, full, ultra) configurable per request via CavemanConfig
• Validation safeguards automatically revert to uncompressed text if transformations corrupt meaning or structure
• Comprehensive statistics generation tracks token savings, applied rules, and preservation metrics for monitoring and debugging

Frequently Asked Questions

What intensity levels does the Caveman compression engine support?

The Caveman engine supports three distinct intensity levels configured via the intensity parameter in CavemanConfig. Lite applies only conservative rules safe for technical discussions, full enables aggressive compression including filler word removal, and ultra activates maximum token reduction including aggressive structural simplifications. Each rule definition specifies a minIntensity threshold determining when it activates.

How does the engine prevent corruption of code blocks and URLs?

Before any rules execute, the extractPreservedBlocks function in preservation.ts identifies and extracts code fences, URLs, and environment variables matching configured patterns. These blocks are stored separately while the remaining text undergoes transformation. The restorePreservedBlocks function reinserts the original content after processing, ensuring zero modification to protected technical content.

What happens if the compression validation fails?

If validateCompression detects that the transformed text fails quality checks—such as excessive length reduction or semantic corruption—the engine immediately falls back to the original uncompressed message. The CompressionStats object records fallbackApplied: true and includes any validation warnings or errors, allowing downstream systems to monitor compression quality and adjust intensity settings accordingly.

Can specific rules be disabled while keeping others active?

Yes, the CavemanConfig interface accepts a skipRules array containing rule identifiers to exclude from processing. For example, passing skipRules: ["passive_voice"] prevents the passive voice transformation while allowing all other applicable rules to execute. This granular control enables fine-tuning compression behavior for specific content types or user preferences.

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