mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
<!-- 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>
219 lines
7.9 KiB
Python
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 == {}
|