# How Headroom Integrates with LangChain: Complete API Guide

> Learn how Headroom integrates with LangChain via an optional integration layer. Automatically compress prompts, responses, and more while maintaining full API compatibility.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: api-reference
- Published: 2026-06-14

---

**Headroom integrates with LangChain through a first-class, optional integration layer located in `headroom/integrations/langchain/` that wraps standard LangChain components to automatically compress prompts, responses, documents, and tool outputs while maintaining full API compatibility.**

Headroom, an open-source LLM compression library, provides a comprehensive integration with LangChain that resides in the `chopratejas/headroom` repository. This integration implements LangChain's abstract base classes—such as `BaseChatModel`, `BaseDocumentCompressor`, and `BaseMemory`—allowing developers to add token compression and reversible CCR (Compressed Context Representation) storage to existing pipelines without code changes.

## Core Integration Components

The integration ships with several specialized wrappers that mirror LangChain's native interfaces. Each component follows a **zero-intrusion design pattern**, exposing the exact same APIs as standard LangChain objects while internally routing data through Headroom's compression pipeline.

### HeadroomChatModel for Chat Compression

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` interface. It wraps any LangChain-compatible LLM and runs messages through Headroom's compression pipeline before they reach the provider.

When you invoke the model, it automatically compresses the input using `headroom.compress(messages, model=self.model)` and returns a `ChatResponse` that LangChain clients expect. This allows you to reduce token costs on every request without modifying your application logic.

### StreamingMetricsTracker for Performance Monitoring

Located in [`headroom/integrations/langchain/streaming.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/streaming.py), the **`StreamingMetricsTracker`** and **`StreamingMetricsCallback`** classes monitor token usage and latency during streaming responses. 

These trackers use Headroom's token counter—specifically `OpenAIProvider.get_token_counter` by default—to provide accurate statistics on output tokens and chunk counts. The metrics tracker integrates seamlessly with LangChain's streaming callbacks, giving you real-time visibility into compression efficiency.

### HeadroomDocumentCompressor for RAG Pipelines

For retrieval-augmented generation (RAG) workflows, the **`HeadroomDocumentCompressor`** in [`headroom/integrations/langchain/retriever.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/retriever.py) implements LangChain's `BaseDocumentCompressor` interface. 

This component scores retrieved documents using a BM25-style relevance metric and returns the top-k most relevant documents. It works natively with LangChain's `ContextualCompressionRetriever`, allowing you to compress large document sets before they enter the context window, significantly reducing token costs for knowledge-intensive applications.

### HeadroomMemory for Compressed Conversation History

The **`HeadroomMemory`** class in [`headroom/integrations/langchain/memory.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/memory.py) implements LangChain's `BaseMemory` interface. 

Every time a new message is added to the conversation history, this component automatically runs Headroom's `compress` routine. This keeps the conversational context small while remaining reversible via CCR, enabling long-running conversations without hitting context window limits.

### Provider Auto-Detection

The [`headroom/integrations/langchain/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/providers.py) module handles **provider-agnostic token counting** by detecting the underlying LLM provider—whether OpenAI, Anthropic, Bedrock, or others—from the LangChain model instance using duck-typing. 

It then instantiates a matching Headroom Provider object and passes it to the compression pipeline, ensuring that token counting remains accurate regardless of which model you use.

### Agent and Tool Compression

In [`headroom/integrations/langchain/agents.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/agents.py), Headroom provides wrappers that compress tool outputs before they are fed back to the agent. The **`HeadroomToolWrapper`** class wraps LangChain `BaseTool` instances, enabling "compressed-tool-agents" that reduce the token footprint of function calling workflows.

Additionally, the integration includes convenience 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) for exposing Headroom-wrapped models to LangGraph workflows and LangSmith tracing respectively.

## Implementation Patterns

All components in the LangChain integration share three critical design patterns that ensure robustness and flexibility.

### Optional Import Guards

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 install hint `pip install headroom[langchain]`. This makes the integration completely optional—the package only imports LangChain when it detects the library is present.

### Zero-Intrusion API Design

The wrappers expose the exact LangChain abstract base classes, meaning existing pipelines, agents, and LangGraph definitions run unchanged. From the LangChain side, Headroom objects are indistinguishable from native implementations, eliminating migration friction.

### Universal Token Counting

Rather than hardcoding provider-specific logic, the integration delegates token counting to Headroom's generic provider system. This allows the same integration to work with any LLM vendor supported by Headroom, including future providers added to the library.

