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(client): honor configured cache optimizer enablement (#4501)

Rudy Mizrahi Celeklid4c0810ea3eb
diff --git a/examples/cache_optimizer_config_local.py b/examples/cache_optimizer_config_local.py
new file mode 100644
index 000000000..b7981c45d
--- /dev/null
+++ b/examples/cache_optimizer_config_local.py
@@ -0,0 +1,124 @@
+"""Actual OpenAI SDK HTTP requests: typed cache opt-out must preserve caller spaces."""
+
+import hashlib
+import json
+import os
+import tempfile
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+
+def main():
+ with tempfile.TemporaryDirectory(prefix="headroom-cache-config-") as scratch:
+ for key in ["HEADROOM_WORKSPACE_DIR", "HEADROOM_CONFIG_DIR", "XDG_CACHE_HOME"]:
+ os.environ[key] = str(Path(scratch) / key.lower())
+ # This isolated proof needs no persistent, process-global CCR database.
+ # Keep the store in memory so Windows can remove the scratch directory.
+ os.environ.update(
+ HEADROOM_OFFLINE="1",
+ HEADROOM_BEACON="off",
+ DO_NOT_TRACK="1",
+ HEADROOM_CCR_BACKEND="memory",
+ )
+ from openai import OpenAI
+
+ from headroom import HeadroomClient, OpenAIProvider
+ from headroom.config import HeadroomConfig, HeadroomMode
+
+ requests = []
+ violations = []
+
+ class Handler(BaseHTTPRequestHandler):
+ def log_message(self, *args):
+ pass
+
+ def do_POST(self):
+ raw = self.rfile.read(int(self.headers["Content-Length"]))
+ body = json.loads(raw)
+ wire_dir = os.environ.get("HEADROOM_PROOF_WIRE_DIR")
+ if wire_dir:
+ target = Path(wire_dir)
+ target.mkdir(parents=True, exist_ok=True)
+ (target / f"request-{len(requests)}.json").write_bytes(raw)
+ requests.append(body)
+ payload = json.dumps(
+ {
+ "id": "chatcmpl_fixture",
+ "object": "chat.completion",
+ "created": 0,
+ "model": body["model"],
+ "choices": [
+ {
+ "index": 0,
+ "message": {"role": "assistant", "content": "local fixture"},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {"prompt_tokens": 1, "completion_tokens": 2, "total_tokens": 3},
+ }
+ ).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(payload)))
+ self.end_headers()
+ self.wfile.write(payload)
+
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+ original = OpenAI(
+ api_key="local-fixture",
+ base_url=f"http://127.0.0.1:{server.server_port}",
+ max_retries=0,
+ )
+ try:
+ for enabled in [False, True]:
+ url = f"sqlite:///{scratch}/{enabled}.db"
+ config = HeadroomConfig(
+ store_url=url,
+ default_mode=HeadroomMode.OPTIMIZE,
+ discover_pipeline_extensions=False,
+ )
+ config.smart_crusher.enabled = False
+ config.cache_aligner.enabled = False
+ config.cache_optimizer.enabled = enabled
+ client = HeadroomClient(original, OpenAIProvider(), store_url=url, config=config)
+ try:
+ response = client.chat.completions.create(
+ model="gpt-4o",
+ messages=[
+ {"role": "system", "content": "Keep exact spaces.\n"},
+ {"role": "user", "content": "Hello."},
+ ],
+ max_tokens=8,
+ )
+ wire_system = requests[-1]["messages"][0]["content"]
+ print(
+ json.dumps(
+ {
+ "configured_enabled": enabled,
+ "runtime_optimizer": client.get_stats()["config"][
+ "cache_optimizer"
+ ],
+ "wire_system": wire_system,
+ "wire_system_sha256": hashlib.sha256(
+ wire_system.encode()
+ ).hexdigest(),
+ "response": response.choices[0].message.content,
+ }
+ )
+ )
+ if not enabled and wire_system != "Keep exact spaces.\n":
+ violations.append("Disabled cache optimizer modified the system message")
+ finally:
+ client.close()
+ finally:
+ original.close()
+ server.shutdown()
+ server.server_close()
+
+ assert not violations, violations
+
+
+if __name__ == "__main__":
+ main()
diff --git a/headroom/client.py b/headroom/client.py
index 91088efac..da74e000a 100644
--- a/headroom/client.py
+++ b/headroom/client.py
@@ -408,7 +408,7 @@ class HeadroomClient:
self._cache_optimizer: BaseCacheOptimizer | None = None
self._semantic_cache_layer: SemanticCacheLayer | None = None
- if enable_cache_optimizer:
+ if self._config.cache_optimizer.enabled:
if cache_optimizer is not None:
self._cache_optimizer = cache_optimizer
else:
@@ -442,7 +442,7 @@ class HeadroomClient:
provider=self._provider.name.lower(),
metadata={
"default_mode": self._default_mode.value,
- "cache_optimizer_enabled": enable_cache_optimizer,
+ "cache_optimizer_enabled": self._config.cache_optimizer.enabled,
"semantic_cache_enabled": enable_semantic_cache,
},
)
diff --git a/tests/test_cache_optimizer_example_cleanup.py b/tests/test_cache_optimizer_example_cleanup.py
new file mode 100644
index 000000000..aebef6325
--- /dev/null
+++ b/tests/test_cache_optimizer_example_cleanup.py
@@ -0,0 +1,45 @@
+"""The actual SDK loopback example must not leave a global scratch SQLite store."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_cache_optimizer_example_keeps_ccr_in_memory() -> None:
+ repo = Path(__file__).resolve().parents[1]
+ probe = """
+import runpy
+import tempfile
+from pathlib import Path
+
+original = tempfile.TemporaryDirectory
+class GuardedTemporaryDirectory(original):
+ def __exit__(self, *args):
+ databases = list(Path(self.name).rglob("ccr_store.db"))
+ try:
+ assert not databases, "Example opened a process-global scratch CCR SQLite database"
+ finally:
+ super().__exit__(*args)
+
+tempfile.TemporaryDirectory = GuardedTemporaryDirectory
+runpy.run_path("examples/cache_optimizer_config_local.py", run_name="__main__")
+"""
+ env = {
+ **os.environ,
+ "PYTHONPATH": str(repo),
+ "HEADROOM_CCR_BACKEND": "sqlite",
+ "HEADROOM_COMPRESS_SESSION_STORE": "",
+ "HEADROOM_OFFLINE": "1",
+ "HEADROOM_BEACON": "off",
+ "DO_NOT_TRACK": "1",
+ }
+ result = subprocess.run(
+ [sys.executable, "-c", probe],
+ cwd=repo,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=60,
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
diff --git a/tests/test_client_cache_optimizer_config.py b/tests/test_client_cache_optimizer_config.py
new file mode 100644
index 000000000..6745e719f
--- /dev/null
+++ b/tests/test_client_cache_optimizer_config.py
@@ -0,0 +1,57 @@
+"""The effective config owns SDK cache optimization and its setup provenance."""
+
+import pytest
+from openai import OpenAI
+
+from headroom import HeadroomClient, OpenAIProvider
+from headroom.cache.openai import OpenAICacheOptimizer
+from headroom.config import HeadroomConfig
+from headroom.pipeline import PipelineStage
+
+
+class SetupRecorder:
+ def __init__(self):
+ self.events = []
+
+ def on_pipeline_event(self, event):
+ if event.stage == PipelineStage.SETUP:
+ self.events.append(event)
+
+
[email protected]("configured", [False, True])
[email protected]("constructor", [False, True])
+def test_config_cache_enabled_takes_precedence(tmp_path, configured, constructor):
+ recorder = SetupRecorder()
+ url = f"sqlite:///{tmp_path}/metrics.db"
+ config = HeadroomConfig(
+ store_url=url,
+ discover_pipeline_extensions=False,
+ pipeline_extensions=[recorder],
+ )
+ config.cache_optimizer.enabled = configured
+ with OpenAI(api_key="local-fixture") as original:
+ with HeadroomClient(
+ original,
+ OpenAIProvider(),
+ store_url=url,
+ config=config,
+ enable_cache_optimizer=constructor,
+ ) as client:
+ expected = "openai-prefix-stabilizer" if configured else None
+ assert client.get_stats()["config"]["cache_optimizer"] == expected
+ assert recorder.events[0].metadata["cache_optimizer_enabled"] is configured
+
+
+def test_disabled_config_also_skips_explicit_optimizer(tmp_path):
+ url = f"sqlite:///{tmp_path}/metrics.db"
+ config = HeadroomConfig(store_url=url, discover_pipeline_extensions=False)
+ config.cache_optimizer.enabled = False
+ with OpenAI(api_key="local-fixture") as original:
+ with HeadroomClient(
+ original,
+ OpenAIProvider(),
+ store_url=url,
+ config=config,
+ cache_optimizer=OpenAICacheOptimizer(),
+ ) as client:
+ assert client.get_stats()["config"]["cache_optimizer"] is None