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(deps): recommend headroom-ai for optional extras (#4046)
Mansurshakh Japarovf1bc260948c1
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdxindex a11db86da..895763055 100644--- a/docs/content/docs/installation.mdx+++ b/docs/content/docs/installation.mdx@@ -24,6 +24,10 @@ dependencies may impose their own Python/platform limits. Platforms outsidethat matrix fall back to the source distribution and need a Rust/nativetoolchain.+Use the distribution name `headroom-ai` for every install, including extras such as+`"headroom-ai[langchain]"`. The Python import and CLI command remain `headroom`;+the PyPI distribution named `headroom` is a different project.+On Intel macOS, ONNX Runtime wheels are available through Python 3.13, usingthe pre-1.24 runtime. Python 3.14 and newer omit optional ONNX backends from`proxy`, `voice`, `relevance`, and `image` extras because compatible wheels arediff --git a/headroom/cli/evals.py b/headroom/cli/evals.pyindex 754f9aa45..d9b16f03f 100644--- a/headroom/cli/evals.py+++ b/headroom/cli/evals.py@@ -449,7 +449,7 @@ def _run_memory_eval(from headroom.memory import MemoryConfigexcept ImportError as e:click.echo("Error: Memory eval dependencies not installed.")- click.echo("Run: pip install headroom[memory,evals]")+ click.echo('Run: pip install "headroom-ai[memory,evals]"')click.echo(f"Details: {e}")raise SystemExit(1) from None@@ -621,7 +621,7 @@ def _run_memory_eval_v2()except ImportError as e:click.echo("Error: Memory eval V2 dependencies not installed.")- click.echo("Run: pip install headroom[memory,evals]")+ click.echo('Run: pip install "headroom-ai[memory,evals]"')click.echo(f"Details: {e}")raise SystemExit(1) from Nonediff --git a/headroom/config.py b/headroom/config.pyindex 465b3164e..11a507e50 100644--- a/headroom/config.py+++ b/headroom/config.py@@ -118,7 +118,7 @@ class RelevanceScorerConfig:DEFAULT: "hybrid" - combines exact matching (UUIDs, IDs) with semanticunderstanding. Falls back to BM25 if sentence-transformers not installed.- For full hybrid support, install: pip install headroom[relevance]+ For full hybrid support, install: pip install "headroom-ai[relevance]"WHY HYBRID IS DEFAULT:- Missing important items during compression is catastrophicdiff --git a/headroom/integrations/__init__.py b/headroom/integrations/__init__.pyindex f3043195a..801b3d086 100644--- a/headroom/integrations/__init__.py+++ b/headroom/integrations/__init__.py@@ -2,7 +2,7 @@Available integrations:-LangChain (pip install headroom[langchain]):+LangChain (pip install "headroom-ai[langchain]"):- HeadroomChatModel: Drop-in wrapper for any LangChain chat model- HeadroomChatMessageHistory: Automatic conversation compression- HeadroomDocumentCompressor: Relevance-based document filtering@@ -19,7 +19,7 @@ CrewAI (pip install headroom-ai crewai):- HeadroomToolWrapper: Tool output compression for CrewAI agents- wrap_tools_with_headroom: Batch wrapper for CrewAI tools-AutoGen (pip install headroom[autogen]):+AutoGen (pip install "headroom-ai[autogen]"):- HeadroomToolWrapper: Tool output compression for AutoGen agents- wrap_tools_with_headroom: Batch wrapper for AutoGen toolsdiff --git a/headroom/integrations/langchain/__init__.py b/headroom/integrations/langchain/__init__.pyindex 46ef09ddb..1a1a1b285 100644--- a/headroom/integrations/langchain/__init__.py+++ b/headroom/integrations/langchain/__init__.py@@ -20,7 +20,7 @@ Example:# Use like normal - optimization happens automaticallyresponse = llm.invoke("Hello!")-Install: pip install headroom[langchain]+Install: pip install "headroom-ai[langchain]""""# Agent tool wrappingdiff --git a/headroom/integrations/langchain/agents.py b/headroom/integrations/langchain/agents.pyindex 8125f0600..80d3e9333 100644--- a/headroom/integrations/langchain/agents.py+++ b/headroom/integrations/langchain/agents.py@@ -53,7 +53,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core")diff --git a/headroom/integrations/langchain/chat_model.py b/headroom/integrations/langchain/chat_model.pyindex 1ec545996..6f4dd4eca 100644--- a/headroom/integrations/langchain/chat_model.py+++ b/headroom/integrations/langchain/chat_model.py@@ -76,7 +76,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core langchain-openai")diff --git a/headroom/integrations/langchain/langgraph.py b/headroom/integrations/langchain/langgraph.pyindex 83aad7560..93cab2577 100644--- a/headroom/integrations/langchain/langgraph.py+++ b/headroom/integrations/langchain/langgraph.py@@ -60,7 +60,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core")diff --git a/headroom/integrations/langchain/langsmith.py b/headroom/integrations/langchain/langsmith.pyindex f7bd14359..05d89290f 100644--- a/headroom/integrations/langchain/langsmith.py+++ b/headroom/integrations/langchain/langsmith.py@@ -72,7 +72,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core")diff --git a/headroom/integrations/langchain/memory.py b/headroom/integrations/langchain/memory.pyindex a3e409234..d14e6d957 100644--- a/headroom/integrations/langchain/memory.py+++ b/headroom/integrations/langchain/memory.py@@ -53,7 +53,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core")diff --git a/headroom/integrations/langchain/retriever.py b/headroom/integrations/langchain/retriever.pyindex 8af1eff92..1f079c768 100644--- a/headroom/integrations/langchain/retriever.py+++ b/headroom/integrations/langchain/retriever.py@@ -93,7 +93,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core")diff --git a/headroom/integrations/langchain/streaming.py b/headroom/integrations/langchain/streaming.pyindex 24a92b09a..8c83eb8bc 100644--- a/headroom/integrations/langchain/streaming.py+++ b/headroom/integrations/langchain/streaming.py@@ -45,7 +45,7 @@ def _check_langchain_available() -> None:if not LANGCHAIN_AVAILABLE:raise ImportError("LangChain is required for this integration. "- "Install with: pip install headroom[langchain] "+ 'Install with: pip install "headroom-ai[langchain]" '"or: pip install langchain-core")diff --git a/headroom/relevance/__init__.py b/headroom/relevance/__init__.pyindex 807bba593..b695c3a44 100644--- a/headroom/relevance/__init__.py+++ b/headroom/relevance/__init__.py@@ -11,7 +11,7 @@ Available scorers:- Combines BM25 + embeddings for best accuracy- Adaptive alpha: more BM25 for UUIDs, more semantic for natural language- Falls back gracefully to BM25 if sentence-transformers not installed- - Install for full support: pip install headroom[relevance]+ - Install for full support: pip install "headroom-ai[relevance]"2. BM25Scorer (zero dependencies)- Fast keyword matching@@ -21,7 +21,7 @@ Available scorers:3. EmbeddingScorer (requires sentence-transformers)- Pure semantic similarity- Best for natural language queries- - Install: pip install headroom[relevance]+ - Install: pip install "headroom-ai[relevance]"WHY HYBRID IS DEFAULT:- Missing important items during compression is catastrophic@@ -112,7 +112,7 @@ def create_scorer(if not EmbeddingScorer.is_available():raise RuntimeError("EmbeddingScorer requires sentence-transformers. "- "Install with: pip install headroom[relevance]"+ 'Install with: pip install "headroom-ai[relevance]"')return EmbeddingScorer(**kwargs)diff --git a/headroom/relevance/embedding.py b/headroom/relevance/embedding.pyindex 666b6bb16..91766dd5d 100644--- a/headroom/relevance/embedding.py+++ b/headroom/relevance/embedding.py@@ -13,7 +13,7 @@ Key features:- ~2-3x faster than sentence-transformers' all-MiniLM-L6-v2- Outranks all-MiniLM-L6-v2 by ~6 MTEB points-Install with: pip install headroom[relevance]+Install with: pip install "headroom-ai[relevance]"History: this module previously wrapped `sentence-transformers`(PyTorch). Switched to fastembed in Stage 3c.1 of the Rust port to:@@ -49,7 +49,7 @@ def _get_numpy():except ImportError as e:raise ImportError("numpy is required for EmbeddingScorer. "- "Install with: pip install headroom[relevance]"+ 'Install with: pip install "headroom-ai[relevance]"') from ereturn _numpy@@ -172,7 +172,7 @@ class EmbeddingScorer(RelevanceScorer):# score.score > 0.5 (semantic match between "failed"/"error" and "errors")Note:- Requires fastembed: pip install headroom[relevance]+ Requires fastembed: pip install "headroom-ai[relevance]""""def __init__(@@ -218,7 +218,8 @@ class EmbeddingScorer(RelevanceScorer):"""if not self.is_available():raise RuntimeError(- "EmbeddingScorer requires fastembed. Install with: pip install headroom[relevance]"+ "EmbeddingScorer requires fastembed. "+ 'Install with: pip install "headroom-ai[relevance]"')if self._model is None:diff --git a/headroom/reporting/generator.py b/headroom/reporting/generator.pyindex d22484004..ccb7dc3b2 100644--- a/headroom/reporting/generator.py+++ b/headroom/reporting/generator.py@@ -23,7 +23,8 @@ def _get_jinja2_template(template_str: str):return Template(template_str, autoescape=True)except ImportError as e:raise ImportError(- "jinja2 is required for report generation. Install with: pip install headroom[reports]"+ "jinja2 is required for report generation. "+ 'Install with: pip install "headroom-ai[reports]"') from e