## Code Examples

### Wrapping a LangChain LLM with Headroom

This example demonstrates how to wrap a standard LangChain chat model with `HeadroomChatModel` to enable automatic compression:

```python
from langchain_openai import ChatOpenAI
from headroom.integrations.langchain import HeadroomChatModel, StreamingMetricsTracker

# Original LangChain model

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

# Wrap it with Headroom compression

headroom_llm = HeadroomChatModel(llm)

# Use it exactly like a regular LangChain model

response = headroom_llm.invoke("Summarize the following code snippet.")
print(response.content)  # Compressed output, original tokens restorable on-demand

```

*Source*: The `HeadroomChatModel` class in [`headroom/integrations/langchain/chat_model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/chat_model.py) forwards calls to the underlying LLM after applying Headroom's compression pipeline.

### Tracking Streaming Metrics

Monitor token usage and latency during streaming responses:

```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)
    print(chunk.content, end="", flush=True)

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

```

*Source*: [`headroom/integrations/langchain/streaming.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/streaming.py) defines `StreamingMetricsTracker` to accumulate content and count tokens using the provider's token counter.

### Compressing Documents in RAG Pipelines

Integrate Headroom's document compressor with LangChain's `ContextualCompressionRetriever`:

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

# Build a vectorstore retriever with high recall

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

# Wrap with Headroom's compressor to keep top-10 relevant documents

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

# Retrieve compressed, relevance-scored documents

results = retriever.invoke("What are the safety considerations for deploying LLMs?")

```

*Source*: [`headroom/integrations/langchain/retriever.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/retriever.py) implements `HeadroomDocumentCompressor` with BM25-style relevance scoring.

### Adding Compressed Memory to Agents

Use `HeadroomMemory` and `HeadroomToolWrapper` to compress both conversation history and tool outputs:

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

# Standard LangChain tool

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

# Wrap tool with Headroom compression

compressed_tool = HeadroomToolWrapper(search_tool)

# Create agent with compressed memory

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

```

*Source*: [`headroom/integrations/langchain/agents.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/agents.py) provides `HeadroomToolWrapper`, while [`memory.py`](https://github.com/chopratejas/headroom/blob/main/memory.py) supplies the `HeadroomMemory` implementation.

## Summary

- **Headroom integrates with LangChain** through an optional module at `headroom/integrations/langchain/` that implements standard LangChain interfaces.
- **Seven core components** provide compression for chat models, streaming metrics, document retrieval, conversation memory, provider detection, tool outputs, and LangGraph/LangSmith compatibility.
- **Zero-intrusion design** means existing LangChain code works without modification—simply wrap your existing objects with Headroom classes.
- **Optional dependencies** ensure the integration only loads when LangChain is installed, with clear error messages guiding installation via `pip install headroom[langchain]`.
- **Provider-agnostic token counting** works across OpenAI, Anthropic, Bedrock, and other supported LLMs through automatic provider detection.

## Frequently Asked Questions

### How do I install Headroom with LangChain support?

Install Headroom using the LangChain extras flag: `pip install headroom[langchain]`. This ensures all LangChain dependencies are available. If you attempt to import from `headroom.integrations.langchain` without LangChain installed, the code raises an `ImportError` with instructions to install the extras.

### Can I use Headroom with existing LangChain agents without rewriting my code?

Yes. Headroom's integration follows a **zero-intrusion API** design. You can wrap existing LangChain models, tools, and memory instances with Headroom classes—such as `HeadroomChatModel` or `HeadroomMemory`—and pass them directly to your existing `AgentExecutor` or chains. The wrappers expose the exact same methods as native LangChain objects.

### Does Headroom's LangChain integration work with streaming responses?

Yes. The `HeadroomChatModel` supports streaming, and the `StreamingMetricsTracker` class in [`headroom/integrations/langchain/streaming.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/streaming.py) specifically tracks token counts and latency during streaming responses. It accumulates chunks and calculates final metrics using the same token counter as non-streaming requests.

### Which LangChain components can Headroom compress?

Headroom provides compression for four primary component types: **chat models** (prompts and responses via `HeadroomChatModel`), **documents** (retrieved context via `HeadroomDocumentCompressor`), **conversation memory** (chat history via `HeadroomMemory`), and **tool outputs** (agent function results via `HeadroomToolWrapper`). Additionally, it supports LangGraph workflows and LangSmith tracing through dedicated helper modules.