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: lazy-load proxy startup dependencies
JerrettDavisf63cfe7a1e8f
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex 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.pynew file mode 100644index 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__.pyindex 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.pyindex acc84ca97..539ff4a4e 100644--- a/headroom/cli/main.py+++ b/headroom/cli/main.py@@ -6,7 +6,7 @@ import clickdef 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__.pyindex 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__.pyindex 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.pyindex b8f41f9eb..b84418667 100644--- a/headroom/providers/anthropic.py+++ b/headroom/providers/anthropic.py@@ -16,6 +16,7 @@ Usage:"""import json+import importlib.utilimport loggingimport osimport warnings@@ -24,16 +25,21 @@ from typing import Any, castfrom .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_infologger = 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.pyindex 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 annotationsimport json+import importlib.utilimport loggingimport osimport 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 costcost = litellm.completion_cost(diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.pyindex 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 annotationsimport logging+import importlib.utilfrom collections import dequefrom datetime import datetime, timedeltafrom typing import TYPE_CHECKING, Any@@ -18,13 +19,20 @@ from headroom.proxy.modes import PROXY_MODE_CACHEif 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 litellmlogger = logging.getLogger("headroom.proxy")@@ -472,7 +480,8 @@ class CostTracker:@staticmethoddef _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 Nonetry:resolved = self._resolve_litellm_model(model)@@ -647,7 +658,8 @@ class CostTracker:Returns (cache_read, cache_write, uncached) per-token costs, or Noneif pricing is unavailable. Uses LiteLLM's native cache pricing data."""- if not LITELLM_AVAILABLE:+ litellm = _get_litellm_module()+ if litellm is None:return Nonetry:resolved = self._resolve_litellm_model(model)diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pyindex 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 annotationsimport json+import importlib.utilimport loggingimport osimport tempfile@@ -28,12 +29,20 @@ DEFAULT_MAX_HISTORY_POINTS = 5000DEFAULT_MAX_HISTORY_AGE_DAYS = 365DEFAULT_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 litellmdef 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 modeltry:@@ -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.0try:@@ -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.0cache_read = _coerce_int(cache_read_tokens)diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 97d83ff2b..ea4143c6f 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -36,6 +36,7 @@ from pathlib import Pathfrom typing import TYPE_CHECKING, Any, Literalif TYPE_CHECKING:+ from ..backends.base import Backendfrom ..cache.compression_cache import CompressionCachefrom ..memory.tracker import MemoryTracker@@ -55,9 +56,7 @@ except ImportError:# Add parent to path for importssys.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_feedbackfrom headroom.cache.compression_store import get_compression_storefrom 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_providertry:+ 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.pyindex 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_versionexcept Exception:headroom_version = "unknown"diff --git a/headroom/transforms/__init__.py b/headroom/transforms/__init__.pyindex 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 exportsif _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.pyindex 7fad4d24f..473b7c6cd 100644--- a/headroom/transforms/cache_aligner.py+++ b/headroom/transforms/cache_aligner.py@@ -15,18 +15,17 @@ from __future__ import annotationsimport loggingimport re-from typing import Any+from typing import TYPE_CHECKING, Any-from ..cache.dynamic_detector import (- DetectorConfig,- DynamicContentDetector,-)from ..config import CacheAlignerConfig, CachePrefixMetrics, TransformResultfrom ..tokenizer import Tokenizerfrom ..tokenizers import EstimatingTokenCounterfrom ..utils import compute_short_hash, deep_copy_messagesfrom .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 configdetector_config = DetectorConfig(tiers=list(self.config.detection_tiers),diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 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_typelogger = 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_detectordef _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 formattype_map = {"json": ContentType.JSON_ARRAY,diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.tsindex 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) PATHspecs.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)); // .../distconst packageRoot = dirname(moduleDir);const localBinDir = join(packageRoot, "node_modules", ".bin");@@ -256,7 +282,7 @@ export class ProxyManager {});}- // 3) Global npm install+ // 5) Global npm installconst npmPrefix = this.getNpmGlobalPrefix();if (npmPrefix) {const globalBins = process.platform === "win32"@@ -276,9 +302,10 @@ export class ProxyManager {}}- // 4) Python module fallback+ // 6) Python module fallbackconst 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.tsindex 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.pynew file mode 100644index 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