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
docs: preserve package entrypoint comments
JerrettDavisc4da04faab70
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex 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__.pyindex 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_modulefrom typing import TYPE_CHECKINGif TYPE_CHECKING:+ # Expose concrete types to static analysis while keeping runtime imports lazy.from headroom.cache.anthropic import AnthropicCacheOptimizer # noqa: F401from headroom.cache.base import ( # noqa: F401BaseCacheOptimizer,diff --git a/headroom/providers/__init__.py b/headroom/providers/__init__.pyindex 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_modulefrom typing import TYPE_CHECKINGif TYPE_CHECKING:+ # Expose concrete types to static analysis while keeping runtime imports lazy.from headroom.providers.anthropic import AnthropicProviderfrom headroom.providers.base import Provider, TokenCounterfrom headroom.providers.cohere import CohereProviderdiff --git a/headroom/transforms/__init__.py b/headroom/transforms/__init__.pyindex 6354b1b4e..2d7adceb0 100644--- a/headroom/transforms/__init__.py+++ b/headroom/transforms/__init__.py@@ -7,6 +7,7 @@ from importlib import import_modulefrom typing import TYPE_CHECKINGif TYPE_CHECKING:+ # Expose concrete types to static analysis while keeping runtime imports lazy.from headroom.transforms.anchor_selector import ( # noqa: F401AnchorSelector,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 exportsif _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"),