fix(packaging)!: keep PyTorch extras out of all (#4067)

<!-- maintainer-current-main -->
## Maintainer latest-main checkpoint
Published `fb146c0663b30488da0a49cfb33624ee82862074` contains current
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 22
dependency/Gemini tests and lock check passed. Earlier live behavior
proofs below retain their commit/platform scope; contributor runtime
logic is unchanged.

The common shard-2 failure was independently confirmed on main's hosted
job 127069149772 and locally (four failures, six passes): the Gemini
memory fixture mocked an unused body reader and provided no request
stream. The maintainer test-only follow-up now constructs a real
FastAPI/ASGI Request carrying JSON bytes and exercises the actual body
reader. All six test-function ASTs/assertions are unchanged, and all 10
parameterized Gemini cases pass. Touched-file Ruff/format and whitespace
checks pass. This fixes the inherited fixture instead of asking
contributors to run CI or weakening the memory/content assertions. Fresh
exact-head hosted qualification is requested. Nothing merged.
<!-- /maintainer-current-main -->

## Description



On Linux, installing `headroom-ai[all]` resolved PyTorch and NVIDIA CUDA
packages even for users who only needed the CLI/proxy profile. The
locked dependency graph included those packages through `ml`, `memory`,
`evals`, and `voice`.



This keeps those PyTorch-backed extras available for explicit
installation while removing them from `[all]`. Image support and the
other CLI/proxy dependencies remain included; dependency metadata cannot
detect installed GPU hardware.



Closes #3339



## Type of Change



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

- [ ] New feature (non-breaking change that adds functionality)

- [x] Breaking change (fix or feature that would cause existing
functionality to change)

- [ ] Documentation update

- [ ] Performance improvement

- [ ] Code refactoring (no functional changes)



## Changes Made



- Remove `ml`, `memory`, `evals`, and `voice` from the `[all]` extra
while keeping each separately installable.

- Retain `image` and the other default CLI/proxy capabilities.

- Update README and installation docs to describe the opt-in extras and
CUDA package implications.

- Add a dependency contract assertion for the `[all]` extra.



## Testing



- [ ] Unit tests pass (`pytest`)

- [ ] Linting passes (`ruff check .`)

- [ ] Type checking passes (`mypy headroom`)

- [ ] New tests added for new functionality

- [x] Manual testing performed



### Test Output



```text

Focused dependency contract tests: 3 passed, 5 deselected.

Python 3.13 locked `uv export` exited 0; the fixed export omits torch, CUDA, NVIDIA, sentence-transformers, and datasets. The baseline export contained them.

`uv lock --check`, scoped Ruff check/format, and `git diff --check` exited 0.

The broader dependency test module had 3 passed and 5 import failures because `opentelemetry` is absent from the local environment.

```



## Real Behavior Proof



- Environment: Linux, Python 3.13, locked uv dependency resolution.

- Exact command / steps: `UV_PYTHON_DOWNLOADS=never uv export --python
3.13 --extra all --no-dev --locked --no-hashes --no-emit-project`.

- Observed result: exit 0; the resolved export no longer contains torch,
CUDA, NVIDIA, sentence-transformers, or datasets, all of which were
present in the baseline export.

- Not tested: a full environment install and GPU runtime behavior.



## Runtime Rollout Safety



- Rollout-managed feature(s): None.

- Minimum rollout channel: Stable package release.

- Stable/default behavior changed: Yes; `[all]` no longer installs the
four PyTorch-backed extras.

- Kill switch / disable path: Not applicable; install the desired extras
explicitly.

- Unsafe override required: No.

- Qualification impact: Users of those capabilities must add the
corresponding extras.

- Rollback path: Restore the extras to `[all]` and regenerate `uv.lock`.



## 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

- [ ] I have commented my code, particularly in hard-to-understand areas

- [x] I have made corresponding changes to the documentation

- [ ] My changes generate no new warnings

- [x] I have added tests that prove my fix is effective or that my
feature works

- [ ] New and existing unit tests pass locally with my changes

- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)



## Screenshots (if applicable)



Not applicable to this dependency-resolution change.



## Additional Notes



The `[all]` install profile intentionally no longer includes
PyTorch-backed optional capabilities; each remains available through its
named extra. The focused regression and locked resolver proof passed,
but the full dependency test module and a full install were not verified
locally.





## Maintainer integration qualification

Published head `3229690b613810d496f015cedd086ca1d7421843` includes
current upstream main `31dcaf41`. The merge preserves main's `lean`
dependency profile and deprecated `sandbox` alias alongside the
contributor's opt-in `[all]` policy. No optional-feature runtime logic
was changed.



