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: lazy-load proxy startup dependencies

JerrettDavisf63cfe7a1e8f
diff --git a/headroom/__init__.py b/headroom/__init__.py
index e52c4eba0..1336c7898 100644
--- a/headroom/__init__.py
+++ b/headroom/__init__.py
@@ -68,106 +68,11 @@ Error Handling:
For more examples, see https://github.com/headroom-sdk/headroom/tree/main/examples
"""
-from .cache import (
- AnthropicCacheOptimizer,
- BaseCacheOptimizer,
- CacheConfig,
- CacheMetrics,
- CacheOptimizerRegistry,
- CacheResult,
- CacheStrategy,
- GoogleCacheOptimizer,
- OpenAICacheOptimizer,
- OptimizationContext,
- SemanticCache,
- SemanticCacheLayer,
-)
-from .client import HeadroomClient
-from .config import (
- Block,
- CacheAlignerConfig,
- CacheOptimizerConfig,
- CachePrefixMetrics,
- DiffArtifact,
- HeadroomConfig,
- HeadroomMode,
- RelevanceScorerConfig,
- RequestMetrics,
- RollingWindowConfig,
- SimulationResult,
- SmartCrusherConfig,
- ToolCrusherConfig,
- TransformDiff,
- TransformResult,
- WasteSignals,
-)
-from .exceptions import (
- CacheError,
- CompressionError,
- ConfigurationError,
- HeadroomError,
- ProviderError,
- StorageError,
- TokenizationError,
- TransformError,
- ValidationError,
-)
+from __future__ import annotations
-# Memory module - optional (requires numpy, hnswlib, etc.)
-try:
- from .memory import (
- EmbedderBackend,
- HierarchicalMemory,
- Memory,
- MemoryConfig,
- ScopeLevel,
- with_memory,
- )
-except ImportError:
- EmbedderBackend = None # type: ignore[assignment,misc]
- HierarchicalMemory = None # type: ignore[assignment,misc]
- Memory = None # type: ignore[assignment,misc]
- MemoryConfig = None # type: ignore[assignment,misc]
- ScopeLevel = None # type: ignore[assignment,misc]
- with_memory = None # type: ignore[assignment]
-
-from .observability import (
- HeadroomOtelMetrics,
- HeadroomTracer,
- LangfuseTracingConfig,
- OTelMetricsConfig,
- configure_langfuse_tracing,
- configure_otel_metrics,
- get_headroom_tracer,
- get_langfuse_tracing_status,
- get_otel_metrics,
- get_otel_metrics_status,
- reset_headroom_tracing,
- reset_otel_metrics,
-)
-from .providers import AnthropicProvider, OpenAIProvider, Provider, TokenCounter
-
-# Relevance scoring - BM25 always available, embedding requires sentence-transformers
-from .relevance import (
- BM25Scorer,
- EmbeddingScorer,
- HybridScorer,
- RelevanceScore,
- RelevanceScorer,
- create_scorer,
- embedding_available,
-)
-from .reporting import generate_report
-from .tokenizer import Tokenizer, count_tokens_messages, count_tokens_text
-from .transforms import (
- CacheAligner,
- RollingWindow,
- SmartCrusher,
- ToolCrusher,
- TransformPipeline,
-)
+from importlib import import_module
-__version__ = "0.5.21"
+from ._version import __version__ # noqa: F401
__all__ = [
# Main client
@@ -268,9 +173,128 @@ __all__ = [
"SharedContext",
]
-# One-function compression API
-from headroom.compress import CompressResult, compress # noqa: E402
-from headroom.hooks import CompressContext, CompressEvent, CompressionHooks # noqa: E402
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+ # Main client
+ "HeadroomClient": ("headroom.client", "HeadroomClient"),
+ # Providers
+ "Provider": ("headroom.providers", "Provider"),
+ "TokenCounter": ("headroom.providers", "TokenCounter"),
+ "OpenAIProvider": ("headroom.providers", "OpenAIProvider"),
+ "AnthropicProvider": ("headroom.providers", "AnthropicProvider"),
+ # Exceptions
+ "HeadroomError": ("headroom.exceptions", "HeadroomError"),
+ "ConfigurationError": ("headroom.exceptions", "ConfigurationError"),
+ "ProviderError": ("headroom.exceptions", "ProviderError"),
+ "StorageError": ("headroom.exceptions", "StorageError"),
+ "CompressionError": ("headroom.exceptions", "CompressionError"),
+ "TokenizationError": ("headroom.exceptions", "TokenizationError"),
+ "CacheError": ("headroom.exceptions", "CacheError"),
+ "ValidationError": ("headroom.exceptions", "ValidationError"),
+ "TransformError": ("headroom.exceptions", "TransformError"),
+ # Config
+ "HeadroomConfig": ("headroom.config", "HeadroomConfig"),
+ "HeadroomMode": ("headroom.config", "HeadroomMode"),
+ "ToolCrusherConfig": ("headroom.config", "ToolCrusherConfig"),
+ "SmartCrusherConfig": ("headroom.config", "SmartCrusherConfig"),
+ "CacheAlignerConfig": ("headroom.config", "CacheAlignerConfig"),
+ "CacheOptimizerConfig": ("headroom.config", "CacheOptimizerConfig"),
+ "RollingWindowConfig": ("headroom.config", "RollingWindowConfig"),
+ "RelevanceScorerConfig": ("headroom.config", "RelevanceScorerConfig"),
+ # Data models
+ "Block": ("headroom.config", "Block"),
+ "CachePrefixMetrics": ("headroom.config", "CachePrefixMetrics"),
+ "DiffArtifact": ("headroom.config", "DiffArtifact"),
+ "RequestMetrics": ("headroom.config", "RequestMetrics"),
+ "SimulationResult": ("headroom.config", "SimulationResult"),
+ "TransformDiff": ("headroom.config", "TransformDiff"),
+ "TransformResult": ("headroom.config", "TransformResult"),
+ "WasteSignals": ("headroom.config", "WasteSignals"),
+ # Transforms
+ "ToolCrusher": ("headroom.transforms", "ToolCrusher"),
+ "SmartCrusher": ("headroom.transforms", "SmartCrusher"),
+ "CacheAligner": ("headroom.transforms", "CacheAligner"),
+ "RollingWindow": ("headroom.transforms", "RollingWindow"),
+ "TransformPipeline": ("headroom.transforms", "TransformPipeline"),
+ # Cache optimizers
+ "BaseCacheOptimizer": ("headroom.cache", "BaseCacheOptimizer"),
+ "CacheConfig": ("headroom.cache", "CacheConfig"),
+ "CacheMetrics": ("headroom.cache", "CacheMetrics"),
+ "CacheResult": ("headroom.cache", "CacheResult"),
+ "CacheStrategy": ("headroom.cache", "CacheStrategy"),
+ "OptimizationContext": ("headroom.cache", "OptimizationContext"),
+ "CacheOptimizerRegistry": ("headroom.cache", "CacheOptimizerRegistry"),
+ "AnthropicCacheOptimizer": ("headroom.cache", "AnthropicCacheOptimizer"),
+ "OpenAICacheOptimizer": ("headroom.cache", "OpenAICacheOptimizer"),
+ "GoogleCacheOptimizer": ("headroom.cache", "GoogleCacheOptimizer"),
+ "SemanticCache": ("headroom.cache", "SemanticCache"),
+ "SemanticCacheLayer": ("headroom.cache", "SemanticCacheLayer"),
+ # Relevance scoring
+ "RelevanceScore": ("headroom.relevance", "RelevanceScore"),
+ "RelevanceScorer": ("headroom.relevance", "RelevanceScorer"),
+ "BM25Scorer": ("headroom.relevance", "BM25Scorer"),
+ "EmbeddingScorer": ("headroom.relevance", "EmbeddingScorer"),
+ "HybridScorer": ("headroom.relevance", "HybridScorer"),
+ "create_scorer": ("headroom.relevance", "create_scorer"),
+ "embedding_available": ("headroom.relevance", "embedding_available"),
+ # Utilities
+ "Tokenizer": ("headroom.tokenizer", "Tokenizer"),
+ "count_tokens_text": ("headroom.tokenizer", "count_tokens_text"),
+ "count_tokens_messages": ("headroom.tokenizer", "count_tokens_messages"),
+ "generate_report": ("headroom.reporting", "generate_report"),
+ # Observability
+ "HeadroomOtelMetrics": ("headroom.observability", "HeadroomOtelMetrics"),
+ "HeadroomTracer": ("headroom.observability", "HeadroomTracer"),
+ "LangfuseTracingConfig": ("headroom.observability", "LangfuseTracingConfig"),
+ "OTelMetricsConfig": ("headroom.observability", "OTelMetricsConfig"),
+ "configure_otel_metrics": ("headroom.observability", "configure_otel_metrics"),
+ "configure_langfuse_tracing": ("headroom.observability", "configure_langfuse_tracing"),
+ "get_headroom_tracer": ("headroom.observability", "get_headroom_tracer"),
+ "get_langfuse_tracing_status": ("headroom.observability", "get_langfuse_tracing_status"),
+ "get_otel_metrics": ("headroom.observability", "get_otel_metrics"),
+ "get_otel_metrics_status": ("headroom.observability", "get_otel_metrics_status"),
+ "reset_headroom_tracing": ("headroom.observability", "reset_headroom_tracing"),
+ "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"),
+ "CompressEvent": ("headroom.hooks", "CompressEvent"),
+ # Shared context
+ "SharedContext": ("headroom.shared_context", "SharedContext"),
+}
+
+_OPTIONAL_EXPORTS = {
+ "with_memory": ("headroom.memory", "with_memory"),
+ "Memory": ("headroom.memory", "Memory"),
+ "ScopeLevel": ("headroom.memory", "ScopeLevel"),
+ "HierarchicalMemory": ("headroom.memory", "HierarchicalMemory"),
+ "MemoryConfig": ("headroom.memory", "MemoryConfig"),
+ "EmbedderBackend": ("headroom.memory", "EmbedderBackend"),
+}
+
+
+def __getattr__(name: str):
+ module_attr = _LAZY_EXPORTS.get(name)
+ if module_attr is not None:
+ module_name, attr_name = module_attr
+ value = getattr(import_module(module_name), attr_name)
+ globals()[name] = value
+ return value
+
+ optional_module_attr = _OPTIONAL_EXPORTS.get(name)
+ if optional_module_attr is not None:
+ module_name, attr_name = optional_module_attr
+ try:
+ value = getattr(import_module(module_name), attr_name)
+ except ImportError:
+ value = None
+ globals()[name] = value
+ return value
+
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
-# Shared context for multi-agent workflows
-from headroom.shared_context import SharedContext # noqa: E402
+def __dir__() -> list[str]:
+ return sorted(set(globals()) | set(__all__))
diff --git a/headroom/_version.py b/headroom/_version.py
new file mode 100644
index 000000000..e2692daf2
--- /dev/null
+++ b/headroom/_version.py
@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "0.5.21"
diff --git a/headroom/cache/__init__.py b/headroom/cache/__init__.py
index d92c16b47..f9899deff 100644
--- a/headroom/cache/__init__.py
+++ b/headroom/cache/__init__.py
@@ -1,54 +1,8 @@
-"""
-Headroom Cache Optimization Module.
+"""Headroom cache optimization exports."""
-This module provides a plugin-based architecture for cache optimization
-across different LLM providers. Each provider has different caching
-mechanisms and this module abstracts those differences.
+from __future__ import annotations
-Provider Caching Differences:
-- Anthropic: Explicit cache_control blocks, 90% savings, 5-min TTL
-- OpenAI: Automatic prefix caching, 50% savings, no user control
-- Google: Separate CachedContent API, 75% savings + storage costs
-
-Usage:
- from headroom.cache import CacheOptimizerRegistry, SemanticCacheLayer
-
- # Get provider-specific optimizer
- optimizer = CacheOptimizerRegistry.get("anthropic")
- result = optimizer.optimize(messages, context)
-
- # With semantic caching layer
- semantic = SemanticCacheLayer(optimizer, similarity_threshold=0.95)
- result = semantic.process(messages, context)
-
- # Register custom optimizer
- CacheOptimizerRegistry.register("my-provider", MyOptimizer)
-"""
-
-from .anthropic import AnthropicCacheOptimizer
-from .base import (
- BaseCacheOptimizer,
- CacheBreakpoint,
- CacheConfig,
- CacheMetrics,
- CacheOptimizer,
- CacheResult,
- CacheStrategy,
- OptimizationContext,
-)
-from .compression_cache import CompressionCache
-from .dynamic_detector import (
- DetectorConfig,
- DynamicCategory,
- DynamicContentDetector,
- DynamicSpan,
- detect_dynamic_content,
-)
-from .google import GoogleCacheOptimizer
-from .openai import OpenAICacheOptimizer
-from .prefix_tracker import FreezeStats, PrefixCacheTracker, PrefixFreezeConfig, SessionTrackerStore
-from .registry import CacheOptimizerRegistry
-from .semantic import SemanticCache, SemanticCacheLayer
+from importlib import import_module
__all__ = [
# Base types
@@ -83,3 +37,56 @@ __all__ = [
"FreezeStats",
"SessionTrackerStore",
]
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+ # Base types
+ "BaseCacheOptimizer": ("headroom.cache.base", "BaseCacheOptimizer"),
+ "CacheBreakpoint": ("headroom.cache.base", "CacheBreakpoint"),
+ "CacheConfig": ("headroom.cache.base", "CacheConfig"),
+ "CacheMetrics": ("headroom.cache.base", "CacheMetrics"),
+ "CacheOptimizer": ("headroom.cache.base", "CacheOptimizer"),
+ "CacheResult": ("headroom.cache.base", "CacheResult"),
+ "CacheStrategy": ("headroom.cache.base", "CacheStrategy"),
+ "OptimizationContext": ("headroom.cache.base", "OptimizationContext"),
+ # Dynamic content detection
+ "DetectorConfig": ("headroom.cache.dynamic_detector", "DetectorConfig"),
+ "DynamicCategory": ("headroom.cache.dynamic_detector", "DynamicCategory"),
+ "DynamicContentDetector": ("headroom.cache.dynamic_detector", "DynamicContentDetector"),
+ "DynamicSpan": ("headroom.cache.dynamic_detector", "DynamicSpan"),
+ "detect_dynamic_content": ("headroom.cache.dynamic_detector", "detect_dynamic_content"),
+ # Registry
+ "CacheOptimizerRegistry": ("headroom.cache.registry", "CacheOptimizerRegistry"),
+ # Provider implementations
+ "AnthropicCacheOptimizer": ("headroom.cache.anthropic", "AnthropicCacheOptimizer"),
+ "OpenAICacheOptimizer": ("headroom.cache.openai", "OpenAICacheOptimizer"),
+ "GoogleCacheOptimizer": ("headroom.cache.google", "GoogleCacheOptimizer"),
+ # Semantic caching
+ "SemanticCacheLayer": ("headroom.cache.semantic", "SemanticCacheLayer"),
+ "SemanticCache": ("headroom.cache.semantic", "SemanticCache"),
+ # Compression cache
+ "CompressionCache": ("headroom.cache.compression_cache", "CompressionCache"),
+ # Prefix cache tracking
+ "PrefixCacheTracker": ("headroom.cache.prefix_tracker", "PrefixCacheTracker"),
+ "PrefixFreezeConfig": ("headroom.cache.prefix_tracker", "PrefixFreezeConfig"),
+ "FreezeStats": ("headroom.cache.prefix_tracker", "FreezeStats"),
+ "SessionTrackerStore": ("headroom.cache.prefix_tracker", "SessionTrackerStore"),
+}
+
+
+def __getattr__(name: str) -> object:
+ if name == "__path__":
+ raise AttributeError(name)
+
+ try:
+ module_name, attr_name = _LAZY_EXPORTS[name]
+ except KeyError as exc:
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+ module = import_module(module_name)
+ value = getattr(module, attr_name)
+ globals()[name] = value
+ return value
+
+
+def __dir__() -> list[str]:
+ return sorted(set(globals()) | set(__all__))
diff --git a/headroom/cli/main.py b/headroom/cli/main.py
index acc84ca97..539ff4a4e 100644
--- a/headroom/cli/main.py
+++ b/headroom/cli/main.py
@@ -6,7 +6,7 @@ import click
def get_version() -> str:
"""Get the current version."""
try:
- from headroom import __version__
+ from headroom._version import __version__
return __version__
except ImportError:
diff --git a/headroom/models/__init__.py b/headroom/models/__init__.py
index 9a6d25f45..3ada5da4f 100644
--- a/headroom/models/__init__.py
+++ b/headroom/models/__init__.py
@@ -1,47 +1,8 @@
-"""Model registry and capabilities database.
-
-Provides a centralized registry of LLM models with their capabilities,
-context limits, pricing, and provider information.
-
-Also provides MLModelRegistry for sharing ML model instances (sentence
-transformers, SIGLIP, spaCy) to avoid loading the same model multiple times.
-
-Usage:
- from headroom.models import ModelRegistry, get_model_info
-
- # Get info about a model
- info = get_model_info("gpt-4o")
- print(f"Context: {info.context_window}")
- print(f"Provider: {info.provider}")
-
- # List all models from a provider
- models = ModelRegistry.list_models(provider="openai")
-
- # Register a custom model
- ModelRegistry.register(
- "my-custom-model",
- provider="custom",
- context_window=32000,
- )
-
- # Get shared ML model instances
- from headroom.models import MLModelRegistry
- model = MLModelRegistry.get_sentence_transformer()
-"""
-
-from .ml_models import (
- MLModelRegistry,
- get_sentence_transformer,
- get_siglip,
- get_spacy,
-)
-from .registry import (
- ModelInfo,
- ModelRegistry,
- get_model_info,
- list_models,
- register_model,
-)
+"""Model registry and shared ML model helpers."""
+
+from __future__ import annotations
+
+from importlib import import_module
__all__ = [
# LLM Registry
@@ -56,3 +17,36 @@ __all__ = [
"get_siglip",
"get_spacy",
]
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+ # LLM registry
+ "ModelRegistry": ("headroom.models.registry", "ModelRegistry"),
+ "ModelInfo": ("headroom.models.registry", "ModelInfo"),
+ "get_model_info": ("headroom.models.registry", "get_model_info"),
+ "list_models": ("headroom.models.registry", "list_models"),
+ "register_model": ("headroom.models.registry", "register_model"),
+ # ML model registry
+ "MLModelRegistry": ("headroom.models.ml_models", "MLModelRegistry"),
+ "get_sentence_transformer": ("headroom.models.ml_models", "get_sentence_transformer"),
+ "get_siglip": ("headroom.models.ml_models", "get_siglip"),
+ "get_spacy": ("headroom.models.ml_models", "get_spacy"),
+}
+
+
+def __getattr__(name: str) -> object:
+ if name == "__path__":
+ raise AttributeError(name)
+
+ try:
+ module_name, attr_name = _LAZY_EXPORTS[name]
+ except KeyError as exc:
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+ module = import_module(module_name)
+ value = getattr(module, attr_name)
+ globals()[name] = value
+ return value
+
+
+def __dir__() -> list[str]:
+ return sorted(set(globals()) | set(__all__))
diff --git a/headroom/providers/__init__.py b/headroom/providers/__init__.py
index 105c87b54..7f0268e5a 100644
--- a/headroom/providers/__init__.py
+++ b/headroom/providers/__init__.py
@@ -1,39 +1,8 @@
-"""Provider abstractions for Headroom SDK.
-
-Providers encapsulate model-specific behavior like tokenization,
-context limits, and cost estimation.
-
-Supported Providers:
-- OpenAIProvider: Native OpenAI models (GPT-4o, o1, etc.)
-- AnthropicProvider: Claude models
-- GoogleProvider: Google Gemini models
-- CohereProvider: Cohere Command models
-- OpenAICompatibleProvider: Universal provider for any OpenAI-compatible API
- (Ollama, vLLM, Together, Groq, Fireworks, LM Studio, etc.)
-- LiteLLMProvider: Universal provider via LiteLLM (100+ providers)
-"""
-
-from .anthropic import AnthropicProvider
-from .base import Provider, TokenCounter
-from .cohere import CohereProvider
-from .google import GoogleProvider
-from .litellm import (
- LiteLLMProvider,
- create_litellm_provider,
- is_litellm_available,
-)
-from .openai import OpenAIProvider
-from .openai_compatible import (
- ModelCapabilities,
- OpenAICompatibleProvider,
- create_anyscale_provider,
- create_fireworks_provider,
- create_groq_provider,
- create_lmstudio_provider,
- create_ollama_provider,
- create_together_provider,
- create_vllm_provider,
-)
+"""Provider abstractions for Headroom SDK."""
+
+from __future__ import annotations
+
+from importlib import import_module
__all__ = [
# Base
@@ -59,3 +28,62 @@ __all__ = [
"create_lmstudio_provider",
"create_litellm_provider",
]
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+ # Base
+ "Provider": ("headroom.providers.base", "Provider"),
+ "TokenCounter": ("headroom.providers.base", "TokenCounter"),
+ # Native providers
+ "OpenAIProvider": ("headroom.providers.openai", "OpenAIProvider"),
+ "AnthropicProvider": ("headroom.providers.anthropic", "AnthropicProvider"),
+ "GoogleProvider": ("headroom.providers.google", "GoogleProvider"),
+ "CohereProvider": ("headroom.providers.cohere", "CohereProvider"),
+ # Universal providers
+ "OpenAICompatibleProvider": (
+ "headroom.providers.openai_compatible",
+ "OpenAICompatibleProvider",
+ ),
+ "ModelCapabilities": ("headroom.providers.openai_compatible", "ModelCapabilities"),
+ "LiteLLMProvider": ("headroom.providers.litellm", "LiteLLMProvider"),
+ "is_litellm_available": ("headroom.providers.litellm", "is_litellm_available"),
+ # Factory functions
+ "create_ollama_provider": ("headroom.providers.openai_compatible", "create_ollama_provider"),
+ "create_together_provider": (
+ "headroom.providers.openai_compatible",
+ "create_together_provider",
+ ),
+ "create_groq_provider": ("headroom.providers.openai_compatible", "create_groq_provider"),
+ "create_fireworks_provider": (
+ "headroom.providers.openai_compatible",
+ "create_fireworks_provider",
+ ),
+ "create_anyscale_provider": (
+ "headroom.providers.openai_compatible",
+ "create_anyscale_provider",
+ ),
+ "create_vllm_provider": ("headroom.providers.openai_compatible", "create_vllm_provider"),
+ "create_lmstudio_provider": (
+ "headroom.providers.openai_compatible",
+ "create_lmstudio_provider",
+ ),
+ "create_litellm_provider": ("headroom.providers.litellm", "create_litellm_provider"),
+}
+
+
+def __getattr__(name: str) -> object:
+ if name == "__path__":
+ raise AttributeError(name)
+
+ try:
+ module_name, attr_name = _LAZY_EXPORTS[name]
+ except KeyError as exc:
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+ module = import_module(module_name)
+ value = getattr(module, attr_name)
+ globals()[name] = value
+ return value
+
+
+def __dir__() -> list[str]:
+ return sorted(set(globals()) | set(__all__))
diff --git a/headroom/providers/anthropic.py b/headroom/providers/anthropic.py
index b8f41f9eb..b84418667 100644
--- a/headroom/providers/anthropic.py
+++ b/headroom/providers/anthropic.py
@@ -16,6 +16,7 @@ Usage:
"""
import json
+import importlib.util
import logging
import os
import warnings
@@ -24,16 +25,21 @@ from typing import Any, cast
from .base import Provider, TokenCounter
-# Check if LiteLLM is available for pricing and context limits
-try:
- import litellm
- from litellm import get_model_info as litellm_get_model_info
+LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
- LITELLM_AVAILABLE = True
-except ImportError:
- LITELLM_AVAILABLE = False
- litellm = None # type: ignore[assignment]
- litellm_get_model_info = None # type: ignore[assignment]
+
+def _get_litellm_clients() -> tuple[Any | None, Any | None]:
+ """Import LiteLLM only when pricing/context metadata is needed."""
+ if not LITELLM_AVAILABLE:
+ return None, None
+
+ try:
+ import litellm
+ from litellm import get_model_info as litellm_get_model_info
+ except ImportError:
+ return None, None
+
+ return litellm, litellm_get_model_info
logger = logging.getLogger(__name__)
@@ -492,7 +498,8 @@ class AnthropicProvider(Provider):
return limit
# Try LiteLLM for context limit
- if LITELLM_AVAILABLE and litellm_get_model_info is not None:
+ _, litellm_get_model_info = _get_litellm_clients()
+ if litellm_get_model_info is not None:
try:
info = litellm_get_model_info(model)
if info:
@@ -559,7 +566,8 @@ class AnthropicProvider(Provider):
Tries LiteLLM first for up-to-date pricing, falls back to manual pricing.
"""
# Try LiteLLM first for cost estimation
- if LITELLM_AVAILABLE and litellm is not None:
+ litellm, litellm_get_model_info = _get_litellm_clients()
+ if litellm is not None:
try:
cost = litellm.completion_cost(
model=model,
diff --git a/headroom/providers/openai.py b/headroom/providers/openai.py
index 78792751d..bff476a1f 100644
--- a/headroom/providers/openai.py
+++ b/headroom/providers/openai.py
@@ -7,6 +7,7 @@ Cost estimates are APPROXIMATE - always verify against your actual billing.
from __future__ import annotations
import json
+import importlib.util
import logging
import os
import warnings
@@ -34,12 +35,20 @@ try:
except ImportError:
TIKTOKEN_AVAILABLE = False
-try:
- import litellm
+LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
- LITELLM_AVAILABLE = True
-except ImportError:
- LITELLM_AVAILABLE = False
+
+def _get_litellm_module() -> Any | None:
+ """Import LiteLLM only when pricing/context metadata is needed."""
+ if not LITELLM_AVAILABLE:
+ return None
+
+ try:
+ import litellm
+ except ImportError:
+ return None
+
+ return litellm
# OpenAI model to tiktoken encoding mappings
@@ -423,7 +432,8 @@ class OpenAIProvider(Provider):
Never raises an exception - uses sensible defaults for unknown models.
"""
# Try LiteLLM first
- if LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is not None:
try:
info = litellm.get_model_info(model)
if info and "max_input_tokens" in info:
@@ -495,7 +505,8 @@ class OpenAIProvider(Provider):
Estimated cost in USD, or None if pricing unknown.
"""
# Try LiteLLM first (most up-to-date pricing)
- if LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is not None:
try:
# LiteLLM uses per-token pricing, returns total cost
cost = litellm.completion_cost(
diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.py
index 11e1d00f8..7e6536e9d 100644
--- a/headroom/proxy/cost.py
+++ b/headroom/proxy/cost.py
@@ -9,6 +9,7 @@ Extracted from server.py for maintainability.
from __future__ import annotations
import logging
+import importlib.util
from collections import deque
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
@@ -18,13 +19,20 @@ from headroom.proxy.modes import PROXY_MODE_CACHE
if TYPE_CHECKING:
from headroom.proxy.prometheus_metrics import PrometheusMetrics
-# Try to import LiteLLM for pricing
-try:
- import litellm
+LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
- LITELLM_AVAILABLE = True
-except ImportError:
- LITELLM_AVAILABLE = False
+
+def _get_litellm_module() -> Any | None:
+ """Import LiteLLM only when pricing data is actually requested."""
+ if not LITELLM_AVAILABLE:
+ return None
+
+ try:
+ import litellm
+ except ImportError:
+ return None
+
+ return litellm
logger = logging.getLogger("headroom.proxy")
@@ -472,7 +480,8 @@ class CostTracker:
@staticmethod
def _resolve_litellm_model_uncached(model: str) -> str:
"""Uncached resolution — called once per unique model name."""
- if not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is None:
return model
# Try as-is first
@@ -522,7 +531,8 @@ class CostTracker:
cache_read_tokens: Tokens served from cache (~10% of input rate)
cache_write_tokens: Tokens written to cache (~125% of input rate)
"""
- if not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is None:
logger.warning("LiteLLM not available - cannot calculate costs")
return None
@@ -631,7 +641,8 @@ class CostTracker:
def _get_list_price(self, model: str) -> float | None:
"""Get list input price per 1M tokens for a model."""
- if not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is None:
return None
try:
resolved = self._resolve_litellm_model(model)
@@ -647,7 +658,8 @@ class CostTracker:
Returns (cache_read, cache_write, uncached) per-token costs, or None
if pricing is unavailable. Uses LiteLLM's native cache pricing data.
"""
- if not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is None:
return None
try:
resolved = self._resolve_litellm_model(model)
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index 544904c53..295bad39d 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -8,6 +8,7 @@ survive proxy restarts and can be shared by multiple Headroom frontends.
from __future__ import annotations
import json
+import importlib.util
import logging
import os
import tempfile
@@ -28,12 +29,20 @@ DEFAULT_MAX_HISTORY_POINTS = 5000
DEFAULT_MAX_HISTORY_AGE_DAYS = 365
DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES = 60
-try:
- import litellm
+LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
- LITELLM_AVAILABLE = True
-except ImportError:
- LITELLM_AVAILABLE = False
+
+def _get_litellm_module() -> Any | None:
+ """Import LiteLLM only when cost metadata is requested."""
+ if not LITELLM_AVAILABLE:
+ return None
+
+ try:
+ import litellm
+ except ImportError:
+ return None
+
+ return litellm
def get_default_savings_storage_path() -> str:
@@ -96,7 +105,8 @@ def _coerce_float(value: Any, default: float = 0.0) -> float:
def _resolve_litellm_model(model: str) -> str:
"""Resolve model name to one LiteLLM recognizes."""
- if not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if litellm is None:
return model
try:
@@ -131,7 +141,8 @@ def _resolve_litellm_model(model: str) -> str:
def _estimate_compression_savings_usd(model: str, tokens_saved: int) -> float:
"""Estimate compression savings in USD from saved input tokens."""
- if tokens_saved <= 0 or not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if tokens_saved <= 0 or litellm is None:
return 0.0
try:
@@ -159,7 +170,8 @@ def _estimate_input_cost_usd(
otherwise falls back to list-price input tokens.
"""
total_input_tokens = _coerce_int(input_tokens)
- if total_input_tokens <= 0 or not LITELLM_AVAILABLE:
+ litellm = _get_litellm_module()
+ if total_input_tokens <= 0 or litellm is None:
return 0.0
cache_read = _coerce_int(cache_read_tokens)
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 97d83ff2b..ea4143c6f 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -36,6 +36,7 @@ from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal
if TYPE_CHECKING:
+ from ..backends.base import Backend
from ..cache.compression_cache import CompressionCache
from ..memory.tracker import MemoryTracker
@@ -55,9 +56,7 @@ except ImportError:
# Add parent to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-from headroom import __version__
-from headroom.backends import AnyLLMBackend, LiteLLMBackend
-from headroom.backends.base import Backend
+from headroom._version import __version__
from headroom.cache.compression_feedback import get_compression_feedback
from headroom.cache.compression_store import get_compression_store
from headroom.ccr import (
@@ -89,7 +88,8 @@ from headroom.observability import (
shutdown_headroom_tracing,
shutdown_otel_metrics,
)
-from headroom.providers import AnthropicProvider, OpenAIProvider
+from headroom.providers.anthropic import AnthropicProvider
+from headroom.providers.openai import OpenAIProvider
# =============================================================================
# Extracted modules (re-exported for backward compatibility)
@@ -350,6 +350,8 @@ class HeadroomProxy(
if backend == "anyllm" or backend.startswith("anyllm-"):
provider = config.anyllm_provider
try:
+ from headroom.backends.anyllm import AnyLLMBackend
+
self.anthropic_backend = AnyLLMBackend(provider=provider)
logger.info(f"any-llm backend enabled (provider={provider})")
except ImportError as e:
@@ -364,6 +366,8 @@ class HeadroomProxy(
provider = backend.replace("litellm-", "")
try:
+ from headroom.backends.litellm import LiteLLMBackend
+
self.anthropic_backend = LiteLLMBackend(
provider=provider,
region=config.bedrock_region,
diff --git a/headroom/telemetry/beacon.py b/headroom/telemetry/beacon.py
index bd9923acb..e3a2483c1 100644
--- a/headroom/telemetry/beacon.py
+++ b/headroom/telemetry/beacon.py
@@ -161,7 +161,7 @@ class TelemetryBeacon:
session_minutes = max(1, int((time.time() - self._start_time) / 60))
try:
- from headroom import __version__ as headroom_version
+ from headroom._version import __version__ as headroom_version
except Exception:
headroom_version = "unknown"
diff --git a/headroom/transforms/__init__.py b/headroom/transforms/__init__.py
index 1822412ac..46bc69c39 100644
--- a/headroom/transforms/__init__.py
+++ b/headroom/transforms/__init__.py
@@ -1,61 +1,11 @@
"""Transform modules for Headroom SDK."""
-from .anchor_selector import (
- AnchorSelector,
- AnchorStrategy,
- AnchorWeights,
- DataPattern,
- calculate_information_score,
- compute_item_hash,
-)
-from .base import Transform
-from .cache_aligner import CacheAligner
-from .content_detector import ContentType, DetectionResult, detect_content_type
-from .diff_compressor import DiffCompressionResult, DiffCompressor, DiffCompressorConfig
-from .intelligent_context import ContextStrategy, IntelligentContextManager
-from .log_compressor import LogCompressionResult, LogCompressor, LogCompressorConfig
-from .pipeline import TransformPipeline
-from .rolling_window import RollingWindow
-from .scoring import EmbeddingProvider, MessageScore, MessageScorer
-from .search_compressor import (
- SearchCompressionResult,
- SearchCompressor,
- SearchCompressorConfig,
-)
-from .smart_crusher import SmartCrusher, SmartCrusherConfig
-from .tool_crusher import ToolCrusher
+from __future__ import annotations
-# HTML content extraction (optional dependency - requires trafilatura)
-try:
- from .html_extractor import ( # noqa: F401
- HTMLExtractionResult,
- HTMLExtractor,
- HTMLExtractorConfig,
- is_html_content,
- )
-
- _HTML_EXTRACTOR_AVAILABLE = True
-except ImportError:
- _HTML_EXTRACTOR_AVAILABLE = False
+import importlib.util
+from importlib import import_module
-# AST-based code compression (optional dependency)
-from .code_compressor import (
- CodeAwareCompressor,
- CodeCompressionResult,
- CodeCompressorConfig,
- CodeLanguage,
- DocstringMode,
- detect_language,
- is_tree_sitter_available,
-)
-
-# Content routing (always available, lazy-loads compressors)
-from .content_router import (
- CompressionStrategy,
- ContentRouter,
- ContentRouterConfig,
- RouterCompressionResult,
-)
+_HTML_EXTRACTOR_AVAILABLE = importlib.util.find_spec("trafilatura") is not None
__all__ = [
# Base
@@ -72,7 +22,7 @@ __all__ = [
"ToolCrusher",
"SmartCrusher",
"SmartCrusherConfig",
- # Text compression (coding tasks)
+ # Text compression
"ContentType",
"DetectionResult",
"detect_content_type",
@@ -85,7 +35,7 @@ __all__ = [
"DiffCompressor",
"DiffCompressorConfig",
"DiffCompressionResult",
- # Code-aware compression (AST-based)
+ # Code-aware compression
"CodeAwareCompressor",
"CodeCompressorConfig",
"CodeCompressionResult",
@@ -101,17 +51,16 @@ __all__ = [
# Other transforms
"CacheAligner",
"RollingWindow",
- # Intelligent context management
+ # Intelligent context
"IntelligentContextManager",
"ContextStrategy",
"MessageScorer",
"MessageScore",
"EmbeddingProvider",
- # HTML extraction (optional)
+ # HTML extraction
"_HTML_EXTRACTOR_AVAILABLE",
]
-# Conditionally add HTML extractor exports
if _HTML_EXTRACTOR_AVAILABLE:
__all__.extend(
[
@@ -121,3 +70,105 @@ if _HTML_EXTRACTOR_AVAILABLE:
"is_html_content",
]
)
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+ # Base
+ "Transform": ("headroom.transforms.base", "Transform"),
+ "TransformPipeline": ("headroom.transforms.pipeline", "TransformPipeline"),
+ # Anchor selection
+ "AnchorSelector": ("headroom.transforms.anchor_selector", "AnchorSelector"),
+ "AnchorStrategy": ("headroom.transforms.anchor_selector", "AnchorStrategy"),
+ "AnchorWeights": ("headroom.transforms.anchor_selector", "AnchorWeights"),
+ "DataPattern": ("headroom.transforms.anchor_selector", "DataPattern"),
+ "calculate_information_score": (
+ "headroom.transforms.anchor_selector",
+ "calculate_information_score",
+ ),
+ "compute_item_hash": ("headroom.transforms.anchor_selector", "compute_item_hash"),
+ # JSON compression
+ "ToolCrusher": ("headroom.transforms.tool_crusher", "ToolCrusher"),
+ "SmartCrusher": ("headroom.transforms.smart_crusher", "SmartCrusher"),
+ "SmartCrusherConfig": ("headroom.transforms.smart_crusher", "SmartCrusherConfig"),
+ # Text compression
+ "ContentType": ("headroom.transforms.content_detector", "ContentType"),
+ "DetectionResult": ("headroom.transforms.content_detector", "DetectionResult"),
+ "detect_content_type": ("headroom.transforms.content_detector", "detect_content_type"),
+ "SearchCompressor": ("headroom.transforms.search_compressor", "SearchCompressor"),
+ "SearchCompressorConfig": (
+ "headroom.transforms.search_compressor",
+ "SearchCompressorConfig",
+ ),
+ "SearchCompressionResult": (
+ "headroom.transforms.search_compressor",
+ "SearchCompressionResult",
+ ),
+ "LogCompressor": ("headroom.transforms.log_compressor", "LogCompressor"),
+ "LogCompressorConfig": ("headroom.transforms.log_compressor", "LogCompressorConfig"),
+ "LogCompressionResult": ("headroom.transforms.log_compressor", "LogCompressionResult"),
+ "DiffCompressor": ("headroom.transforms.diff_compressor", "DiffCompressor"),
+ "DiffCompressorConfig": ("headroom.transforms.diff_compressor", "DiffCompressorConfig"),
+ "DiffCompressionResult": (
+ "headroom.transforms.diff_compressor",
+ "DiffCompressionResult",
+ ),
+ # Code-aware compression
+ "CodeAwareCompressor": ("headroom.transforms.code_compressor", "CodeAwareCompressor"),
+ "CodeCompressorConfig": ("headroom.transforms.code_compressor", "CodeCompressorConfig"),
+ "CodeCompressionResult": (
+ "headroom.transforms.code_compressor",
+ "CodeCompressionResult",
+ ),
+ "CodeLanguage": ("headroom.transforms.code_compressor", "CodeLanguage"),
+ "DocstringMode": ("headroom.transforms.code_compressor", "DocstringMode"),
+ "detect_language": ("headroom.transforms.code_compressor", "detect_language"),
+ "is_tree_sitter_available": (
+ "headroom.transforms.code_compressor",
+ "is_tree_sitter_available",
+ ),
+ # Content routing
+ "ContentRouter": ("headroom.transforms.content_router", "ContentRouter"),
+ "ContentRouterConfig": ("headroom.transforms.content_router", "ContentRouterConfig"),
+ "RouterCompressionResult": (
+ "headroom.transforms.content_router",
+ "RouterCompressionResult",
+ ),
+ "CompressionStrategy": ("headroom.transforms.content_router", "CompressionStrategy"),
+ # Other transforms
+ "CacheAligner": ("headroom.transforms.cache_aligner", "CacheAligner"),
+ "RollingWindow": ("headroom.transforms.rolling_window", "RollingWindow"),
+ # Intelligent context
+ "IntelligentContextManager": (
+ "headroom.transforms.intelligent_context",
+ "IntelligentContextManager",
+ ),
+ "ContextStrategy": ("headroom.transforms.intelligent_context", "ContextStrategy"),
+ "MessageScorer": ("headroom.transforms.scoring", "MessageScorer"),
+ "MessageScore": ("headroom.transforms.scoring", "MessageScore"),
+ "EmbeddingProvider": ("headroom.transforms.scoring", "EmbeddingProvider"),
+ # HTML extraction
+ "HTMLExtractor": ("headroom.transforms.html_extractor", "HTMLExtractor"),
+ "HTMLExtractorConfig": ("headroom.transforms.html_extractor", "HTMLExtractorConfig"),
+ "HTMLExtractionResult": ("headroom.transforms.html_extractor", "HTMLExtractionResult"),
+ "is_html_content": ("headroom.transforms.html_extractor", "is_html_content"),
+}
+
+
+def __getattr__(name: str) -> object:
+ if name == "__path__":
+ raise AttributeError(name)
+ if name == "_HTML_EXTRACTOR_AVAILABLE":
+ return _HTML_EXTRACTOR_AVAILABLE
+
+ try:
+ module_name, attr_name = _LAZY_EXPORTS[name]
+ except KeyError as exc:
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+ module = import_module(module_name)
+ value = getattr(module, attr_name)
+ globals()[name] = value
+ return value
+
+
+def __dir__() -> list[str]:
+ return sorted(set(globals()) | set(__all__))
diff --git a/headroom/transforms/cache_aligner.py b/headroom/transforms/cache_aligner.py
index 7fad4d24f..473b7c6cd 100644
--- a/headroom/transforms/cache_aligner.py
+++ b/headroom/transforms/cache_aligner.py
@@ -15,18 +15,17 @@ from __future__ import annotations
import logging
import re
-from typing import Any
+from typing import TYPE_CHECKING, Any
-from ..cache.dynamic_detector import (
- DetectorConfig,
- DynamicContentDetector,
-)
from ..config import CacheAlignerConfig, CachePrefixMetrics, TransformResult
from ..tokenizer import Tokenizer
from ..tokenizers import EstimatingTokenCounter
from ..utils import compute_short_hash, deep_copy_messages
from .base import Transform
+if TYPE_CHECKING:
+ from ..cache.dynamic_detector import DynamicContentDetector
+
logger = logging.getLogger(__name__)
@@ -77,6 +76,8 @@ class CacheAligner(Transform):
def _init_dynamic_detector(self) -> None:
"""Initialize the DynamicContentDetector with configured tiers."""
+ from ..cache.dynamic_detector import DetectorConfig, DynamicContentDetector
+
# Build detector config
detector_config = DetectorConfig(
tiers=list(self.config.detection_tiers),
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 994fdf6fa..7e4399a7b 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -52,23 +52,37 @@ from .content_detector import ContentType, DetectionResult, detect_content_type
logger = logging.getLogger(__name__)
-# Use Magika-based detector if available, fallback to regex
-_magika_detector = None
-_USE_MAGIKA = False
-try:
- from ..compression.detector import get_detector
+_magika_detector: Any | None = None
+_magika_status: bool | None = None
- _magika_detector = get_detector(prefer_magika=True)
- _USE_MAGIKA = True
- logger.info("ContentRouter: Using Magika ML-based content detection")
-except ImportError:
- logger.debug("Magika not available, using regex-based detection")
+
+def _get_magika_detector() -> Any | None:
+ """Load the Magika detector only when router detection actually runs."""
+ global _magika_detector, _magika_status
+
+ if _magika_status is False:
+ return None
+ if _magika_detector is not None:
+ return _magika_detector
+
+ try:
+ from ..compression.detector import get_detector
+
+ _magika_detector = get_detector(prefer_magika=True)
+ _magika_status = True
+ logger.info("ContentRouter: Using Magika ML-based content detection")
+ except ImportError:
+ _magika_status = False
+ logger.debug("Magika not available, using regex-based detection")
+
+ return _magika_detector
def _detect_content(content: str) -> DetectionResult:
"""Detect content type using Magika if available, else regex fallback."""
- if _USE_MAGIKA and _magika_detector:
- result = _magika_detector.detect(content)
+ magika_detector = _get_magika_detector()
+ if magika_detector is not None:
+ result = magika_detector.detect(content)
# Map Magika ContentType to router's expected format
type_map = {
"json": ContentType.JSON_ARRAY,
diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.ts
index 14fdc1e72..8d6868061 100644
--- a/plugins/openclaw/src/proxy-manager.ts
+++ b/plugins/openclaw/src/proxy-manager.ts
@@ -224,7 +224,33 @@ export class ProxyManager {
const specs: LaunchSpec[] = [];
- // 1) PATH
+ const configuredPython = this.getConfiguredPythonCommand();
+ if (configuredPython) {
+ specs.push({
+ label: `Configured Python: ${configuredPython} -m headroom.cli`,
+ command: configuredPython,
+ args: ["-m", "headroom.cli", ...commonArgs],
+ checkCommand: configuredPython,
+ checkArgs: ["-c", HEADROOM_MODULE_DISCOVERY_SNIPPET],
+ });
+ }
+
+ // 2) Windows pyenv: resolve the real executable so we avoid shim .bat wrappers.
+ if (process.platform === "win32") {
+ const pyenvHeadroom = this.getPyenvResolvedHeadroom();
+ if (pyenvHeadroom) {
+ specs.push({
+ label: `pyenv: ${pyenvHeadroom}`,
+ command: pyenvHeadroom,
+ args: commonArgs,
+ checkCommand: pyenvHeadroom,
+ checkArgs: ["--version"],
+ useShell: false,
+ });
+ }
+ }
+
+ // 3) PATH
specs.push({
label: "PATH: headroom",
command: "headroom",
@@ -237,7 +263,7 @@ export class ProxyManager {
checkUseShell: false,
});
- // 2) Local npm install (inside plugin install path)
+ // 4) Local npm install (inside plugin install path)
const moduleDir = dirname(fileURLToPath(import.meta.url)); // .../dist
const packageRoot = dirname(moduleDir);
const localBinDir = join(packageRoot, "node_modules", ".bin");
@@ -256,7 +282,7 @@ export class ProxyManager {
});
}
- // 3) Global npm install
+ // 5) Global npm install
const npmPrefix = this.getNpmGlobalPrefix();
if (npmPrefix) {
const globalBins = process.platform === "win32"
@@ -276,9 +302,10 @@ export class ProxyManager {
}
}
- // 4) Python module fallback
+ // 6) Python module fallback
const pythonCommands = this.getPythonCommands();
for (const pyCmd of pythonCommands) {
+ if (configuredPython && pyCmd === configuredPython) continue;
specs.push({
label: `Python: ${pyCmd} -m headroom.cli`,
command: pyCmd,
@@ -291,11 +318,34 @@ export class ProxyManager {
return specs;
}
- private getPythonCommands(): string[] {
- const commands: string[] = [];
+ private getConfiguredPythonCommand(): string | null {
const configured = typeof this.config.pythonPath === "string"
? this.config.pythonPath.trim()
: "";
+ return configured.length > 0 ? configured : null;
+ }
+
+ private getPyenvResolvedHeadroom(): string | null {
+ if (process.platform !== "win32") return null;
+
+ try {
+ const result = spawnSync("pyenv", ["which", "headroom"], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ timeout: 5000,
+ });
+ if (result.error || result.status !== 0) return null;
+ const resolved = (result.stdout ?? "").trim().split(/\r?\n/, 1)[0];
+ if (!resolved || !existsSync(resolved)) return null;
+ return resolved;
+ } catch {
+ return null;
+ }
+ }
+
+ private getPythonCommands(): string[] {
+ const commands: string[] = [];
+ const configured = this.getConfiguredPythonCommand() ?? "";
if (configured.length > 0) {
commands.push(configured);
}
diff --git a/plugins/openclaw/test/proxy-manager.test.ts b/plugins/openclaw/test/proxy-manager.test.ts
index 6af995e42..eb477166a 100644
--- a/plugins/openclaw/test/proxy-manager.test.ts
+++ b/plugins/openclaw/test/proxy-manager.test.ts
@@ -204,11 +204,23 @@ describe("ProxyManager launch internals", () => {
expect(commands).toContain("py");
});
+ it("prefers configured pythonPath ahead of PATH launchers", () => {
+ const manager = new ProxyManager({ pythonPath: "C:\\Python311\\python.exe" });
+ vi.spyOn(manager as any, "getPyenvResolvedHeadroom").mockReturnValue(null);
+
+ const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
+
+ expect(specs[0]?.label).toContain("Configured Python:");
+ expect(specs[0]?.command).toBe("C:\\Python311\\python.exe");
+ expect(specs[0]?.args).toEqual(["-m", "headroom.cli", "proxy", "--host", "127.0.0.1", "--port", "8787"]);
+ });
+
it("uses lightweight PATH checks instead of booting the headroom CLI", () => {
const manager = new ProxyManager({});
const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
- const pathSpec = specs[0];
+ const pathSpec = specs.find((spec) => spec.command === "headroom");
+ expect(pathSpec).toBeDefined();
expect(pathSpec.command).toBe("headroom");
expect(pathSpec.args).toEqual(["proxy", "--host", "127.0.0.1", "--port", "8787"]);
if (process.platform === "win32") {
@@ -221,6 +233,20 @@ describe("ProxyManager launch internals", () => {
}
});
+ it("prefers a resolved pyenv executable on Windows before PATH shims", () => {
+ if (process.platform !== "win32") return;
+
+ const manager = new ProxyManager({});
+ vi.spyOn(manager as any, "getPyenvResolvedHeadroom").mockReturnValue("C:\\Python312\\Scripts\\headroom.exe");
+
+ const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
+
+ expect(specs[0]?.label).toContain("pyenv:");
+ expect(specs[0]?.command).toBe("C:\\Python312\\Scripts\\headroom.exe");
+ expect(specs[0]?.useShell).toBe(false);
+ expect(specs[1]?.command).toBe("headroom");
+ });
+
it("passes through fast-fail launch flags when configured", () => {
const manager = new ProxyManager({ retryMaxAttempts: 1, connectTimeoutSeconds: 3 });
const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
diff --git a/tests/test_package_init_lazy.py b/tests/test_package_init_lazy.py
new file mode 100644
index 000000000..142e8ec54
--- /dev/null
+++ b/tests/test_package_init_lazy.py
@@ -0,0 +1,68 @@
+"""Regression tests for lightweight package bootstrap."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import textwrap
+
+
+def test_headroom_import_stays_lazy() -> None:
+ script = textwrap.dedent(
+ """
+ import json
+ import sys
+
+ import headroom
+
+ print(json.dumps({
+ "version": headroom.__version__,
+ "cache_loaded": "headroom.cache" in sys.modules,
+ "models_registry_loaded": "headroom.models.registry" in sys.modules,
+ "memory_loaded": "headroom.memory" in sys.modules,
+ }))
+ """
+ )
+
+ result = subprocess.run(
+ [sys.executable, "-c", script],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+
+ data = json.loads(result.stdout.strip())
+ assert data["version"] == "0.5.21"
+ assert data["cache_loaded"] is False
+ assert data["models_registry_loaded"] is False
+ assert data["memory_loaded"] is False
+
+
+def test_proxy_server_import_skips_litellm_backend() -> None:
+ script = textwrap.dedent(
+ """
+ import json
+ import sys
+
+ import headroom.proxy.server
+
+ print(json.dumps({
+ "litellm_backend_loaded": "headroom.backends.litellm" in sys.modules,
+ "anyllm_backend_loaded": "headroom.backends.anyllm" in sys.modules,
+ "litellm_loaded": "litellm" in sys.modules,
+ }))
+ """
+ )
+
+ result = subprocess.run(
+ [sys.executable, "-c", script],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+
+ data = json.loads(result.stdout.strip())
+ assert data["litellm_backend_loaded"] is False
+ assert data["anyllm_backend_loaded"] is False
+ assert data["litellm_loaded"] is False