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
perf(proxy): avoid eager dependency imports (#3546)
Syamsul Alam59bd482fa166
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex 4b429590d..a04d7fd18 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -5,7 +5,7 @@ import osimport platformimport sysimport warnings-from importlib import import_module+from importlib.util import find_specfrom pathlib import Pathfrom typing import Any, Literal, cast@@ -49,8 +49,9 @@ def ensure_proxy_dependencies() -> None:required_modules.append("orjson")try:- for module in required_modules:- import_module(module)+ missing = next((module for module in required_modules if find_spec(module) is None), None)+ if missing is not None:+ raise ImportError(f"No module named '{missing}'")except ImportError as e:click.secho("Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]",diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex c3f68eb80..efbcc389c 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -3180,11 +3180,13 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# Installed here (not at module import) so importing headroom.proxy.server# in tests or library contexts does not silently attach a RotatingFileHandler# to the user's live proxy log. Multi-worker processes add their PID so- # same-port workers never share a RotatingFileHandler target.- _setup_file_logging(- config.port,- process_id=os.getpid() if config.worker_processes > 1 else None,- )+ # same-port workers never share a RotatingFileHandler target. Stateless+ # mode must not create a log directory or file.+ if not config.stateless:+ _setup_file_logging(+ config.port,+ process_id=os.getpid() if config.worker_processes > 1 else None,+ )# Defensive re-apply of file-backed settings for embedded/non-CLI callers# that construct the app without going through the `headroom` CLI entrypointdiff --git a/headroom/savings_ledger.py b/headroom/savings_ledger.pyindex 823efa445..b959f7c5d 100644--- a/headroom/savings_ledger.py+++ b/headroom/savings_ledger.py@@ -306,6 +306,9 @@ def record_savings_event(zero-saving request is skipped exactly as before."""+ if _paths.process_is_stateless():+ return False+try:before = max(int(tokens_before), 0)after = max(int(tokens_after), 0)diff --git a/headroom/telemetry/session.py b/headroom/telemetry/session.pyindex b4bd6b87f..fec83529e 100644--- a/headroom/telemetry/session.py+++ b/headroom/telemetry/session.py@@ -604,6 +604,11 @@ def install_id() -> str:# outside the lock in read_install_id().if _install_id is not None:return _install_id+ from headroom import paths++ if paths.process_is_stateless():+ _install_id = uuid.uuid4().hex+ return _install_idpath = _install_id_path()_install_id = uuid.uuid4().hextry:diff --git a/tests/test_cli_proxy_improvements.py b/tests/test_cli_proxy_improvements.pyindex aa5d58eb8..996d43bd5 100644--- a/tests/test_cli_proxy_improvements.py+++ b/tests/test_cli_proxy_improvements.py@@ -303,22 +303,16 @@ class TestMissingProxyDepsError:def test_proxy_command_exits_when_mcp_missing(self, runner: CliRunner, monkeypatch: pytest.MonkeyPatch) -> None:- import builtins-- real_import = builtins.__import__-- def fake_import(- name: str,- globals: dict | None = None,- locals: dict | None = None,- fromlist: tuple = (),- level: int = 0,- ):- if name == "mcp":- raise ImportError("No module named 'mcp'")- return real_import(name, globals, locals, fromlist, level)-- monkeypatch.setattr(builtins, "__import__", fake_import)+ from importlib.util import find_spec++ def fake_find_spec(name: str) -> object:+ return None if name == "mcp" else find_spec(name)++ monkeypatch.setattr("headroom.cli.proxy.find_spec", fake_find_spec)+ monkeypatch.setattr(+ "uvicorn.run",+ lambda *args, **kwargs: pytest.fail("missing dependencies must not start a server"),+ )result = runner.invoke(main, ["proxy"])assert result.exit_code == 1, result.outputassert "pip install headroom-ai[proxy]" in result.output@@ -328,24 +322,12 @@ class TestMissingProxyDepsError:def test_ensure_proxy_dependencies_exits_when_fastapi_missing(self, monkeypatch: pytest.MonkeyPatch) -> None:- import builtins-from headroom.cli.proxy import ensure_proxy_dependencies- real_import = builtins.__import__-- def fake_import(- name: str,- globals: dict | None = None,- locals: dict | None = None,- fromlist: tuple = (),- level: int = 0,- ):- if name == "fastapi":- raise ImportError("No module named 'fastapi'")- return real_import(name, globals, locals, fromlist, level)-- monkeypatch.setattr(builtins, "__import__", fake_import)+ monkeypatch.setattr(+ "headroom.cli.proxy.find_spec",+ lambda name: None if name == "fastapi" else object(),+ )with pytest.raises(SystemExit) as exc_info:ensure_proxy_dependencies()diff --git a/tests/test_litellm_optional.py b/tests/test_litellm_optional.pyindex 1cc702ff8..f9acb87ab 100644--- a/tests/test_litellm_optional.py+++ b/tests/test_litellm_optional.py@@ -78,14 +78,17 @@ def test_proxy_starts_without_watchdog(monkeypatch: pytest.MonkeyPatch) -> None:requested: list[str] = []- def fake_import(name: str) -> object:+ from importlib.machinery import ModuleSpec++ def fake_find_spec(name: str) -> ModuleSpec | None:requested.append(name)if name == "watchdog":- raise ImportError("No module named 'watchdog'")- return object()+ return None+ return ModuleSpec(name, loader=None)- monkeypatch.setattr(proxy, "import_module", fake_import)+ monkeypatch.setattr(proxy, "find_spec", fake_find_spec)proxy.ensure_proxy_dependencies()+ assert "fastapi" in requestedassert "watchdog" not in requesteddiff --git a/tests/test_savings_ledger.py b/tests/test_savings_ledger.pyindex 41b5b1e73..02c5ff2c3 100644--- a/tests/test_savings_ledger.py+++ b/tests/test_savings_ledger.py@@ -72,6 +72,13 @@ def test_zero_or_negative_savings_not_recorded(monkeypatch, tmp_path):assert L.aggregate_savings().lifetime["calls"] == 0+def test_stateless_mode_does_not_create_ledger(monkeypatch, tmp_path):+ path = _events_env(monkeypatch, tmp_path)+ monkeypatch.setenv("HEADROOM_STATELESS", "true")+ assert L.record_savings_event(tokens_before=100, tokens_after=50) is False+ assert not path.exists()++def test_breakdowns_aggregate_by_dimension(monkeypatch, tmp_path):_events_env(monkeypatch, tmp_path)L.record_savings_event(tokens_before=1000, tokens_after=300, model=None, client="claude-code")diff --git a/tests/test_stateless_writers.py b/tests/test_stateless_writers.pyindex d7008f2da..97c21e5ca 100644--- a/tests/test_stateless_writers.py+++ b/tests/test_stateless_writers.py@@ -53,6 +53,18 @@ def test_process_stateless_env(monkeypatch, value, expected):assert paths.process_is_stateless() is expected+def test_install_id_stays_in_memory_when_stateless(tmp_path, monkeypatch):+ from headroom.telemetry import session++ workspace = tmp_path / "state"+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace))+ monkeypatch.setattr(session, "_install_id", None)+ paths.set_process_stateless(True)++ assert len(session.install_id()) == 32+ assert not workspace.exists()++# ---- output-savings recorder ----------------------------------------------@@ -79,14 +91,15 @@ def test_output_savings_flush_persists_when_not_stateless(tmp_path, monkeypatch)def test_memory_disabled_under_stateless(tmp_path, monkeypatch):"""A stateless proxy with --memory must not initialize memory or write a DB."""+ workspace = tmp_path / "state"monkeypatch.chdir(tmp_path)- monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace))from headroom.proxy.server import ProxyConfig, create_appapp = create_app(ProxyConfig(memory_enabled=True, stateless=True))proxy = app.state.proxyassert proxy.memory_handler is None- assert not (tmp_path / ".headroom" / "memory.db").exists()+ assert not workspace.exists()# ---- fastembed model pinning ----------------------------------------------