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: restore lazy import compatibility

JerrettDavisf45822c17872
diff --git a/headroom/__init__.py b/headroom/__init__.py
index 1336c7898..c7061b3f1 100644
--- a/headroom/__init__.py
+++ b/headroom/__init__.py
@@ -73,6 +73,7 @@ from __future__ import annotations
from importlib import import_module
from ._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.py
index 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 PrometheusMetrics
LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
+litellm: Any | None = None
def _get_litellm_module() -> Any | None:
"""Import LiteLLM only when pricing data is actually requested."""
+ global litellm
+
+ if litellm is not None:
+ return litellm
if not LITELLM_AVAILABLE:
return None
try:
- import litellm
+ import litellm as imported_litellm
except ImportError:
return None
+ litellm = imported_litellm
return litellm
logger = logging.getLogger("headroom.proxy")
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index 295bad39d..b41979fc8 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -30,18 +30,24 @@ DEFAULT_MAX_HISTORY_AGE_DAYS = 365
DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES = 60
LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
+litellm: Any | None = None
def _get_litellm_module() -> Any | None:
"""Import LiteLLM only when cost metadata is requested."""
+ global litellm
+
+ if litellm is not None:
+ return litellm
if not LITELLM_AVAILABLE:
return None
try:
- import litellm
+ import litellm as imported_litellm
except ImportError:
return None
+ litellm = imported_litellm
return litellm
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 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_provider
try:
- from headroom.backends.anyllm import AnyLLMBackend
+ global AnyLLMBackend
+ if AnyLLMBackend is None:
+ from headroom.backends.anyllm import AnyLLMBackend as ImportedAnyLLMBackend
+
+ AnyLLMBackend = ImportedAnyLLMBackend
self.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 = ImportedLiteLLMBackend
self.anthropic_backend = LiteLLMBackend(
provider=provider,