How Headroom Integrates with LangChain: Complete API Guide

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 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, 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 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 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 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, 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 and 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:

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 forwards calls to the underlying LLM after applying Headroom's compression pipeline.

Tracking Streaming Metrics

Monitor token usage and latency during streaming responses:

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

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 implements HeadroomDocumentCompressor with BM25-style relevance scoring.

Adding Compressed Memory to Agents

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

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 provides HeadroomToolWrapper, while 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 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.

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