Files
Tejas ChopraandClaude Opus 5.5 02ce467d2d chore(integrations): fix the broken LangChain example and stale docstrings (#4134)
## Description

This PR fixes a broken example and two stale docstrings in the
integrations.

- `examples/langchain_demo/run_comparison.py` could not run its Headroom
arm at all. It failed in three places, in this order:
1. `HeadroomConfig(smart_crusher_threshold=...,
smart_crusher_max_items=..., cache_alignment=..., rolling_window=...)`:
none of these keyword arguments exist, so it raised `TypeError` before
anything ran. (Rolling-window was removed from the pipeline; see
`docs/content/docs/architecture.mdx`.)
2. `HeadroomChatModel(..., headroom_config=config)`: the constructor
parameter is `config`, so this raised `TypeError: ... got multiple
values for keyword argument 'headroom_config'`.
3. `headroom_model.get_total_tokens_saved()`: `HeadroomChatModel` has no
such method; it exposes the `total_tokens_saved` property, so this would
have raised `AttributeError` at the end of each scenario.
- The `headroom/integrations/mcp/server.py` module docstring showed a
`HeadroomMCPMiddleware` class that does not exist.
- The `headroom/integrations/__init__.py` docstring showed the same Agno
import line twice.

Refs #4136

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `examples/langchain_demo/run_comparison.py`:
- the config becomes `HeadroomConfig()`, with a comment saying why. The
old keyword arguments do not exist, and their nearest real equivalent
(`smart_crusher=SmartCrusherConfig(...)`) would have no effect:
`TransformPipeline` builds its `ContentRouter` from the router's own
defaults and never reads `HeadroomConfig.smart_crusher`. That wiring gap
is a separate product change; it is recorded in the docs ledger because
`api-reference.mdx` shows such a setting;
  - `headroom_config=config` becomes `config=config`;
- `headroom_model.get_total_tokens_saved()` becomes
`headroom_model.total_tokens_saved`.
- the printed narrative no longer claims a 20-item cap or a CacheAligner
gain (CacheAligner is off by default, and the 15-item setting applies
only to lossy row selection); the simulation figure is labelled a rough
5x estimate.
- `headroom/integrations/mcp/server.py`: the "Middleware" docstring
example now uses the real `HeadroomMCPClientWrapper(base_client,
config=config)` and its `call_tool`.
- `headroom/integrations/__init__.py`: the first Agno example line now
shows the package-level import `from headroom.integrations import
HeadroomAgnoModel`, which is re-exported there. The "or explicitly" line
keeps the subpackage import.

## Testing

- [ ] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ python -c "from headroom.integrations.langchain import HeadroomChatModel as H; print(type(H.__dict__.get('total_tokens_saved')).__name__, hasattr(H, 'get_total_tokens_saved'))"
property False
$ python -c "from headroom.integrations import HeadroomAgnoModel; print('ok')"
ok
$ python -m py_compile examples/langchain_demo/run_comparison.py && echo compiled
compiled
# run_agent_headroom(SCENARIOS[0]) with ChatOpenAI replaced by a fake LangChain chat model (no API key)
# that first asks for a search_logs tool call, then answers "done"
origin/main: TypeError: HeadroomConfig.__init__() got an unexpected keyword argument 'smart_crusher_threshold'
this branch: model calls: 2 | 2nd call message types: ['SystemMessage', 'HumanMessage', 'AIMessage', 'ToolMessage']
             OK scenario='User Account Investigation' tool_calls=1 tool_output_tokens=25643 final='done' messages=5
$ pytest tests/test_integrations/mcp tests/test_integrations/langchain/test_chat_model.py
70 passed, 9 skipped
$ uvx ruff@0.16.8 check / format --check <3 touched files>  -> All checks passed! / already formatted
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, repo venv.
- Exact command / steps: the commands above. The example run imports
`examples.langchain_demo.run_comparison`, swaps `ChatOpenAI` for a
`FakeMessagesListChatModel` that first returns a `search_logs` tool call
and then answers "done", and calls `run_agent_headroom` on the first
scenario. So construction, a tool-result turn through
`HeadroomChatModel`, and the metrics read all run.
- Observed result: on origin/main the Headroom arm raises `TypeError` at
config construction; on this branch it returns an `AgentRun`. The
docstring imports resolve.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):

