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

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#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#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#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) 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), 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:

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:

# 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).

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 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) 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 normalizes these transformations behind a unified interface.

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