Skip to content

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.

fix(langchain): check optional integration availability (#4042)

Mansurshakh Japarovcde584d7fe69
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b462acd22..7aca1f52f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -119,7 +119,7 @@ jobs:
- name: Verify Ruff version alignment
id: ruff-version
run: 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 check
run: ruff check .
- name: ruff format --check
@@ -393,7 +393,7 @@ jobs:
python -m pip install --upgrade pip
pip install torch --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple
WHEEL="$(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.md
index 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. Without
diff --git a/headroom/integrations/langchain/chat_model.py b/headroom/integrations/langchain/chat_model.py
index 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.py
new file mode 100644
index 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) == 23
diff --git a/tests/test_integrations/langchain/test_langchain_1x_compat.py b/tests/test_integrations/langchain/test_langchain_1x_compat.py
index 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 by
running 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`` on
invoke, because ``StructuredTool`` calls its ``func`` with unpacked kwargs
while ``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 tool
with no parameters.
-4. ``HeadroomDocumentCompressor`` silently subclassed a local stub rather than
+3. ``HeadroomDocumentCompressor`` silently subclassed a local stub rather than
LangChain's ``BaseDocumentCompressor``, so retrievers rejected it.
"""
import asyncio
import json
-from typing import Any
import pytest
try:
- from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
- from langchain_core.messages import AIMessage
from langchain_core.tools import tool
LANGCHAIN_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_headroom
diff --git a/tests/test_startup_log_noise.py b/tests/test_startup_log_noise.py
index 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 a
diff --git a/tests/test_xai_cache_economics.py b/tests/test_xai_cache_economics.py
index 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"])