```text
branch: cleanup/cli-integrations-integrations-unused-imports @ 0ff4cbf3
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines (<tmp>/ws/logs/proxy-53143.log):
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: <tmp>)
```
- Direct runtime command on this PR's own path (temp HOME,
HEADROOM_WORKSPACE_DIR and CODEX_HOME):

```text
$ python examples/langchain_demo check: run_agent_headroom(SCENARIOS[0]) with a fake chat model (tool call, then "done")
model calls: 2 | 2nd call message types: ['SystemMessage', 'HumanMessage', 'AIMessage', 'ToolMessage']
OK scenario='User Account Investigation' tool_calls=1 tool_output_tokens=25627 final='done' messages=5
```
- Not tested: running the full demo against a real model, which needs
live API keys.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a, example script and docstrings only.
- Stable/default behavior changed: no library behaviour changes.
- Kill switch / disable path: n/a.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- The audit also proposed removing three unused try-block imports:
  - `ModelResponse` in `agno/model.py`;
  - `AIMessageChunk` in `langchain/streaming.py`;
  - `BeforeToolCallEvent` in `strands/hooks.py`.

They are left in place. `from headroom.integrations.<x> import <name>`
works for each of them today, with or without the framework installed,
and nothing importable from `headroom/integrations/` may be removed.
- The branch name still says "unused-imports" for that reason.
- No regression test: the example is not part of the test suite; the
fake-model run above is the check.
- Docs: `wiki/langchain.md:587` documents the same nonexistent
`headroom_config=` keyword. That is recorded in the docs ledger; this PR
does not edit docs.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4134"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:02:10 -07:00
..

LangChain + Headroom Demo

Real-world demonstration of Headroom optimization on LangChain agents.

Quick Start

# Show compression in action (no API key needed)
PYTHONPATH=. python -m examples.langchain_demo.show_compression

# Verify 100% ERROR preservation
PYTHONPATH=. python -m examples.langchain_demo.verify_errors_kept

# Run full agent comparison (requires OPENAI_API_KEY)
export OPENAI_API_KEY='your-key-here'
PYTHONPATH=. python -m examples.langchain_demo.run_comparison

Results

Token Savings (with 100% ERROR preservation)

Tool Before After Saved
search_users (100 items) 15,453 2,014 87%
search_logs (200 items) 25,679 3,213 87%
get_metrics (100 items) 11,517 8,425 27%
search_docs (50 items) 6,912 2,127 69%
fetch_api_data (75 items) 15,786 3,622 77%
TOTAL 75,347 19,401 74%

Critical Data Preservation

  • 100% ERROR entries preserved (27/27 in test runs)
  • 100% anomaly detection (CPU spikes, high error rates)
  • First/last items always kept (context preservation)

Cost Impact (at gpt-4o $2.50/1M)

  • Per request: $0.19 → $0.05
  • At 1000 req/day: $4,196/month saved

What Headroom Does

SmartCrusher intelligently compresses tool outputs by:

  1. 100% ERROR preservation - NEVER drops error items (bug fix v1.1)
  2. Keeping first/last items - Context for pagination
  3. Keeping anomalies - High CPU, memory spikes (statistical detection)
  4. Relevance scoring - Items matching user's query
  5. Change points - Significant transitions in data

Files

  • mock_tools.py - Realistic tool output generators
  • show_compression.py - Standalone compression demo
  • verify_errors_kept.py - Verify 100% ERROR preservation
  • run_comparison.py - Full agent before/after comparison

Eval Tests

Run the comprehensive eval suite:

PYTHONPATH=. pytest tests/test_integrations/test_langchain_evals.py -v

12 evals covering:

  • Error preservation (100%)
  • Anomaly detection
  • Relevance matching
  • Compression efficiency
  • Schema preservation
  • Edge cases