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

> Discover how OmniRoute's Caveman compression engine uses rule-based token reduction to cut API costs. Learn about its deterministic pipeline that preserves code and URLs.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: internals
- Published: 2026-07-09

---

**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)](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)](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)](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)](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/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:

```typescript
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:

```typescript
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**:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/caveman.ts) | Main pipeline implementation containing `cavemanCompress`, `applyRulesToText`, and cleanup helpers | [[`caveman.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/caveman.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/caveman.ts) |
| [`open-sse/services/compression/cavemanRules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/cavemanRules.ts) | Rule definitions and `getRulesForContext` selector | [[`cavemanRules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cavemanRules.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/cavemanRules.ts) |
| [`open-sse/services/compression/preservation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/preservation.ts) | Protected block extraction and restoration logic | [[`preservation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/preservation.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/preservation.ts) |
| [`open-sse/services/compression/languageDetector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/languageDetector.ts) | Automatic language detection for localized rule packs | [[`languageDetector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/languageDetector.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/languageDetector.ts) |
| [`open-sse/services/compression/strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/strategySelector.ts) | Chooses Caveman or alternative compression modes per request | [[`strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/strategySelector.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/strategySelector.ts) |
| [`open-sse/services/compression/engines/cavemanAdapter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.