mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
co-authored by
JerrettDavis
parent
9762a14a40
commit
f1bc260948
@@ -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
|
||||
|
||||
@@ -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
@@ -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,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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user