How to Integrate Headroom as a Python Library: Complete Implementation Guide

Headroom provides a drop‑in wrapper around OpenAI‑compatible or Anthropic‑compatible clients that automatically applies context‑optimizing transforms, cache‑alignment, and semantic caching before the request reaches the provider.

The chopratejas/headroom repository offers a lightweight optimization layer that intercepts LLM requests to reduce token usage and improve cache hit rates. You can integrate Headroom as a Python library by wrapping your existing client with HeadroomClient and continuing to use familiar API signatures like chat.completions.create. This guide walks through the exact implementation steps using the actual source architecture.

Prerequisites and Installation

Install the package via pip to get the core SDK with lazy‑loaded dependencies.

pip install headroom-sdk

The package uses lazy imports (implemented in headroom/__init__.py lines 71‑88), meaning heavy optional dependencies such as provider SDKs or semantic‑cache ML stacks are not loaded until actually invoked. This keeps startup times minimal while maintaining full functionality.

Core Integration Pattern

Integrating Headroom follows a three‑step pattern: create a provider abstraction, instantiate the client wrapper, and use standard API methods. The orchestration logic resides in headroom/client.py, where the HeadroomClient class coordinates parsing, optimization, and request forwarding.

Step 1: Create a Provider

Instantiate a provider object that handles token counting, context limits, and transport specifics. For OpenAI, use OpenAIProvider; for Anthropic, use AnthropicProvider. These classes are defined in headroom/providers/base.py and registered in headroom/providers/registry.py.

from headroom import OpenAIProvider

provider = OpenAIProvider()

Step 2: Instantiate HeadroomClient

Wrap your original LLM client with HeadroomClient, passing the provider and optional configuration. The default_mode parameter controls whether requests run through the optimization pipeline ("optimize") or passive auditing ("audit").

from headroom import HeadroomClient
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

Configuration options are managed through HeadroomConfig in headroom/config.py, allowing you to toggle specific transforms, cache settings, and storage backends.

Step 3: Use Standard API Signatures

Call chat.completions.create (OpenAI style) or messages.create (Anthropic style) exactly as you would with the native client. The façade objects ChatCompletions and Messages (lines 38‑84 in headroom/client.py) forward these calls to the internal _create method, which injects the optimization pipeline transparently.

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum computing basics."}],
)

Understanding the Optimization Pipeline

When default_mode="optimize" is active, every request flows through a sophisticated pipeline before hitting the provider API. The _create method (lines 91‑104 in headroom/client.py) builds a request ID, parses the message list, and executes the TransformPipeline.

Transform Execution

The TransformPipeline (defined in headroom/transforms/__init__.py) runs a configurable sequence of transforms:

• SmartCrusher (headroom/transforms/smart_crusher.py): The main compression engine that reduces token usage while preserving semantic meaning.
• CacheAligner (headroom/transforms/cache_aligner.py): Computes cache‑alignment scores and optionally inserts prefix‑aligning tokens to maximize cache key matches.
• SemanticCacheLayer (headroom/cache.py): Performs optional semantic‑cache lookup to retrieve similar recent responses.

The pipeline produces an optimized message list and a token count, which are then passed to the transport layer.

Caching and Request Dispatch

After transformation, the CacheOptimizer (also in headroom/cache.py) checks for cache hits and may short‑circuit the request with a cached response. If no cache hit occurs, the request dispatches via call_client_transport (lines 104‑119 in headroom/client.py), which uses the provider‑specific transport logic.

Finally, metrics persist to the storage backend (sqlite by default via headroom/storage.py), recording tokens before/after, transforms applied, and cache hits for later analysis.

Practical Implementation Examples

OpenAI Integration

This example demonstrates a complete OpenAI setup with optimization enabled:

from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

# Wrap the native client

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

# Standard API call with automatic optimization

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain the difference between RAM and VRAM."}],
)

print(response.choices[0].message.content)

Anthropic‑Style Integration

For Claude models, swap the provider and use the messages interface:

from headroom import HeadroomClient, AnthropicProvider
from anthropic import Anthropic

client = HeadroomClient(
    original_client=Anthropic(),
    provider=AnthropicProvider(),
    default_mode="optimize",
)

resp = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    messages=[{"role": "user", "content": "Write a short poem about clouds."}],
    max_tokens=256,
)

print(resp.content)

Simulating Optimizations

Use the simulate method to preview token savings without consuming API credits:

simulation = client.chat.completions.simulate(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarise the plot of *Inception* in 50 words."}],
)

print(f"Tokens before: {simulation.tokens_before}")
print(f"Tokens after: {simulation.tokens_after}")
print(f"Transforms applied: {simulation.transforms}")

The SimulationResult object reports projected efficiency gains based on the current transform configuration.

Accessing Session Statistics

Retrieve detailed metrics about your integration’s performance:

stats = client.get_stats()
print(f"Tokens saved this session: {stats['session']['tokens_saved_total']}")
print(f"Cache hits: {stats['session']['cache_hits']}")

Validating Setup

Verify that your configuration is correct before running production traffic:

validation = client.validate_setup()
if not validation["valid"]:
    print("Setup problems:", validation)
else:
    print("Headroom is ready to go!")

Summary

Integrating Headroom as a Python library requires minimal code changes while providing significant optimization benefits:

• Wrap existing clients with HeadroomClient and a provider abstraction (OpenAIProvider or AnthropicProvider) to enable automatic request optimization.
• The TransformPipeline in headroom/transforms/__init__.py executes SmartCrusher and CacheAligner transforms to reduce token usage and improve cache alignment.
• Use simulate() to preview token savings, and access session statistics via get_stats() to monitor efficiency gains.
• Lazy imports in headroom/__init__.py ensure fast startup times despite heavy optional dependencies.

Frequently Asked Questions

How does Headroom maintain compatibility with existing OpenAI client code?

Headroom exposes façade objects ChatCompletions and Messages that mirror the exact method signatures of the underlying providers. As implemented in headroom/client.py lines 38‑88, these objects forward calls to the internal _create method, which handles the optimization pipeline transparently before dispatching to call_client_transport in the provider layer.

What is the difference between "optimize" and "audit" modes?

Optimize mode runs the full TransformPipeline (SmartCrusher, CacheAligner, and semantic cache lookups) to reduce tokens and costs. Audit mode records metrics and passes requests through unmodified, allowing you to measure baseline usage before enabling optimizations. Set this via the default_mode parameter in HeadroomConfig (headroom/config.py).

Can I use Headroom without installing heavy ML dependencies for semantic caching?

Yes. The package uses lazy imports (lines 71‑88 in headroom/__init__.py), meaning the semantic cache layer and other heavy ML components are only imported when explicitly accessed. If you disable semantic caching in your HeadroomConfig, these dependencies never load, keeping your environment lightweight.

Where does Headroom store usage metrics and cache data?

By default, metrics persist to SQLite via the storage implementation in headroom/storage.py. You can configure alternative backends or disable persistence entirely through HeadroomConfig. The storage layer records RequestMetrics including tokens before/after, transform applications, cache hits, and request timing.

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