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: restore lazy import compatibility
JerrettDavisf45822c17872
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex 1336c7898..c7061b3f1 100644--- a/headroom/__init__.py+++ b/headroom/__init__.py@@ -73,6 +73,7 @@ from __future__ import annotationsfrom importlib import import_modulefrom ._version import __version__ # noqa: F401+from .compress import CompressResult, compress__all__ = [# Main client@@ -256,7 +257,6 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {"reset_otel_metrics": ("headroom.observability", "reset_otel_metrics"),# One-function API"compress": ("headroom.compress", "compress"),- "CompressResult": ("headroom.compress", "CompressResult"),# Hooks"CompressionHooks": ("headroom.hooks", "CompressionHooks"),"CompressContext": ("headroom.hooks", "CompressContext"),diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.pyindex 7e6536e9d..6965152d9 100644--- a/headroom/proxy/cost.py+++ b/headroom/proxy/cost.py@@ -20,18 +20,24 @@ if TYPE_CHECKING:from headroom.proxy.prometheus_metrics import PrometheusMetricsLITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None+litellm: Any | None = Nonedef _get_litellm_module() -> Any | None:"""Import LiteLLM only when pricing data is actually requested."""+ global litellm++ if litellm is not None:+ return litellmif not LITELLM_AVAILABLE:return Nonetry:- import litellm+ import litellm as imported_litellmexcept ImportError:return None+ litellm = imported_litellmreturn litellmlogger = logging.getLogger("headroom.proxy")diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pyindex 295bad39d..b41979fc8 100644--- a/headroom/proxy/savings_tracker.py+++ b/headroom/proxy/savings_tracker.py@@ -30,18 +30,24 @@ DEFAULT_MAX_HISTORY_AGE_DAYS = 365DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES = 60LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None+litellm: Any | None = Nonedef _get_litellm_module() -> Any | None:"""Import LiteLLM only when cost metadata is requested."""+ global litellm++ if litellm is not None:+ return litellmif not LITELLM_AVAILABLE:return Nonetry:- import litellm+ import litellm as imported_litellmexcept ImportError:return None+ litellm = imported_litellmreturn litellmdiff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex ea4143c6f..3e61e046e 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -149,6 +149,11 @@ logging.basicConfig()logger = logging.getLogger("headroom.proxy")+# Preserve module-level backend symbols for tests and patch-based integrations+# while still importing the actual backend implementations lazily at runtime.+AnyLLMBackend = None+LiteLLMBackend = None+# Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis_setup_file_logging()@@ -350,7 +355,11 @@ class HeadroomProxy(if backend == "anyllm" or backend.startswith("anyllm-"):provider = config.anyllm_providertry:- from headroom.backends.anyllm import AnyLLMBackend+ global AnyLLMBackend+ if AnyLLMBackend is None:+ from headroom.backends.anyllm import AnyLLMBackend as ImportedAnyLLMBackend++ AnyLLMBackend = ImportedAnyLLMBackendself.anthropic_backend = AnyLLMBackend(provider=provider)logger.info(f"any-llm backend enabled (provider={provider})")@@ -366,7 +375,11 @@ class HeadroomProxy(provider = backend.replace("litellm-", "")try:- from headroom.backends.litellm import LiteLLMBackend+ global LiteLLMBackend+ if LiteLLMBackend is None:+ from headroom.backends.litellm import LiteLLMBackend as ImportedLiteLLMBackend++ LiteLLMBackend = ImportedLiteLLMBackendself.anthropic_backend = LiteLLMBackend(provider=provider,