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

> Learn to integrate Headroom as a Python library. This guide details how Headroom optimizes OpenAI and Anthropic client requests with context transforms and semantic caching for better performance.

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

---

**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.

```bash
pip install headroom-sdk

```

The package uses **lazy imports** (implemented in [`headroom/__init__.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/base.py) and registered in [`headroom/providers/registry.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/registry.py).

```python
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"`).

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/client.py)) forward these calls to the internal `_create` method, which injects the optimization pipeline transparently.

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/__init__.py)) runs a configurable sequence of transforms:

*   **SmartCrusher** ([`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)): The main compression engine that reduces token usage while preserving semantic meaning.
*   **CacheAligner** ([`headroom/transforms/cache_aligner.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/cache_aligner.py)): Computes cache‑alignment scores and optionally inserts prefix‑aligning tokens to maximize cache key matches.
*   **SemanticCacheLayer** ([`headroom/cache.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/client.py)), which uses the provider‑specific transport logic.

Finally, metrics persist to the storage backend (`sqlite` by default via [`headroom/storage.py`](https://github.com/chopratejas/headroom/blob/main/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:

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

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

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

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

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.