# Headroom Transform Pipeline Sequence: How LLM Requests Are Processed

> Discover the Headroom Transform Pipeline sequence for LLM requests. Learn how Tool-Result Interceptors, Cache Aligners, and Content Routers optimize processing for efficient content compression.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-15

---

**The Headroom Transform Pipeline processes every LLM request through a deterministic sequence consisting of an optional Tool-Result Interceptor, a Cache Aligner, and a Content Router that dispatches to specialized compressors based on detected content types.**

The `chopratejas/headroom` repository implements a sophisticated request optimization system for Large Language Models through its transform pipeline architecture. Understanding the **Headroom Transform Pipeline sequence** is essential for developers integrating the SDK, as it determines exactly how prompts are intercepted, aligned, compressed, and routed before reaching the model provider.

## Default Headroom Transform Pipeline Sequence

When the SDK is initialized without custom transforms, `TransformPipeline._build_default_transforms()` in [`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py) constructs the pipeline automatically. The default sequence follows this strict order:

### Step 0 – Tool-Result Interceptor (Optional)

The **Tool-Result Interceptor** executes first when enabled via `HeadroomConfig.intercept_tool_results` or the `HEADROOM_INTERCEPT_ENABLED` environment variable. This transform runs first-stage "read-outline" logic and other tool-result interceptors that shrink the payload before any compression occurs.

### Step 1 – Cache Aligner

The **Cache Aligner** detects volatile data patterns—including UUIDs, timestamps, JWTs, and hex hashes—within the system-prompt prefix. Unlike mutating transforms, it emits warnings without modifying the prompt content, stabilizing the cache-key prefix to ensure repeated calls hit identical cache entries.

### Step 2 – Content Router and Compressor Dispatch

The **Content Router** serves as the pipeline's core processing engine. It analyzes the (potentially intercepted) content, determines the appropriate compression strategy, and re-assembles the final message list. The router dispatches to content-aware compressors based on detected data types:

- **SmartCrusher** – Compresses JSON arrays efficiently
- **KompressCompressor** – Applies ML-based plain-text compression
- **CodeAwareCompressor** – Performs AST-preserving code compression
- **LogCompressor** – Handles build and test log optimization
- **SearchCompressor** – Compresses search-result output
- **HTMLExtractor** – Extracts useful text from HTML documents

## Pipeline Orchestration and Error Handling

All transforms inherit from the abstract `Transform` class defined in [`headroom/transforms/base.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/base.py) and implement an `apply()` method returning a `TransformResult`. The pipeline orchestrates execution by passing each transform's output as the next transform's input, while aggregating token counts, execution timing, markers, and warning messages.

If any transform raises an exception, the **circuit-breaker** mechanism activates according to the `HEADROOM_PIPELINE_BREAKER_THRESHOLD` and `HEADROOM_PIPELINE_BREAKER_COOLDOWN_S` environment variables. When triggered, the circuit opens and subsequent requests pass through untouched to prevent cascading failures.

## Implementing the Headroom Transform Pipeline in Code

The following examples demonstrate how to work with the pipeline in production environments.

### Using the Default Pipeline

```python
from headroom import HeadroomClient, HeadroomConfig

client = HeadroomClient(
    api_key="your-api-key",
    config=HeadroomConfig(),  # Uses default pipeline sequence

)

messages = [
    {"role": "user", "content": "Explain the quicksort algorithm in detail."}
]

# Internally constructs TransformPipeline and applies transforms

response = client.chat_completion(messages, model="gpt-4")
print(response["choices"][0]["message"]["content"])

```

### Building a Custom Pipeline