- Reconciled the existing macOS dependency test with the declared
policy, retaining the transitive exclusion check and independently
verifying explicit `ml`/`voice` opt-ins on Intel macOS and Linux. All 12
tests across `tests/test_onnx_dependency_contract.py` and
`tests/test_optional_dependencies.py` pass on Windows/Python 3.12.13.

- Evaluation workflow installs now explicitly request `evals`, and the
model-allowed weekly job also requests `ml`, preserving its previous
intended dependencies. The evaluation guide and AI install index
identify those opt-ins. These address the existing Devin workflow/docs
findings.

- `uv lock --check`, touched Python Ruff/format and whitespace checks
pass. All 253 locked package versions are unchanged; only the root
`[all]` dependency metadata/flattened list changes.

- Real resolver commands from this checkout: `uv export --extra all
--no-dev --locked --no-hashes --no-emit-project` and `uv export --extra
all --extra ml --extra voice --extra evals --no-dev --locked --no-hashes
--no-emit-project`. Evaluating their actual requirement markers for
Python 3.12/3.13/3.14 on Linux x86_64, Windows AMD64, macOS arm64 and
macOS x86_64 shows `[all]` excludes torch, sentence-transformers,
datasets and CUDA/NVIDIA packages in all 12 environments. Explicit
opt-ins retain datasets and torch where supported; Intel macOS still
excludes torch.

- Not tested: a fresh full environment install, GPU runtime, live paid
evaluations or a fresh native build. Hosted CI must qualify the
published final head separately.



### Maintainer current-main requalification

Exact head `f1ed1e0019037e7b53ff9ef548843449c3c7a16f`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Current-main integration against upstream
c01cf07d94. The sole conflict was the
inherited Gemini fixture: adopted main's streamed-body helper after
verifying all six test-function ASTs unchanged. No contributor
dependency policy rewritten. The declared breaking change keeps
Torch-backed ml/memory/evals/voice opt-in while preserving the default
CLI/proxy bundle, image capability and main's lean profile. Evaluation
workflows and guides explicitly request removed extras; current
author/Devin discussion considered.

