Files
headroom/tests/test_optional_dependencies.py
lorenzozaneandJerrettDavis a8905214d9 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>
2026-11-06 09:23:03 -06:00

219 lines
7.9 KiB
Python

from __future__ import annotations
import re
from pathlib import Path
from typing import Any
from packaging.markers import default_environment
from packaging.requirements import Requirement
try:
import tomllib
except ModuleNotFoundError: # pragma: no cover - Python 3.10 fallback
import tomli as tomllib # type: ignore[no-redef]
ROOT = Path(__file__).resolve().parents[1]
ALL_EXTRA = "all"
HEADROOM_PACKAGE_NAME = "headroom-ai"
MACOS_X86_64_TORCH_GUARD = "sys_platform != 'darwin' or platform_machine != 'x86_64'"
MACOS_X86_64_SYS_PLATFORM = "darwin"
MACOS_X86_64_PLATFORM_MACHINE = "x86_64"
PYPROJECT_FILE = "pyproject.toml"
SYS_PLATFORM_MARKER = "sys_platform"
PLATFORM_MACHINE_MARKER = "platform_machine"
TORCH_PACKAGE_NAME = "torch"
TORCH_TRANSITIVE_PACKAGE_NAMES = frozenset({"sentence-transformers"})
ORJSON_PACKAGE_NAME = "orjson"
PYTHON_SOCKS_PACKAGE_NAME = "python-socks"
PROXY_EXTRA = "proxy"
LEAN_EXTRA = "lean"
UV_LOCK_FILE = "uv.lock"
EXTRA_MARKER = re.compile(r"^extra == '([^']+)'$")
def _selected_dependency_names_for_extra(
optional_deps: dict[str, list[str]],
extra_name: str,
environment: dict[str, str],
visited: set[str] | None = None,
) -> set[str]:
selected: set[str] = set()
visited = visited or set()
if extra_name in visited:
return selected
visited.add(extra_name)
for dependency in optional_deps[extra_name]:
requirement = Requirement(dependency)
if requirement.marker is not None and not requirement.marker.evaluate(environment):
continue
if requirement.name == HEADROOM_PACKAGE_NAME:
for nested_extra in requirement.extras:
selected.update(
_selected_dependency_names_for_extra(
optional_deps,
nested_extra,
environment,
visited,
)
)
else:
selected.add(requirement.name)
return selected
def _locked_package(package_name: str) -> dict[str, Any]:
lock = tomllib.loads((ROOT / UV_LOCK_FILE).read_text(encoding="utf-8"))
packages: list[dict[str, Any]] = lock["package"]
for package in packages:
if package["name"] == package_name:
return package
raise AssertionError(f"{package_name} not found in {UV_LOCK_FILE}")
def _locked_dependency_names(package_name: str) -> set[str]:
package = _locked_package(package_name)
return {dependency["name"] for dependency in package.get("dependencies", [])}
def _locked_extra_requirements(
locked_extras: dict[str, list[dict[str, Any]]], extra_name: str
) -> dict[str, set[str]]:
"""Each package in an extra's flattened lock list, with the extras it requests.
A package can appear once bare and once with extras (`httpx`, `httpx[http2]`);
both mean one install, so the extras are merged.
"""
requirements: dict[str, set[str]] = {}
for dependency in locked_extras[extra_name]:
requirements.setdefault(dependency["name"], set()).update(dependency.get("extra", []))
return requirements
def test_all_extra_does_not_require_torch_on_macos_x86_64() -> None:
"""Keep `headroom-ai[all]` resolvable where PyTorch publishes no wheel."""
pyproject = tomllib.loads((ROOT / PYPROJECT_FILE).read_text(encoding="utf-8"))
optional_deps = pyproject["project"]["optional-dependencies"]
macos_x86_64_environment = default_environment()
macos_x86_64_environment.update(
{
SYS_PLATFORM_MARKER: MACOS_X86_64_SYS_PLATFORM,
PLATFORM_MACHINE_MARKER: MACOS_X86_64_PLATFORM_MACHINE,
}
)
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
for extra_name in ("ml", "voice")
for dep in optional_deps[extra_name]
if dep.startswith(TORCH_PACKAGE_NAME)
]
selected_all_dependency_names = _selected_dependency_names_for_extra(
optional_deps,
ALL_EXTRA,
macos_x86_64_environment,
)
locked_torch_transitive_dependency_names = {
package_name
for package_name in TORCH_TRANSITIVE_PACKAGE_NAMES
if TORCH_PACKAGE_NAME in _locked_dependency_names(package_name)
}
assert torch_deps
assert all(MACOS_X86_64_TORCH_GUARD in dep for dep in torch_deps)
assert locked_torch_transitive_dependency_names
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)."""
pyproject = tomllib.loads((ROOT / PYPROJECT_FILE).read_text(encoding="utf-8"))
optional_deps = pyproject["project"]["optional-dependencies"]
environment = default_environment()
selected_proxy_dependency_names = _selected_dependency_names_for_extra(
optional_deps,
PROXY_EXTRA,
environment,
)
selected_all_dependency_names = _selected_dependency_names_for_extra(
optional_deps,
ALL_EXTRA,
environment,
)
assert ORJSON_PACKAGE_NAME in selected_proxy_dependency_names
assert ORJSON_PACKAGE_NAME in selected_all_dependency_names
def test_proxy_extra_includes_socks_support_for_websocket_proxy_discovery() -> None:
"""A system SOCKS proxy must not disable Codex Responses WebSockets."""
pyproject = tomllib.loads((ROOT / PYPROJECT_FILE).read_text(encoding="utf-8"))
optional_deps = pyproject["project"]["optional-dependencies"]
environment = default_environment()
selected_proxy_dependency_names = _selected_dependency_names_for_extra(
optional_deps,
PROXY_EXTRA,
environment,
)
assert PYTHON_SOCKS_PACKAGE_NAME in selected_proxy_dependency_names
def test_locked_composite_extras_include_their_nested_extras() -> None:
"""`uv sync --extra lean` must install everything `--extra proxy` does.
uv installs an extra from its own flattened list in uv.lock, and neither
`uv lock --check` nor a plain `uv lock` re-derives that list when a nested
extra gains a dependency: python-socks reached `proxy` but not `lean`.
"""
package = _locked_package(HEADROOM_PACKAGE_NAME)
locked_extras = package["optional-dependencies"]
composites = {
match.group(1): requirement["extras"]
for requirement in package["metadata"]["requires-dist"]
if requirement["name"] == HEADROOM_PACKAGE_NAME
and (match := EXTRA_MARKER.match(requirement.get("marker", "")))
}
missing: dict[str, list[str]] = {}
for composite, nested in composites.items():
locked = _locked_extra_requirements(locked_extras, composite)
for nested_extra in nested:
for name, extras in _locked_extra_requirements(locked_extras, nested_extra).items():
if name not in locked or not extras <= locked[name]:
missing.setdefault(composite, []).append(f"{name} (from {nested_extra})")
assert LEAN_EXTRA in composites
assert missing == {}