```python
from headroom.transforms import CacheAligner, ContentRouter, TransformPipeline
from headroom.config import HeadroomConfig, CacheAlignerConfig

cfg = HeadroomConfig(
    intercept_tool_results=False,
    cache_aligner=CacheAlignerConfig(enabled=True)
)

pipeline = TransformPipeline(
    config=cfg,
    transforms=[
        CacheAligner(cfg.cache_aligner),
        ContentRouter(),  # Maintains internal compressor dispatch

    ]
)

result = pipeline.apply(
    messages=[{"role": "user", "content": "Large text payload here..."}],
    model="gpt-3.5-turbo",
    model_limit=8192
)

print(f"Tokens before: {result.tokens_before}")
print(f"Tokens after: {result.tokens_after}")
print(f"Applied transforms: {result.transforms_applied}")

```

### Inspecting Compressor Selection

```python
from headroom.transforms.content_router import ContentRouter

router = ContentRouter()
result = router.compress(
    content='[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
)

print(f"Strategy used: {result.strategy_used}")  # Outputs: "smart_crusher"

print(f"Routing log: {result.routing_log}")

```

## Key Source Files in the Transform Pipeline

- [`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py) – Defines `TransformPipeline` and `_build_default_transforms()` orchestration logic
- [`headroom/transforms/base.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/base.py) – Abstract `Transform` base class with `apply()` interface
- [`headroom/transforms/cache_aligner.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/cache_aligner.py) – Volatile token detection and cache stabilization
- [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) – Content analysis and compressor dispatch logic
- [`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py) – JSON array compression implementation
- [`headroom/transforms/kompress_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/kompress_compressor.py) – ML-based text compression
- [`headroom/transforms/code_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/code_compressor.py) – AST-aware code compression
- [`headroom/transforms/log_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/log_compressor.py) – Build and test log optimization
- [`headroom/transforms/search_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/search_compressor.py) – Search result compression
- [`headroom/transforms/html_extractor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/html_extractor.py) – HTML-to-text extraction

## Summary

- The **Headroom Transform Pipeline sequence** follows a deterministic order: optional Tool-Result Interceptor, Cache Aligner, then Content Router
- `TransformPipeline._build_default_transforms()` in [`pipeline.py`](https://github.com/chopratejas/headroom/blob/main/pipeline.py) constructs this sequence automatically when using default configurations
- The **Cache Aligner** stabilizes cache keys by detecting volatile patterns without mutating prompt content
- The **Content Router** dispatches to six specialized compressors including `SmartCrusher`, `KompressCompressor`, and `CodeAwareCompressor` based on content type detection
- Circuit-breaker protection prevents cascading failures when transforms encounter errors

## Frequently Asked Questions

### What is the default sequence of the Headroom Transform Pipeline?

The default sequence begins with an optional **Tool-Result Interceptor** (when enabled via `HEADROOM_INTERCEPT_ENABLED`), followed by the **Cache Aligner**, and finally the **Content Router** which delegates to appropriate compressors. This order is hardcoded in `TransformPipeline._build_default_transforms()` within [`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py).

### How does the Cache Aligner improve caching without changing prompts?

The **Cache Aligner** scans the system-prompt prefix for volatile tokens like UUIDs, timestamps, and JWTs, emitting warnings when detected. By identifying these unstable elements, it ensures the cache-key generation ignores variable components, allowing identical logical prompts to hit the same cache entries despite dynamic values.

### What content types can the Content Router compress?

The **Content Router** in [`content_router.py`](https://github.com/chopratejas/headroom/blob/main/content_router.py) can invoke six specialized compressors: **SmartCrusher** for JSON arrays, **KompressCompressor** for ML-based plain-text, **CodeAwareCompressor** for AST-preserving code, **LogCompressor** for build logs, **SearchCompressor** for search results, and **HTMLExtractor** for HTML documents.

### How does the pipeline handle transform failures?

The pipeline implements circuit-breaker logic controlled by `HEADROOM_PIPELINE_BREAKER_THRESHOLD` and `HEADROOM_PIPELINE_BREAKER_COOLDOWN_S` environment variables. When transform exceptions exceed the threshold, the circuit opens and subsequent requests bypass all transforms to prevent service degradation while maintaining availability.