Fresh verification: 25 dependency/Gemini tests pass; offline uv lock
check resolves 253 packages; changed Python lint/format and
main-relative whitespace pass. Actual locked exports evaluated over 12
OS/Python marker environments (Linux/Windows/macOS, Python 3.10–3.13):
all excludes Torch/NVIDIA dependencies, explicit
all+ml+memory+evals+voice retains Torch. This is resolver/export proof,
not a fresh full installation or GPU runtime claim. No new source
blocker found; formal approval awaits exact-head hosted checks. Nothing
merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
lorenzozane
2026-11-06 09:23:03 -06:00
committed by GitHub
co-authored by JerrettDavis
parent 8cdce172ea
commit a8905214d9
9 changed files with 61 additions and 34 deletions
+3 -3
View File
@@ -49,7 +49,7 @@ jobs:
- name: Install dependencies (builds Rust extension via maturin)
run: |
pip install -e ".[all]"
pip install -e ".[all,evals]"
python -c "from headroom._core import SmartCrusher; print('headroom._core OK:', SmartCrusher)"
- name: Run CCR round-trip (zero cost)
@@ -119,7 +119,7 @@ jobs:
- name: Install dependencies (builds Rust extension via maturin)
run: |
pip install -e ".[all]"
pip install -e ".[all,evals,ml]"
python -c "from headroom._core import SmartCrusher; print('headroom._core OK')"
- name: Run Tier 1 evaluation suite
run: |
@@ -157,7 +157,7 @@ jobs:
# Real-dataset recall on the prose path (HotpotQA): does the ground-truth
# answer survive compressing the supporting context? Uses the production
# routing path, so prose flows through Kompress (ModernBERT) — allowed here
# because the weekly job installs [all]. Non-blocking and defensive: a
# because the weekly job explicitly installs [ml]. Non-blocking and defensive: a
# dataset download or model failure warns rather than fails the job.
- name: Dataset recall report — HotpotQA (model-allowed, non-blocking)
run: |
+7 -3
View File
@@ -481,14 +481,18 @@ orchestration stays focused on lifecycle, sequencing and policy:
```bash
uv tool install --python 3.13 "headroom-ai[all]" # CLI, isolated app env
pip install "headroom-ai[all]" # Python, everything — includes the CLI
pip install "headroom-ai[all]" # CLI/proxy feature set
npm install headroom-ai # TypeScript SDK (library only)
docker pull ghcr.io/headroomlabs-ai/headroom:latest
```
`[all]` includes the CLI/proxy feature set, including image support, without PyTorch-backed dependencies.
Add `[ml]`, `[memory]`, `[evals]`, or `[voice]` separately for those features;
their PyTorch dependency can install CUDA runtime packages on Linux.
Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`,
`[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain, not in
`[all]`), `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`,
`[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain),
`[relevance]`, `[image]`, `[lean]` (torch-free proxy dependency profile; `[sandbox]` is a deprecated alias), `[agno]`, `[langchain]`, `[evals]`, `[voice]`, and
`[pytorch-mps]` (Apple-GPU memory-embedder offload — set
`HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.11+**.
+9 -8
View File
@@ -87,7 +87,7 @@ The core package includes the `compress()` function, SmartCrusher, CacheAligner,
### Extras
Install only what you need, or grab everything with `[all]`:
Install only what you need, or use `[all]` for the default CLI/proxy feature set:
```bash
pip install "headroom-ai[all]"
@@ -97,16 +97,16 @@ pip install "headroom-ai[all]"
|---|---|---|
| `proxy` | Proxy server, HTTP API, MCP runtime, local ONNX Kompress path | `pip install "headroom-ai[proxy]"` |
| `proxy-prod` | `proxy` plus gunicorn on Unix production hosts | `pip install "headroom-ai[proxy,proxy-prod]"` |
| `ml` | PyTorch/Hugging Face Kompress backend and model tooling | `pip install "headroom-ai[ml]"` |
| `ml` | PyTorch/Hugging Face Kompress backend and model tooling; opt-in, not in `[all]` | `pip install "headroom-ai[ml]"` |
| `code` | CodeCompressor (tree-sitter AST parsing) | `pip install "headroom-ai[code]"` |
| `memory` | Persistent memory (sqlite-vec, sentence-transformers) — pure-Python default backend, no compiler | `pip install "headroom-ai[memory]"` |
| `memory` | Persistent memory (sqlite-vec, sentence-transformers); opt-in, not in `[all]` | `pip install "headroom-ai[memory]"` |
| `vector` | Optional HNSW vector backend (hnswlib) — needs a C++ toolchain; **not in `[all]`** | `pip install "headroom-ai[vector]"` |
| `memory-stack` | Optional Qdrant + Neo4j memory backend helpers; **not in `[all]`**. Headroom turns off Mem0's PostHog telemetry by default; set `MEM0_TELEMETRY=True` to allow it | `pip install "headroom-ai[memory-stack]"` |
| `relevance` | fastembed-based relevance scoring (BAAI/bge-small-en-v1.5, ONNX) | `pip install "headroom-ai[relevance]"` |
| `image` | Image compression (Pillow, ONNX runtime, OCR) | `pip install "headroom-ai[image]"` |
| `reports` | HTML/Markdown report generation (Jinja2) | `pip install "headroom-ai[reports]"` |
| `otel` | OpenTelemetry exporter (OTLP) | `pip install "headroom-ai[otel]"` |
| `voice` | Voice/audio support | `pip install "headroom-ai[voice]"` |
| `voice` | Voice/audio support; opt-in, not in `[all]` | `pip install "headroom-ai[voice]"` |
| `voice-train` | Voice training dependencies; **not in `[all]`** | `pip install "headroom-ai[voice-train]"` |
| `mcp` | MCP server tools (`headroom_compress`, `headroom_retrieve`, `headroom_stats`) | `pip install "headroom-ai[mcp]"` |
| `langchain` | LangChain `HeadroomChatModel` wrapper; **not in `[all]`** | `pip install "headroom-ai[langchain]"` |
@@ -117,15 +117,16 @@ pip install "headroom-ai[all]"
| `anyllm` | any-llm multi-provider backend (Python 3.11+); **not in `[all]`** | `pip install "headroom-ai[anyllm]"` |
| `bedrock` | Native AWS Bedrock credentials/backend support; **not in `[all]`** | `pip install "headroom-ai[bedrock]"` |
| `redis` | Redis client for state shared across replicas (`HEADROOM_CCR_BACKEND=redis`, `HEADROOM_COMPRESS_SESSION_STORE`); **not in `[all]`**, included in every Docker image | `pip install "headroom-ai[redis]"` |
| `evals` | Evaluation framework (GSM8K, SQuAD, BFCL benchmarks) | `pip install "headroom-ai[evals]"` |
| `evals` | Evaluation framework (GSM8K, SQuAD, BFCL benchmarks); opt-in, not in `[all]` | `pip install "headroom-ai[evals]"` |
| `pytorch-mps` | Apple-GPU (MPS) memory-embedder offload — **macOS only**, not in `[all]` (torch + sentence-transformers); opt in with `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` | `pip install "headroom-ai[pytorch-mps]"` |
| `html` | HTML main-content extraction with trafilatura | `pip install "headroom-ai[html]"` |
| `spreadsheet` | `.xlsx` / `.xls` ingestion with openpyxl and xlrd | `pip install "headroom-ai[spreadsheet]"` |
| `lean` | Torch-free proxy bundle for constrained environments (a dependency profile; it provides no isolation). `sandbox` is a deprecated alias | `pip install "headroom-ai[lean]"` |
| `all` | Runtime bundle: `proxy,code,ml,memory,relevance,image,reports,otel,evals,voice,html,mcp,spreadsheet` | `pip install "headroom-ai[all]"` |
| `all` | CLI/proxy feature set without PyTorch-backed dependencies | `pip install "headroom-ai[all]"` |
`[all]` is the full built-in runtime bundle, not every integration or optional
backend. The rows marked “not in `[all]`” must be requested explicitly.
`[all]` is the built-in CLI/proxy feature set, not every integration or
PyTorch-backed feature. The rows marked “not in `[all]`” must be requested
explicitly. PyPI's Linux PyTorch wheels can include CUDA runtime packages.
You can combine extras:
+2 -2
View File
@@ -25,7 +25,7 @@ Model: `gpt-4o-mini` | Suite cost: ~$3 | Duration: ~15 min
## Installation
```bash
pip install "headroom-ai[all]" # Everything including evals (recommended)
pip install "headroom-ai[all,evals]" # CLI/proxy feature set plus evaluation dependencies
pip install "headroom-ai[evals]" # Evaluation framework only
```
@@ -234,7 +234,7 @@ jobs:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.11" }
- run: pip install -e ".[all]"
- run: pip install -e ".[all,evals]"
- name: CCR Round-trip (zero cost)
run: |
python -c "
+1 -1
View File
@@ -17,7 +17,7 @@ The canonical, always-current documentation index lives at the docs site below.
## Install (copy-paste-runnable)
- Python: `pip install headroom-ai` is enough for `compress()`; add `[proxy]` for the HTTP proxy and `headroom wrap`, `[all]` for every optional extra
- Python: `pip install headroom-ai` is enough for `compress()`; add `[proxy]` for the HTTP proxy and `headroom wrap`, `[all]` for the CLI/proxy feature set. PyTorch-backed `[ml]`, `[memory]`, `[evals]`, and `[voice]` are separate opt-ins.
- TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
- Docker local: `docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0`
- Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
+4 -2
View File
@@ -361,7 +361,9 @@ dev = [
"cryptography>=50.0.0",
"respx>=0.20.0", # HTTP mock transport for passthrough handler tests
]
# All optional dependencies (everything you need).
# All optional dependencies for the default CLI/proxy feature set.
# PyTorch-backed features stay opt-in because Linux PyPI wheels include CUDA
# runtime packages and dependency metadata cannot detect installed hardware.
#
# The EleutherAI lm-evaluation-harness is intentionally not exposed as a
# project extra. Headroom invokes it as an external subprocess
@@ -371,7 +373,7 @@ dev = [
# who need standard accuracy benchmarks can install `lm-eval[api]` in their
# benchmark environment separately.
all = [
"headroom-ai[proxy,code,ml,memory,relevance,image,reports,otel,evals,voice,html,mcp,spreadsheet]",
"headroom-ai[proxy,code,relevance,image,reports,otel,html,mcp,spreadsheet]",
]
# Lean: a proxy with ALL torch-free capability — for running Headroom in a
# constrained or low-resource environment and offloading heavy ML elsewhere.
+12 -6
View File
@@ -76,15 +76,21 @@ def test_intel_macos_python314_omits_ort_dependent_optional_backends() -> None:
assert not selected & ort_backends, (extra, selected & ort_backends)
def test_all_extra_includes_proxy_and_voice() -> None:
def test_all_extra_includes_proxy_without_torch_dependency_extras() -> None:
project = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]
all_requirements = project["optional-dependencies"]["all"]
optional = project["optional-dependencies"]
all_requirements = optional["all"]
assert any(
requirement.name == "headroom-ai" and {"proxy", "voice"} <= set(requirement.extras)
included_extras = {
extra
for raw_requirement in all_requirements
if (requirement := Requirement(raw_requirement))
)
if (requirement := Requirement(raw_requirement)) and requirement.name == "headroom-ai"
for extra in requirement.extras
}
assert {"proxy", "image"} <= included_extras
assert not {"ml", "memory", "evals", "voice"} & included_extras
assert {"ml", "memory", "evals", "voice", "sandbox"} <= optional.keys()
@pytest.mark.proxy_dependency_gate
+22 -2
View File
@@ -105,8 +105,14 @@ def test_all_extra_does_not_require_torch_on_macos_x86_64() -> None:
}
)
assert "ml" in optional_deps[ALL_EXTRA][0]
assert "voice" in optional_deps[ALL_EXTRA][0]
all_requirements = [Requirement(dep) for dep in optional_deps[ALL_EXTRA]]
all_nested_extras = {
extra
for requirement in all_requirements
if requirement.name == HEADROOM_PACKAGE_NAME
for extra in requirement.extras
}
assert not {"ml", "memory", "evals", "voice"} & all_nested_extras
torch_deps = [
dep
@@ -131,6 +137,20 @@ def test_all_extra_does_not_require_torch_on_macos_x86_64() -> None:
assert TORCH_PACKAGE_NAME not in selected_all_dependency_names
assert selected_all_dependency_names.isdisjoint(locked_torch_transitive_dependency_names)
# Explicit opt-ins still honor the Intel macOS wheel guard independently
# of whether the default installation profile requests them.
for extra_name in ("ml", "voice"):
selected = _selected_dependency_names_for_extra(
optional_deps, extra_name, macos_x86_64_environment
)
assert TORCH_PACKAGE_NAME not in selected
assert selected.isdisjoint(locked_torch_transitive_dependency_names)
linux_environment = dict(macos_x86_64_environment, sys_platform="linux")
assert TORCH_PACKAGE_NAME in _selected_dependency_names_for_extra(
optional_deps, extra_name, linux_environment
)
def test_proxy_extra_includes_orjson_for_litellm_backends() -> None:
"""`headroom-ai[all]` must ship orjson for LiteLLM provider backends (GH #2056)."""
Generated
+1 -7
View File
@@ -1441,12 +1441,9 @@ agno = [
{ name = "agno" },
]
all = [
{ name = "anthropic" },
{ name = "datasets" },
{ name = "fastapi" },
{ name = "fastembed", marker = "python_full_version < '3.14' or platform_machine != 'x86_64' or sys_platform != 'darwin'" },
{ name = "httpx", extra = ["http2"] },
{ name = "huggingface-hub" },
{ name = "jinja2" },
{ name = "magika", marker = "python_full_version < '3.14' or platform_machine != 'x86_64' or sys_platform != 'darwin'" },
{ name = "mcp" },
@@ -1462,12 +1459,9 @@ all = [
{ name = "python-socks" },
{ name = "rapidocr", marker = "(python_full_version >= '3.13' and platform_machine != 'x86_64') or (python_full_version == '3.13.*' and platform_machine == 'x86_64' and sys_platform == 'darwin') or (python_full_version >= '3.13' and sys_platform != 'darwin')" },
{ name = "rapidocr-onnxruntime", marker = "python_full_version < '3.13'" },
{ name = "scikit-learn" },
{ name = "sentence-transformers", marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'" },
{ name = "sentencepiece" },
{ name = "sqlite-vec" },
{ name = "starlette" },
{ name = "torch", marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'" },
{ name = "trafilatura" },
{ name = "transformers" },
{ name = "tree-sitter" },
@@ -1726,7 +1720,7 @@ requires-dist = [
{ name = "gunicorn", marker = "sys_platform != 'win32' and extra == 'proxy-prod'", specifier = ">=21.0.0" },
{ name = "headroom-ai", extras = ["lean"], marker = "extra == 'sandbox'" },
{ name = "headroom-ai", extras = ["proxy"], marker = "extra == 'proxy-prod'" },
{ name = "headroom-ai", extras = ["proxy", "code", "ml", "memory", "relevance", "image", "reports", "otel", "evals", "voice", "html", "mcp", "spreadsheet"], marker = "extra == 'all'" },
{ name = "headroom-ai", extras = ["proxy", "code", "relevance", "image", "reports", "otel", "html", "mcp", "spreadsheet"], marker = "extra == 'all'" },
{ name = "headroom-ai", extras = ["proxy", "code", "relevance", "reports", "otel", "html", "mcp", "spreadsheet"], marker = "extra == 'lean'" },
{ name = "headroom-ai", extras = ["voice"], marker = "extra == 'voice-train'" },
{ name = "hf-xet", marker = "platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'", specifier = ">=1.6.0" },