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.

perf(proxy): avoid eager dependency imports (#3546)

Syamsul Alam59bd482fa166
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 4b429590d..a04d7fd18 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -5,7 +5,7 @@ import os
import platform
import sys
import warnings
-from importlib import import_module
+from importlib.util import find_spec
from pathlib import Path
from 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.py
index 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 entrypoint
diff --git a/headroom/savings_ledger.py b/headroom/savings_ledger.py
index 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.py
index 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_id
path = _install_id_path()
_install_id = uuid.uuid4().hex
try:
diff --git a/tests/test_cli_proxy_improvements.py b/tests/test_cli_proxy_improvements.py
index 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.output
assert "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.py
index 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 requested
assert "watchdog" not in requested
diff --git a/tests/test_savings_ledger.py b/tests/test_savings_ledger.py
index 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.py
index 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_app
app = create_app(ProxyConfig(memory_enabled=True, stateless=True))
proxy = app.state.proxy
assert proxy.memory_handler is None
- assert not (tmp_path / ".headroom" / "memory.db").exists()
+ assert not workspace.exists()
# ---- fastembed model pinning ----------------------------------------------