# How to Integrate Headroom with LangChain: Complete Implementation Guide

> Learn how to integrate Headroom with LangChain using our complete guide. This guide details how Headroom compresses tokens across chat models, retrievers, memory, and tools with full LangChain API compatibility.

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

---

**Headroom exposes a zero-intrusion LangChain integration layer in `headroom/integrations/langchain/` that compresses tokens across chat models, retrievers, memory, and tools while preserving full LangChain API compatibility.**

Headroom is an open-source token compression library that reduces LLM costs through reversible Content Compression and Reconstruction (CCR). According to the `chopratejas/headroom` source code, the library provides optional first-class bindings for LangChain that wrap existing components without requiring architectural changes to your existing pipelines.

## Core Integration Components

The LangChain integration lives under `headroom/integrations/langchain/` and implements LangChain's abstract base classes to ensure drop-in compatibility.

### HeadroomChatModel

The **`HeadroomChatModel`** class in [`headroom/integrations/langchain/chat_model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/chat_model.py) implements LangChain's `BaseChatModel` (or `ChatModel`) interface. It wraps any LangChain-compatible LLM and runs every request through Headroom’s compression pipeline before the request reaches the provider, returning a standard `ChatResponse` that existing LangChain clients expect.

```python
from langchain_openai import ChatOpenAI               # any LangChain‑compatible LLM

from headroom.integrations.langchain import HeadroomChatModel, StreamingMetricsTracker

# Original LangChain model

llm = ChatOpenAI(model="gpt-4o", streaming=True)

# Wrap it – now every request passes through Headroom’s compression pipeline

headroom_llm = HeadroomChatModel(llm)

# Use it just like a regular LangChain model

response = headroom_llm.invoke("Summarize the following code snippet.")
print(response.content)          # ← compressed output, original tokens restored on‑demand

```

### Streaming Token Metrics

The **`StreamingMetricsTracker`** and **`StreamingMetricsCallback`** classes in [`headroom/integrations/langchain/streaming.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/streaming.py) track output tokens, chunk count, and latency during streaming responses. They use Headroom’s provider-agnostic token counter (`OpenAIProvider.get_token_counter` by default) to deliver accurate statistics regardless of the underlying LLM vendor.

```python
from headroom.integrations.langchain import StreamingMetricsTracker

tracker = StreamingMetricsTracker(model="gpt-4o")
for chunk in headroom_llm.stream("Explain quantum entanglement"):
    tracker.add_chunk(chunk)          # collect content & timing

    print(chunk.content, end="", flush=True)

metrics = tracker.finish()
print("\nTokens emitted:", metrics.output_tokens)
print("Duration (ms):", metrics.duration_ms)

```

### Document Compression for RAG

The **`HeadroomDocumentCompressor`** in [`headroom/integrations/langchain/retriever.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/retriever.py) implements LangChain’s `BaseDocumentCompressor`. It scores retrieved documents with a BM25-style relevance metric and returns a compressed top-k set, making it ideal for use with `ContextualCompressionRetriever` in RAG pipelines.

```python
from langchain.retrievers import ContextualCompressionRetriever
from langchain_community.vectorstores import Chroma
from headroom.integrations.langchain import HeadroomDocumentCompressor

# Build a vectorstore retriever (k=50 for high recall)

vectorstore = Chroma.from_documents(docs, embeddings)
base_retriever = vectorstore.as_retriever(search_kwargs={"k": 50})

# Wrap the retriever with Headroom’s compressor (keep top‑10 relevant docs)

compressor = HeadroomDocumentCompressor(max_documents=10, min_relevance=0.3)
retriever = ContextualCompressionRetriever(
    base_compressor=compressor,
    base_retriever=base_retriever,
)

# Retrieve – you’ll get a compact, relevance‑scored set of documents

results = retriever.invoke("What are the safety considerations for deploying a large language model?")

```

### Compressed Memory and Tool Wrappers

For conversational agents, **`HeadroomMemory`** in [`headroom/integrations/langchain/memory.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/memory.py) implements LangChain’s `BaseMemory` interface. It automatically runs Headroom’s `compress` routine every time a new message is added, keeping conversation history small while remaining reversible via CCR.

