# How Headroom's ML Router Achieves 40-90% Image Compression Savings

> Discover how Headroom's ML router achieves 40-90% image compression savings by intelligently selecting techniques with MiniLM and SigLIP analysis for reduced token costs.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: deep-dive
- Published: 2026-06-20

---

**Headroom reduces image token costs by 40-90% through a three-stage pipeline that combines a trained MiniLM classifier with SigLIP vision analysis to dynamically select the optimal compression technique for each request.**

The open-source `chopratejas/headroom` repository implements an intelligent routing system that analyzes both the user's query and the image content to minimize token usage while preserving answer quality. By routing requests through technique-specific transformations, the system achieves significant cost savings without requiring manual image preprocessing.

## The Three-Stage Compression Pipeline

The ML router operates through distinct analysis phases that determine whether to aggressively compress, partially resize, or preserve image fidelity based on semantic requirements.

### Query Classification with MiniLM

At the core of the routing decision is a **trained MiniLM model** (`chopratejas/technique-router`) that predicts the appropriate compression strategy. The classifier evaluates the user's natural language query against four predefined techniques: `full_low` for generic questions, `preserve` for detail-critical requests, `crop` for region-specific queries, and `transcode` for text extraction scenarios.

The model and its tokenizer are lazily loaded through the shared `MLModelRegistry` to minimize memory overhead. As implemented in [[`headroom/image/trained_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/trained_router.py)](https://github.com/chopratejas/headroom/blob/main/headroom/image/trained_router.py#L89-L99), this registry ensures the router is instantiated only once and reused across requests, with the initial download incurring a one-time 2-3 second overhead.

### Image Property Analysis via SigLIP

When enabled, the system employs **SigLIP** (Sigmoid Loss for Language Image Pre-training) to extract semantic embeddings from the image. These embeddings are compared against textual prompts such as "an image with visible text" or "a complex scene" to generate similarity scores.

The scores pass through sigmoid activation functions to produce boolean-like `ImageSignals`: `has_text`, `is_document`, `is_complex`, and `has_small_details`. This analysis occurs in [[`headroom/image/trained_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/trained_router.py)](https://github.com/chopratejas/headroom/blob/main/headroom/image/trained_router.py#L71-L78), providing objective metadata about visual content that complements the query classification.

### Decision Logic and Technique Selection

The router synthesizes query predictions and image signals into a final `RouteDecision` containing the selected technique, confidence score, and human-readable reasoning. The logic in [[`headroom/image/trained_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/trained_router.py)](https://github.com/chopratejas/headroom/blob/main/headroom/image/trained_router.py#L334-L382) maps combinations to specific savings profiles:

- **`full_low`**: Selected for generic questions; yields approximately **87% token savings** by aggressively downsampling
- **`preserve`**: Chosen when fine details are essential; results in **0% savings** but maintains full resolution
- **`crop`**: Targets region-specific queries by resizing to relevant areas; achieves **50-90% savings** depending on crop ratio
- **`transcode`**: Converts images to OCR text when only textual content matters; delivers approximately **99% savings** by eliminating image tokens entirely

## Provider-Specific Implementation

The `ImageCompressor` class in [[`headroom/image/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/__init__.py)](https://github.com/chopratejas/headroom/blob/main/headroom/image/__init__.py) translates router decisions into provider-specific API parameters.

For **OpenAI** models, the system adds `detail="low"` to the `image_url` object, forcing the API to use a compressed 512px representation. **Anthropic** implementations resize images to 512px before base64 encoding. **Google Gemini** processing optimizes for tile-based vision models by resizing to 768px, which aligns with Gemini's native tile processing dimensions.

## Performance Characteristics

Subsequent requests after the initial model download demonstrate minimal latency overhead. The router executes in approximately **2ms on GPU** and **10ms on CPU**, making it suitable for real-time applications. Models remain cached locally via the `MLModelRegistry` defined in [[`headroom/models/ml_models.py`](https://github.com/chopratejas/headroom/blob/main/headroom/models/ml_models.py)](https://github.com/chopratejas/headroom/blob/main/headroom/models/ml_models.py), ensuring the MiniLM and SigLIP weights persist across sessions without re-download.

## Implementation Examples

### Direct API Usage

Integrate compression directly into Python applications using the `ImageCompressor` class:

```python
from headroom.image import ImageCompressor

compressor = ImageCompressor()  # Loads MiniLM + SigLIP router

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What animal is this?"},
            {
                "type": "image_url",
                "image_url": {"url": "data:image/jpeg;base64,..."}
            }
        ]
    }
]

compressed = compressor.compress(messages, provider="openai")
print(compressor.last_result.technique)  # → Technique.FULL_LOW

print(compressor.last_savings)          # → ~87.0 (% tokens saved)

```

### Zero-Code Proxy Deployment

Deploy Headroom as a transparent proxy to compress images without modifying application code:

```bash

# Terminal 1: Start the proxy with image optimization enabled

headroom proxy --port 8787

# Terminal 2: Point any OpenAI-compatible client to the proxy

ANTHROPIC_BASE_URL=http://localhost:8787 claude

```

The proxy respects the `x-headroom-bypass` header for opt-out scenarios, detected in [[`headroom/proxy/helpers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py)](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py).

## Summary

- Headroom's **ML router** combines MiniLM query classification with SigLIP image analysis to select from four compression techniques.
- The **`full_low`**, **`crop`**, and **`transcode`** techniques deliver **40-90% token reductions** (up to 99% for OCR) while **`preserve`** maintains full fidelity for detail-critical requests.
- Provider-specific optimizations in `ImageCompressor` automatically adjust parameters for OpenAI, Anthropic, and Google Gemini APIs.
- First requests incur a **2-3 second model download**, with subsequent routing completed in **2-10ms** depending on hardware acceleration.

## Frequently Asked Questions

### How does Headroom decide which compression technique to use?

Headroom's `TrainedRouter` analyzes both the text query and image content through separate neural pipelines. The MiniLM classifier evaluates the query intent, while SigLIP extracts visual features like text presence and scene complexity. These signals converge in the decision logic at lines 334-382 of [`trained_router.py`](https://github.com/chopratejas/headroom/blob/main/trained_router.py) to select between `full_low`, `preserve`, `crop`, or `transcode` techniques based on predicted token savings versus answer quality requirements.

### What is the performance impact of using the ML router?

The initial model loading requires approximately **2-3 seconds** to download the MiniLM and SigLIP weights from Hugging Face. Once cached locally through the `MLModelRegistry`, subsequent routing decisions execute in **2ms on GPU** or **10ms on CPU**, making the overhead negligible for most production workloads compared to the 40-90% token cost savings achieved.

### Can I disable image compression for specific requests?

Yes. The proxy implementation in [[`headroom/proxy/helpers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py)](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py) detects the `x-headroom-bypass` header, which instructs the system to skip compression and forward the original image unmodified. When using the Python API directly, you can also bypass the router by manually specifying technique parameters in the `compress()` method call.

### Which providers are supported for image compression?

Headroom currently implements provider-specific handling for **OpenAI**, **Anthropic**, and **Google Gemini**. OpenAI requests receive `detail="low"` parameters, Anthropic images resize to 512px, and Gemini optimizations target 768px for tile-based vision processing. The `ImageCompressor` class in [`headroom/image/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/__init__.py) normalizes these transformations behind a unified interface.