# How to Integrate Headroom with LangChain Using HeadroomChatModel

> Easily integrate Headroom with LangChain using the HeadroomChatModel. This drop-in wrapper optimizes LLM requests through Headroom's TransformPipeline for enhanced performance. Integrate now!

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

---

**HeadroomChatModel** is a drop-in wrapper that subclasses LangChain's `BaseChatModel` and automatically optimizes every request through Headroom's **TransformPipeline** before forwarding to the underlying LLM.

The `chopratejas/headroom` repository provides a seamless integration for LangChain applications through the `HeadroomChatModel` wrapper. This class intercepts LLM requests, applies context optimization transforms, and delivers reduced token payloads without requiring changes to your existing chain logic. By subclassing LangChain's base chat model interface, Headroom ensures full compatibility with streaming, tool calling, and LCEL compositions.

## Architecture of HeadroomChatModel

The core wrapper is implemented in [`headroom/integrations/langchain/chat_model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/chat_model.py). It subclasses LangChain's `BaseChatModel` and overrides the `invoke`, `stream`, and `ainvoke` methods to inject optimization logic before forwarding requests to the wrapped provider.

### Message Optimization Pipeline

Internally, the wrapper calls `optimize_messages` (lines approximately 150-190 in [`chat_model.py`](https://github.com/chopratejas/headroom/blob/main/chat_model.py)) to build a **TransformPipeline** from the current `HeadroomConfig`. This function:

1. Extracts the provider name using `get_headroom_provider` and the model name via `get_model_name_from_langchain`
2. Constructs a pipeline configured with the repository's default transforms
3. Returns a new message list plus an `OptimizationMetrics` object

The transformed messages are then passed to the underlying LLM, while the original response is returned unchanged to the caller.

### Provider Mapping

Helper functions in [`headroom/integrations/langchain/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/providers.py) map LangChain model objects to concrete Headroom providers like `OpenAIProvider` and `AnthropicProvider`. These utilities extract the underlying model identifier and ensure the TransformPipeline applies provider-specific optimizations.

## Basic Integration

Wrap any existing LangChain chat model to enable automatic optimization:

```python
from langchain_openai import ChatOpenAI
from headroom.integrations import HeadroomChatModel

# Create a regular LangChain chat model

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# Wrap it – all calls now go through Headroom

optimized_llm = HeadroomChatModel(llm)

# Normal invoke works as usual

response = optimized_llm.invoke("Explain the difference between memoization and caching.")
print(response.content)

```

This pattern works with any `BaseChatModel` subclass, including `ChatAnthropic`, `ChatGoogleGenerativeAI`, or custom implementations.

## Streaming and Tool Calls

The wrapper supports streaming generation and tool calling without additional configuration. The `stream` method optimizes the prompt before each chunk is yielded:

```python
from langchain_openai import ChatOpenAI
from headroom.integrations import HeadroomChatModel
from langchain_core.messages import AIMessage, HumanMessage

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

# Streaming generation (chunks are yielded)

for chunk in wrapped.stream([
    HumanMessage(content="Summarize the following text in bullet points."),
    AIMessage(content="Here is the text you want summarized...")
]):
    print(chunk.content, end="")  # prints as chunks arrive

```

The `ainvoke` method provides equivalent async support for non-blocking applications.

## LCEL Composition with HeadroomRunnable

For LangChain Expression Language (LCEL) pipelines, use `HeadroomRunnable` to enable chain composition:

```python
from langchain_openai import ChatOpenAI
from headroom.integrations import HeadroomChatModel, HeadroomRunnable
from langchain.schema import StrOutputParser

llm = ChatOpenAI(model="gpt-4o")
optimized = HeadroomChatModel(llm)

# Turn the model into a Runnable for LCEL pipelines

runnable = HeadroomRunnable(optimized)

# Simple chain: prompt → LLM → parse

chain = (
    {"question": lambda x: x}  # identity input transformer

    | runnable
    | StrOutputParser()
)

print(chain.invoke("What are the main benefits of using Headroom?"))

```

`HeadroomRunnable` is defined in the same [`chat_model.py`](https://github.com/chopratejas/headroom/blob/main/chat_model.py) file and ensures every step of the LCEL chain respects the optimization pipeline.

## Configuration and Optimization Modes

Control which transforms are active using `HeadroomConfig` and `HeadroomMode`, defined in [`headroom/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/__init__.py):

```python
from langchain_openai import ChatOpenAI
from headroom import HeadroomConfig, HeadroomMode
from headroom.integrations import HeadroomChatModel

config = HeadroomConfig(mode=HeadroomMode.COMPACT)   # fewer transforms, faster

llm = ChatOpenAI(model="gpt-4o")
optimized = HeadroomChatModel(llm, config=config)

print(optimized.invoke("Write a concise tweet about AI safety."))

```

Available modes include:
- **OPTIMIZE**: Full transformation pipeline (default)
- **COMPACT**: Reduced transforms for faster processing
- **SAFE**: Conservative optimizations preserving context

## Monitoring with HeadroomCallbackHandler

The optional `HeadroomCallbackHandler` (also in [`chat_model.py`](https://github.com/chopratejas/headroom/blob/main/chat_model.py)) records token usage, latency, and which transforms were applied. Note that due to LangChain's design, callbacks cannot modify messages, so this handler is purely for observability:

```python
from headroom.integrations.langchain.chat_model import HeadroomCallbackHandler

callback = HeadroomCallbackHandler()
response = optimized_llm.invoke("Query", callbacks=[callback])

# Metrics available via callback.metrics

```

## Summary

- **HeadroomChatModel** wraps any LangChain `BaseChatModel` to apply automatic context optimization
- The wrapper intercepts `invoke`, `stream`, and `ainvoke` calls in [`headroom/integrations/langchain/chat_model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/chat_model.py) and processes messages through a `TransformPipeline`
- Provider mapping utilities in [`headroom/integrations/langchain/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/providers.py) ensure compatibility with OpenAI, Anthropic, and other LLM providers
- **HeadroomRunnable** enables LCEL composition while maintaining optimization guarantees
- Configure optimization intensity via `HeadroomConfig` using modes like `HeadroomMode.COMPACT` or `HeadroomMode.SAFE`

## Frequently Asked Questions

### Does HeadroomChatModel support streaming and async operations?

Yes. The wrapper implements both `stream` and `ainvoke` methods that apply the same TransformPipeline optimization before yielding chunks or returning async results. Streaming works transparently with the wrapped model's native streaming capabilities.

### Can I use HeadroomChatModel with existing LangChain chains?

Yes. Because HeadroomChatModel subclasses `BaseChatModel`, it is a drop-in replacement for any chat model in your existing chains. For LCEL pipelines specifically, use `HeadroomRunnable` to ensure proper composition behavior.

### How do I configure which transforms are applied?

Pass a `HeadroomConfig` object to the `HeadroomChatModel` constructor. Set the `mode` parameter to `HeadroomMode.OPTIMIZE`, `HeadroomMode.COMPACT`, or `HeadroomMode.SAFE` to control the transform pipeline intensity. You can also configure individual transforms in the `HeadroomConfig` instance.

### Does HeadroomChatModel work with providers other than OpenAI?

Yes. The integration supports any LangChain chat model, including Anthropic, Google, and custom implementations. The `get_headroom_provider` utility in [`headroom/integrations/langchain/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/langchain/providers.py) automatically maps LangChain model instances to the appropriate Headroom provider class for provider-specific optimizations.