The **`HeadroomToolWrapper`** in [`headroom/integrations/langchain/agents.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/agents.py) wraps LangChain `BaseTool` instances to compress tool outputs before they are fed back to the agent.

```python
from headroom.integrations.langchain import HeadroomMemory, HeadroomToolWrapper
from langchain.agents import AgentExecutor, Tool

# Your usual LangChain tool

search_tool = Tool(name="search", func=search_fn, description="Web search")

# Wrap the tool with Headroom compression

compressed_tool = HeadroomToolWrapper(search_tool)

# Create an agent with a compressed memory store

memory = HeadroomMemory()
agent = AgentExecutor(tools=[compressed_tool], memory=memory, llm=headroom_llm)

```

## Integration Design Patterns

All LangChain integration modules in `headroom/integrations/langchain/` follow three architectural principles:

- **Optional Import Guard**: Each module begins with a `try/except ImportError` block that sets `LANGCHAIN_AVAILABLE`. If LangChain is not installed, the code raises a clear `ImportError` with the hint `pip install headroom[langchain]`.
- **Provider-Agnostic Token Counting**: The integration delegates token counting to Headroom’s generic provider system (via [`headroom/integrations/langchain/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/providers.py)), which auto-detects the underlying LLM provider (OpenAI, Anthropic, Bedrock, etc.) using duck-typing.
- **Zero-Intrusion API**: Wrappers expose the exact LangChain abstract base classes (`BaseChatModel`, `BaseDocumentCompressor`, `BaseMemory`, `BaseTool`), meaning existing pipelines, agents, and LangGraph definitions run unchanged.

Additional helpers in [`headroom/integrations/langchain/langgraph.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/langgraph.py) and [`headroom/integrations/langchain/langsmith.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/langsmith.py) expose Headroom-wrapped models to LangGraph workflows and LangSmith tracing respectively.

## Summary

- Headroom provides **first-class LangChain bindings** under `headroom/integrations/langchain/` that are completely optional and only import when `LANGCHAIN_AVAILABLE` is detected.
- **`HeadroomChatModel`** wraps any LangChain LLM to compress prompts and responses transparently.
- **`HeadroomDocumentCompressor`** adds BM25-based relevance scoring to RAG retrievers via the `BaseDocumentCompressor` interface.
- **`HeadroomMemory`** and **`HeadroomToolWrapper`** enable compressed conversation history and tool outputs for agents.
- The integration uses **provider auto-detection** in [`providers.py`](https://github.com/chopratejas/headroom/blob/main/providers.py) to ensure accurate token counting across OpenAI, Anthropic, and other vendors without manual configuration.

## Frequently Asked Questions

### Does Headroom require rewriting existing LangChain code?

No. Headroom’s LangChain integration follows a **zero-intrusion pattern** by implementing LangChain’s standard abstract base classes. You wrap existing models or retrievers with Headroom classes, but the rest of your pipeline—from agents to chains—remains unchanged.

### Which LangChain components does Headroom support?

According to the `chopratejas/headroom` source, Headroom supports **chat models** (`HeadroomChatModel`), **retrievers** (`HeadroomDocumentCompressor`), **memory** (`HeadroomMemory`), and **tools** (`HeadroomToolWrapper`). It also includes helpers for **LangGraph** and **LangSmith** integration.

### How does Headroom handle token counting across different LLM providers?

The [`headroom/integrations/langchain/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/providers.py) module auto-detects the underlying provider using duck-typing and returns a matching Headroom Provider object. This allows `StreamingMetricsTracker` and other components to use the correct tokenizer for OpenAI, Anthropic, Bedrock, or other supported vendors.

### Can I use Headroom with LangChain if I don't have the library installed initially?

Yes. The integration is optional. If you attempt to import from `headroom.integrations.langchain` without LangChain installed, the module raises an `ImportError` with instructions to run `pip install headroom[langchain]`. The rest of Headroom functions normally without LangChain present.