fix(deps): recommend headroom-ai for optional extras (#4046)

### Maintainer qualification refresh (2026-10-09)

Current head: `345d362496cd0eb3cf3919137961ef6bc7c140ec`. Merged current
main `01d9194` cleanly through GitHub branch update, preserving the
installation guidance and fixture corrections. The merged tree passed 48
focused pricing/dependency tests and 17 xAI/LiteLLM tests; Ruff and
whitespace checks passed. Current-head hosted checks are now green.
Earlier runtime and resolver evidence remains attributed to its original
tested heads. Ready for human merge review; no merge performed.

## Description

Closes #4041. Recommend this project's PyPI distribution
`headroom-ai[...]` in optional-dependency errors and installation
examples; keep the Python import and CLI name `headroom` unchanged.

Current published head: `345d362496cd0eb3cf3919137961ef6bc7c140ec`.
Maintainer updates, main's Intel-macOS ONNX documentation, shared ONNX
test-contract adaptations, and independent xAI billing checks are
preserved.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update

## Changes Made

- Correct fourteen Python guidance owners and the existing installation
documentation.
- Quote extras requirements portably, e.g. `pip install
"headroom-ai[langchain]"`.
- Preserve existing exception types, optional-dependency conditions,
package imports and executable names.
- Preserve the maintainer's shared test-fixture corrections; no
production billing change.

## Testing

- [ ] Unit tests pass (`pytest`) — no new whole-project local run
claimed.
- [ ] Linting passes (`ruff check .`) — earlier bounded owner checks are
linked below.
- [ ] Type checking passes (`mypy headroom`) — no new installed-extra
whole-project claim.
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

Historical pre-synchronization hosted checks:
https://github.com/headroomlabs-ai/headroom/actions/runs/37811412629

Observed on `45c5a3658`: all four Python shards, extras tests, native
Docker exercise, builds and lint succeeded. Rust-only lanes were
skipped, not counted as passed.

Independent maintainer before/after public API and pip evidence,
including complete runnable guard script and output:
https://github.com/headroomlabs-ai/headroom/pull/4046#issuecomment-6064193865

Historical owner qualification at `ef7a1c933`: 334 passed, 12 skipped, 9
local-model cases deselected; 67 dependency-contract/CLI tests passed.
The initial seven offline Ollama failures are disclosed there, not
relabeled green. Later 74-test pricing validation and the LiteLLM
1.104.2 portability check:
https://github.com/headroomlabs-ai/headroom/pull/4046#issuecomment-6064722009

## Real Behavior Proof

- Environment: original Linux x86_64 / Python 3.13.14 default-only
environment, plus the maintainer's independent Windows default-only
`headroom-ai==0.40.0` environment genuinely lacking `langchain_core`; no
provider/model calls.
- Exact command / steps: run the public `HeadroomChatModel(object())`
constructor and all seven real optional-LangChain guards using the
complete script in the linked maintainer evidence. The maintainer also
executed these non-installing resolver commands:

```powershell
G:/tmp/headroom-review/resume26-4046-venv/Scripts/python.exe -m pip install --dry-run --ignore-installed --no-deps --only-binary=:all: --report G:/git/headroom/.remember/tmp/pr4046-resume26-pip-old.json 'headroom[langchain]'
G:/tmp/headroom-review/resume26-4046-venv/Scripts/python.exe -m pip install --dry-run --ignore-installed --no-deps --only-binary=:all: --report G:/git/headroom/.remember/tmp/pr4046-resume26-pip-corrected.json 'headroom-ai[langchain]'
```

- Observed result: before, the public constructor recommends the
unrelated distribution and its check fails; after, all eight surfaces
advertise the quoted `headroom-ai[langchain]` requirement. Pip's old
requirement selects unrelated `headroom` 0.2.7 with no extras; the
corrected requirement selects `headroom-ai` 0.40.0 with the advertised
extra. No unrelated package was installed or executed.
- Not tested: live provider billing, paid endpoints, model downloads,
successful memory evaluation, or a new local whole-project typecheck.
The original default-only memory-eval attempt reached an unchanged late
NumPy import error before this guidance block; no success is claimed for
it.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; installation guidance correction
only.
- Minimum rollout channel: N/A; no rollout channel or runtime flag
added.
- Stable/default behavior changed: corrected installation advice only;
optional-import conditions and exception types are unchanged.
- Kill switch / disable path: N/A; no feature enablement or persistent
state change.
- Unsafe override required: no.
- Qualification impact: follow the correct distribution's existing
extras; no dependency constraint changes. Exact-head hosted Python
checks passed; skipped Rust-only lanes are not fresh qualification.
- Rollback path: revert the guidance change; no state migration or data
rollback.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please

## Additional Notes

Issue #4041 explicitly excludes source-string wording-only permanent
tests. A literal-message equality test would copy this edit, and live
index-resolution tests would be network-dependent; the actual public API
and non-installing resolver red/green evidence verify the requested
contract. Existing owner suites remain in place. Independent maintainer
results are attributed above, not represented as newly executed local
checks. AI-assisted follow-up, without subagents; no approval or merge
performed.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Mansurshakh Japarov
2026-10-13 16:37:32 -07:00
committed by GitHub
co-authored by JerrettDavis
parent 9762a14a40
commit f1bc260948
15 changed files with 27 additions and 21 deletions
+4
View File
@@ -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
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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"
)
@@ -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"
)
+1 -1
View File
@@ -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"
)
+1 -1
View File
@@ -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"
)
+1 -1
View File
@@ -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"
)
+1 -1
View File
@@ -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"
)
+1 -1
View File
@@ -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"
)
+3 -3
View File
@@ -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)
+5 -4
View File
@@ -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:
+2 -1
View File
@@ -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