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.

docs: preserve package entrypoint comments

JerrettDavisc4da04faab70
diff --git a/headroom/__init__.py b/headroom/__init__.py
index 8e65f3750..40fd5bab8 100644
--- a/headroom/__init__.py
+++ b/headroom/__init__.py
@@ -131,7 +131,7 @@ __all__ = [
"GoogleCacheOptimizer",
"SemanticCache",
"SemanticCacheLayer",
- # Relevance scoring
+ # Relevance scoring - BM25 always available, embeddings require sentence-transformers
"RelevanceScore",
"RelevanceScorer",
"BM25Scorer",
@@ -157,21 +157,21 @@ __all__ = [
"get_otel_metrics_status",
"reset_headroom_tracing",
"reset_otel_metrics",
- # Memory - hierarchical memory system
+ # Memory - optional hierarchical memory system
"with_memory", # Main user-facing API
"Memory",
"ScopeLevel",
"HierarchicalMemory",
"MemoryConfig",
"EmbedderBackend",
- # One-function API
+ # One-function compression API
"compress",
"CompressResult",
# Hooks
"CompressionHooks",
"CompressContext",
"CompressEvent",
- # Shared context
+ # Shared context for multi-agent workflows
"SharedContext",
]
@@ -266,6 +266,7 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
"SharedContext": ("headroom.shared_context", "SharedContext"),
}
+# Memory module - optional (requires numpy, hnswlib, etc.)
_OPTIONAL_EXPORTS = {
"with_memory": ("headroom.memory", "with_memory"),
"Memory": ("headroom.memory", "Memory"),
diff --git a/headroom/cache/__init__.py b/headroom/cache/__init__.py
index 88315247c..052fac83a 100644
--- a/headroom/cache/__init__.py
+++ b/headroom/cache/__init__.py
@@ -1,4 +1,28 @@
-"""Headroom cache optimization exports."""
+"""Headroom Cache Optimization Module.
+
+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.
+
+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 __future__ import annotations
@@ -6,6 +30,7 @@ from importlib import import_module
from typing import TYPE_CHECKING
if TYPE_CHECKING:
+ # Expose concrete types to static analysis while keeping runtime imports lazy.
from headroom.cache.anthropic import AnthropicCacheOptimizer # noqa: F401
from headroom.cache.base import ( # noqa: F401
BaseCacheOptimizer,
diff --git a/headroom/providers/__init__.py b/headroom/providers/__init__.py
index 1e37ece21..e36265991 100644
--- a/headroom/providers/__init__.py
+++ b/headroom/providers/__init__.py
@@ -1,4 +1,17 @@
-"""Provider abstractions for Headroom SDK."""
+"""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 __future__ import annotations
@@ -6,6 +19,7 @@ from importlib import import_module
from typing import TYPE_CHECKING
if TYPE_CHECKING:
+ # Expose concrete types to static analysis while keeping runtime imports lazy.
from headroom.providers.anthropic import AnthropicProvider
from headroom.providers.base import Provider, TokenCounter
from headroom.providers.cohere import CohereProvider
diff --git a/headroom/transforms/__init__.py b/headroom/transforms/__init__.py
index 6354b1b4e..2d7adceb0 100644
--- a/headroom/transforms/__init__.py
+++ b/headroom/transforms/__init__.py
@@ -7,6 +7,7 @@ from importlib import import_module
from typing import TYPE_CHECKING
if TYPE_CHECKING:
+ # Expose concrete types to static analysis while keeping runtime imports lazy.
from headroom.transforms.anchor_selector import ( # noqa: F401
AnchorSelector,
AnchorStrategy,
@@ -89,7 +90,7 @@ __all__ = [
"ToolCrusher",
"SmartCrusher",
"SmartCrusherConfig",
- # Text compression
+ # Text compression (coding tasks)
"ContentType",
"DetectionResult",
"detect_content_type",
@@ -102,7 +103,7 @@ __all__ = [
"DiffCompressor",
"DiffCompressorConfig",
"DiffCompressionResult",
- # Code-aware compression
+ # Code-aware compression (AST-based)
"CodeAwareCompressor",
"CodeCompressorConfig",
"CodeCompressionResult",
@@ -118,16 +119,17 @@ __all__ = [
# Other transforms
"CacheAligner",
"RollingWindow",
- # Intelligent context
+ # Intelligent context management
"IntelligentContextManager",
"ContextStrategy",
"MessageScorer",
"MessageScore",
"EmbeddingProvider",
- # HTML extraction
+ # HTML extraction (optional)
"_HTML_EXTRACTOR_AVAILABLE",
]
+# Conditionally add HTML extractor exports
if _HTML_EXTRACTOR_AVAILABLE:
__all__.extend(
[
@@ -156,7 +158,7 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
"ToolCrusher": ("headroom.transforms.tool_crusher", "ToolCrusher"),
"SmartCrusher": ("headroom.transforms.smart_crusher", "SmartCrusher"),
"SmartCrusherConfig": ("headroom.transforms.smart_crusher", "SmartCrusherConfig"),
- # Text compression
+ # Text compression (coding tasks)
"ContentType": ("headroom.transforms.content_detector", "ContentType"),
"DetectionResult": ("headroom.transforms.content_detector", "DetectionResult"),
"detect_content_type": ("headroom.transforms.content_detector", "detect_content_type"),
@@ -178,7 +180,7 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
"headroom.transforms.diff_compressor",
"DiffCompressionResult",
),
- # Code-aware compression
+ # Code-aware compression (AST-based)
"CodeAwareCompressor": ("headroom.transforms.code_compressor", "CodeAwareCompressor"),
"CodeCompressorConfig": ("headroom.transforms.code_compressor", "CodeCompressorConfig"),
"CodeCompressionResult": (
@@ -203,7 +205,7 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
# Other transforms
"CacheAligner": ("headroom.transforms.cache_aligner", "CacheAligner"),
"RollingWindow": ("headroom.transforms.rolling_window", "RollingWindow"),
- # Intelligent context
+ # Intelligent context management
"IntelligentContextManager": (
"headroom.transforms.intelligent_context",
"IntelligentContextManager",
@@ -212,7 +214,7 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
"MessageScorer": ("headroom.transforms.scoring", "MessageScorer"),
"MessageScore": ("headroom.transforms.scoring", "MessageScore"),
"EmbeddingProvider": ("headroom.transforms.scoring", "EmbeddingProvider"),
- # HTML extraction
+ # HTML extraction (optional dependency - requires trafilatura)
"HTMLExtractor": ("headroom.transforms.html_extractor", "HTMLExtractor"),
"HTMLExtractorConfig": ("headroom.transforms.html_extractor", "HTMLExtractorConfig"),
"HTMLExtractionResult": ("headroom.transforms.html_extractor", "HTMLExtractionResult"),