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(deps): recommend headroom-ai for optional extras (#4046)

Mansurshakh Japarovf1bc260948c1
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx
index 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 outside
that matrix fall back to the source distribution and need a Rust/native
toolchain.
+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, using
the pre-1.24 runtime. Python 3.14 and newer omit optional ONNX backends from
`proxy`, `voice`, `relevance`, and `image` extras because compatible wheels are
diff --git a/headroom/cli/evals.py b/headroom/cli/evals.py
index 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 MemoryConfig
except 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 None
diff --git a/headroom/config.py b/headroom/config.py
index 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 semantic
understanding. 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 catastrophic
diff --git a/headroom/integrations/__init__.py b/headroom/integrations/__init__.py
index 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 tools
diff --git a/headroom/integrations/langchain/__init__.py b/headroom/integrations/langchain/__init__.py
index 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 automatically
response = llm.invoke("Hello!")
-Install: pip install headroom[langchain]
+Install: pip install "headroom-ai[langchain]"
"""
# Agent tool wrapping
diff --git a/headroom/integrations/langchain/agents.py b/headroom/integrations/langchain/agents.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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__.py
index 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.py
index 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 e
return _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.py
index 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