Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(langchain): check optional integration availability (#4042)
Mansurshakh Japarovcde584d7fe69
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex b462acd22..7aca1f52f 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -119,7 +119,7 @@ jobs:- name: Verify Ruff version alignmentid: ruff-versionrun: echo "version=$(python scripts/verify-ruff-version.py --print-version)" >> "$GITHUB_OUTPUT"- - run: python -m pip install --upgrade pip "ruff==${{ steps.ruff-version.outputs.version }}" "mypy==1.20.2"+ - run: python -m pip install --upgrade pip "ruff==${{ steps.ruff-version.outputs.version }}" "mypy==1.20.2" "langchain-core>=1.3.3,<4.0"- name: ruff checkrun: ruff check .- name: ruff format --check@@ -393,7 +393,7 @@ jobs:python -m pip install --upgrade pippip install torch --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simpleWHEEL="$(ls dist/*.whl)"- pip install "${WHEEL}[dev]" pytest-split+ pip install "${WHEEL}[dev,langchain]" pytest-split# cwd's ./headroom source tree shadows the installed wheel; copy the# compiled extension in so tests import it (no second cargo build).SITE="$(python -c 'import sysconfig; print(sysconfig.get_path("platlib"))')"diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 19c5317ff..248b33bd6 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -130,6 +130,11 @@ Enable or disable automatic Copilot review in **Settings → Rules → Rulesets- Type hints on public functions; Google-style docstrings.- Cover new behavior + edge cases; aim >80% coverage on new code.- Python 3.11+. Optional features go behind extras.+- For an optional-integration change, run its owner tests and `mypy headroom`+ with the relevant extra installed. A hook environment without that dependency+ does not check the imported library's types.+ CI lint installs `langchain-core` for its normal mypy run; keep typechecking+ there rather than launching a second mypy subprocess from pytest.- **Headroom writes LF and normalizes on read, on every platform.** Pass`newline="\n"` to every `write_text`/`open` that writes a context, memory,or state file, and normalize `\r\n`/`\r` when you read one back. Withoutdiff --git a/headroom/integrations/langchain/chat_model.py b/headroom/integrations/langchain/chat_model.pyindex 6f4dd4eca..b7738ba72 100644--- a/headroom/integrations/langchain/chat_model.py+++ b/headroom/integrations/langchain/chat_model.py@@ -377,7 +377,7 @@ class HeadroomChatModel(BaseChatModel):pass them explicitly."""bound_kwargs: dict[str, Any] = {}- if not RunnableBinding:+ if not LANGCHAIN_AVAILABLE:return model, bound_kwargs# isinstance, not hasattr: a Mock answers hasattr("bound") truthfully# and would be unwrapped into one of its own auto-created children.diff --git a/tests/test_integrations/langchain/test_binding_http.py b/tests/test_integrations/langchain/test_binding_http.pynew file mode 100644index 000000000..eac125bfb--- /dev/null+++ b/tests/test_integrations/langchain/test_binding_http.py@@ -0,0 +1,178 @@+"""Cover Headroom's binding-kwargs merge with real LangChain and loopback HTTP."""++import asyncio+import json+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer+from threading import Thread++import pytest++MODEL = "headroom-binding-loopback"+++def _tool(name):+ return {+ "type": "function",+ "function": {+ "name": name,+ "description": "Look up the weather in a city.",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ }+++def _choice(name):+ return {"type": "function", "function": {"name": name}}++[email protected](autouse=True)+def offline_headroom(monkeypatch, tmp_path):+ """Disable automatic egress and isolate normal product state/config."""+ monkeypatch.setenv("HEADROOM_OFFLINE", "1")+ # Track these too: apply_offline_env() sets them lazily during product use.+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")+ monkeypatch.setenv("TRANSFORMERS_OFFLINE", "1")+ monkeypatch.setenv("DO_NOT_TRACK", "1")+ monkeypatch.setenv("HEADROOM_CONFIG_DIR", str(tmp_path / "config"))+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / "workspace"))+ monkeypatch.setenv("HEADROOM_MODEL_LIMITS", json.dumps({"context_limits": {MODEL: 128000}}))+ for name in ("LANGCHAIN_TRACING", "LANGCHAIN_TRACING_V2", "LANGSMITH_TRACING"):+ monkeypatch.setenv(name, "false")+ monkeypatch.setenv("OTEL_SDK_DISABLED", "true")+ monkeypatch.setenv("OPENAI_PROXY", "")+++def openai_loopback():+ """Run only a local HTTP fixture, without hosted calls or real credentials."""+ pytest.importorskip("langchain_openai")+ requests = []++ class Handler(BaseHTTPRequestHandler):+ def do_POST(self):+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))+ requests.append((self.path, body))+ message = {"role": "assistant", "content": "Loopback reply"}+ finish_reason = "stop"+ response = json.dumps(+ {+ "id": "chatcmpl-loopback",+ "object": "chat.completion",+ "created": 1,+ "model": MODEL,+ "choices": [{"index": 0, "message": message, "finish_reason": finish_reason}],+ "usage": {"prompt_tokens": 41, "completion_tokens": 9, "total_tokens": 50},+ }+ ).encode()+ self.send_response(200)+ self.send_header("Content-Type", "application/json")+ self.send_header("Content-Length", str(len(response)))+ self.end_headers()+ self.wfile.write(response)++ def log_message(self, *args):+ pass++ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ thread = Thread(target=server.serve_forever, daemon=True)+ thread.start()+ try:+ yield f"http://127.0.0.1:{server.server_port}/v1", requests+ finally:+ server.shutdown()+ server.server_close()+ thread.join(timeout=5)+ assert not thread.is_alive(), "Loopback HTTP server did not stop"++[email protected]("binding", ["bind_tools", "nested"])+def test_binding_reaches_openai_http(openai_loopback, binding):+ import httpx+ from langchain_core.runnables import RunnableBinding+ from langchain_openai import ChatOpenAI+ from langsmith import tracing_context++ from headroom.integrations import HeadroomChatModel++ base_url, requests = openai_loopback+ with tracing_context(enabled=False), httpx.Client(trust_env=False) as http_client:+ original = ChatOpenAI(+ model=MODEL,+ api_key="loopback-dummy-key",+ base_url=base_url,+ max_retries=0,+ timeout=5,+ use_responses_api=False,+ http_client=http_client,+ )+ kwargs = {}+ expected_name = "inner_weather"+ if binding == "bind_tools":+ wrapped = HeadroomChatModel(original, auto_detect_provider=False).bind_tools(+ [_tool(expected_name)], tool_choice=expected_name+ )+ else:+ inner = original.bind_tools(+ [_tool("inner_weather")],+ tool_choice="inner_weather",+ temperature=0.1,+ top_p=0.8,+ )+ outer = RunnableBinding(+ bound=inner,+ kwargs={+ "tools": [_tool("outer_weather")],+ "tool_choice": _choice("outer_weather"),+ "temperature": 0.2,+ },+ )+ wrapped = HeadroomChatModel(outer, auto_detect_provider=False)+ expected_name = "caller_weather"+ kwargs = {+ "tools": [_tool(expected_name)],+ "tool_choice": _choice(expected_name),+ "temperature": 0.3,+ }+ wrapped.cache = False+ wrapped.invoke("What is the weather in Paris?", **kwargs)++ _, body = requests[0]+ assert body["tools"] == [_tool(expected_name)]+ assert body["tool_choice"] == _choice(expected_name)+ if binding == "nested":+ assert body["temperature"] == 0.3+ assert body["top_p"] == 0.8+++def test_unwrap_binding_matches_real_runnable_precedence():+ pytest.importorskip("langchain_core")+ from langchain_core.runnables import RunnableBinding, RunnableLambda+ from langsmith import tracing_context++ from headroom.integrations import HeadroomChatModel++ def affine(value, scale=1, offset=0):+ return value * scale + offset++ target = RunnableLambda(affine)+ inner = RunnableBinding(bound=target, kwargs={"scale": 2, "offset": 3})+ outer = RunnableBinding(bound=inner, kwargs={"scale": 5})+ unwrapped, kwargs = HeadroomChatModel._unwrap_binding(outer)+ plain, plain_kwargs = HeadroomChatModel._unwrap_binding(target)+ assert unwrapped is target++ with tracing_context(enabled=False):+ assert outer.invoke(4) == unwrapped.invoke(4, **kwargs) == 23+ caller_kwargs = {**kwargs, "scale": 7}+ assert outer.invoke(4, scale=7) == unwrapped.invoke(4, **caller_kwargs) == 31+ assert asyncio.run(outer.ainvoke(4)) == asyncio.run(unwrapped.ainvoke(4, **kwargs)) == 23+ assert asyncio.run(outer.ainvoke(4, scale=7)) == 31+ assert asyncio.run(unwrapped.ainvoke(4, **caller_kwargs)) == 31+ assert plain.invoke(4, **plain_kwargs) == 4+ # Caller overrides must not mutate either reusable binding.+ assert inner.invoke(4) == 11+ assert outer.invoke(4) == 23diff --git a/tests/test_integrations/langchain/test_langchain_1x_compat.py b/tests/test_integrations/langchain/test_langchain_1x_compat.pyindex 43d81f8c1..f90ee4dd0 100644--- a/tests/test_integrations/langchain/test_langchain_1x_compat.py+++ b/tests/test_integrations/langchain/test_langchain_1x_compat.py@@ -3,27 +3,21 @@Each test here corresponds to a defect that shipped in 0.37.0 and was found byrunning the documented examples against langchain-core 1.6:-1. ``HeadroomChatModel.bind_tools()`` returned a model that emitted no tool- calls, because ``_generate`` called the private method on the- ``RunnableBinding`` and the bound kwargs were dropped.-2. ``wrap_tools_with_headroom`` produced tools that raised ``TypeError`` on+1. ``wrap_tools_with_headroom`` produced tools that raised ``TypeError`` oninvoke, because ``StructuredTool`` calls its ``func`` with unpacked kwargswhile ``BaseTool.invoke`` takes a single input.-3. The wrapped tool lost the original ``args_schema``, so a model saw a tool+2. The wrapped tool lost the original ``args_schema``, so a model saw a toolwith no parameters.-4. ``HeadroomDocumentCompressor`` silently subclassed a local stub rather than+3. ``HeadroomDocumentCompressor`` silently subclassed a local stub rather thanLangChain's ``BaseDocumentCompressor``, so retrievers rejected it."""import asyncioimport json-from typing import Anyimport pytesttry:- from langchain_core.language_models.fake_chat_models import GenericFakeChatModel- from langchain_core.messages import AIMessagefrom langchain_core.tools import toolLANGCHAIN_AVAILABLE = True@@ -61,60 +55,8 @@ def query_database(query: str) -> str:return BIG_RESULT-class _RecordingModel(GenericFakeChatModel):- """Fake model that records the kwargs its _generate actually received."""-- last_kwargs: dict[str, Any] = {}-- def _generate(self, messages, stop=None, run_manager=None, **kwargs):- type(self).last_kwargs = dict(kwargs)- kwargs.pop("tools", None)- return super()._generate(messages, stop=stop, run_manager=run_manager, **kwargs)-- def bind_tools(self, tools, **kwargs):- # Mirrors what real providers do: return a RunnableBinding carrying the- # tools in .kwargs rather than a new model instance.- return self.bind(tools=list(tools), **kwargs)---class TestBindToolsSurvivesWrapping:- """Defect 1: bound kwargs must reach the underlying model."""-- def test_bound_tools_reach_generate(self):- from headroom.integrations import HeadroomChatModel-- _RecordingModel.last_kwargs = {}- inner = _RecordingModel(messages=iter([AIMessage("ok")]))- wrapped = HeadroomChatModel(inner).bind_tools([query_database])-- wrapped.invoke("call the tool")-- assert "tools" in _RecordingModel.last_kwargs, (- "bind_tools kwargs were dropped before reaching the wrapped model; "- "an agent built on this model would never call a tool"- )-- def test_unbound_model_passes_no_tools(self):- from headroom.integrations import HeadroomChatModel-- _RecordingModel.last_kwargs = {}- inner = _RecordingModel(messages=iter([AIMessage("ok")]))- HeadroomChatModel(inner).invoke("hello")-- assert "tools" not in _RecordingModel.last_kwargs-- def test_unwrap_binding_ignores_non_bindings(self):- from headroom.integrations import HeadroomChatModel-- inner = GenericFakeChatModel(messages=iter([AIMessage("ok")]))- model, kwargs = HeadroomChatModel._unwrap_binding(inner)-- assert model is inner- assert kwargs == {}--class TestWrappedToolIsUsable:- """Defects 2 and 3: the wrapped tool must invoke, and keep its schema."""+ """Defects 1 and 2: the wrapped tool must invoke, and keep its schema."""def test_invoke_with_keyword_arguments(self):from headroom.integrations import wrap_tools_with_headroomdiff --git a/tests/test_startup_log_noise.py b/tests/test_startup_log_noise.pyindex 9e838d774..2831d0f93 100644--- a/tests/test_startup_log_noise.py+++ b/tests/test_startup_log_noise.py@@ -118,6 +118,11 @@ class TestLiteLLMLogSuppression:"""The env flag must exist before litellm itself is imported."""import os+ import headroom.providers as providers++ # Import also replaces the parent package attribute. Track it even when+ # initially absent so teardown restores or removes the temporary module.+ monkeypatch.setattr(providers, "litellm", None, raising=False)monkeypatch.delenv("LITELLM_SUPPRESS_DEBUG_INFO", raising=False)# delitem, not pop: teardown puts the real modules back. A bare pop made# every later `import litellm` load a second copy, so a test pinning adiff --git a/tests/test_xai_cache_economics.py b/tests/test_xai_cache_economics.pyindex 8f0314025..560b1cf39 100644--- a/tests/test_xai_cache_economics.py+++ b/tests/test_xai_cache_economics.py@@ -72,6 +72,10 @@ def test_xai_cache_savings_and_billing_use_their_respective_price_sources(}if catalog_read is not None:row["cache_read_input_token_cost"] = catalog_read+ original_row = litellm.model_cost[model]+ # Register through the public API; keep the isolated row free of inherited rates.+ monkeypatch.setitem(litellm.model_cost, model, dict(row))+ litellm.register_model({model: dict(row)})monkeypatch.setitem(litellm.model_cost, model, row)resolve_rates.cache_clear()try:@@ -83,21 +87,19 @@ def test_xai_cache_savings_and_billing_use_their_respective_price_sources(# A provider-wide counterfactual estimate is not a billed cache rate.# Use the real calculator for the same reported usage, as billing does.- if catalog_read is None:- canonical_input, _ = litellm.cost_per_token(- model=model,- prompt_tokens=10_000,- completion_tokens=0,- cache_read_input_tokens=10_000,- )- else:- canonical_input = 10_000 * catalog_read+ canonical_input, _ = litellm.cost_per_token(+ model=model,+ prompt_tokens=10_000,+ completion_tokens=0,+ cache_read_input_tokens=10_000,+ )tracker = CostTracker()tracker.record_tokens(model, tokens_saved=0, tokens_sent=10_000, cache_read_tokens=10_000)assert tracker.totals()[1] == pytest.approx(canonical_input)assert tracker.stats()["total_input_cost_usd"] == pytest.approx(canonical_input)finally:resolve_rates.cache_clear()+ litellm.register_model({model: original_row})@pytest.mark.parametrize("user_agent", ["grok/1.2.3", "grok-shell/0.2.112"])