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(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.pynew file mode 100644index 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.pyindex 91088efac..da74e000a 100644--- a/headroom/client.py+++ b/headroom/client.py@@ -408,7 +408,7 @@ class HeadroomClient:self._cache_optimizer: BaseCacheOptimizer | None = Noneself._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_optimizerelse:@@ -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.pynew file mode 100644index 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.stderrdiff --git a/tests/test_client_cache_optimizer_config.py b/tests/test_client_cache_optimizer_config.pynew file mode 100644index 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