Commit Graph
5 Commits
Author SHA1 Message Date
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
Kenneth WongandKenneth Wong b5c52647b4 test(deps): fail when a composite extra's uv.lock list drops a nested extra's package (#4598)
## Description

Adds a regression test for a `uv.lock` drift that left `uv sync --extra
lean` without `python-socks`, while `--extra proxy` and the deprecated
`--extra sandbox` alias (which is just `lean`) installed it.

**Scope change:** this PR originally also carried the one-line `uv.lock`
fix. #4614 has since re-locked `main` and picked up the same
`python-socks` line under `lean` ("uv flattening the existing `proxy`
extra that `lean` already includes", per its commit message), so after
rebasing onto `main` (`7e0094d6`) the fix commit was empty and dropped.
What remains is the test that catches this class of drift.

Background: #3357 added `python-socks[asyncio]` to the `proxy` extra
after #3727 had renamed `sandbox` to `lean`. In `uv.lock`, each extra
has its own flattened dependency list, and the `lean` list kept its old
contents. `uv lock --check` accepts a stale list and a plain `uv lock`
leaves it alone, so nothing in CI caught it. The existing
`test_proxy_extra_includes_socks_support_for_websocket_proxy_discovery`
only reads `pyproject.toml`, which is why it stayed green.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
- [x] Test-only change (regression guard)

## Changes Made

- `tests/test_optional_dependencies.py`:
`test_locked_composite_extras_include_their_nested_extras` checks that
every composite extra in `uv.lock` (`lean`, `sandbox`, `all`,
`proxy-prod`, `voice-train`, read from the `headroom-ai[...]`
self-references in `requires-dist`) lists each package its nested extras
list, with at least the same package extras. It reads `uv.lock` directly
with `tomllib`, so it needs no `uv` binary and runs in the normal pytest
shards.

No `uv.lock`, `pyproject.toml` or runtime code changes.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_optional_dependencies.py                     # this branch, on main 7e0094d6
4 passed in 0.82s

$ git show fc1ba891:uv.lock > uv.lock                                 # lock from before #4614
$ pytest -q tests/test_optional_dependencies.py -k composite
E     {'lean': ['python-socks (from proxy)']}
1 failed, 3 deselected in 0.50s

$ ruff check tests/test_optional_dependencies.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS 27 (arm64), Python 3.11.17, branch rebased onto
`main` at `7e0094d6`.
- Exact command / steps: run the new test against `main`'s current
`uv.lock`, then against the `uv.lock` from `fc1ba891` (before #4614).
- Observed result: passes on the current lock; fails on the old lock,
naming the missing package and the extra it comes from.
- Not tested: n/a; the change is a test only.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a, test-only change
- Stable/default behavior changed: no
- Kill switch / disable path: none needed
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit

## 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
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] 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)

N/A

## Additional Notes

`mypy headroom` is unaffected (test-only change). The commit message's
"on main's lock it fails" refers to the lock before #4614.

https://claude.ai/code/session_01S4VPhWACY6qi2jBcN3M2sr

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
2026-11-03 17:02:55 -06:00
CtrlCreeperandJerrettDavis 79181ca0fe fix(proxy): install SOCKS support for websocket proxies (#3357)
## Description

Install the SOCKS transport dependency required when `websockets`
discovers a system SOCKS proxy. Without it, Codex Responses WebSocket
relay logs `connecting through a SOCKS proxy requires python-socks` and
cannot establish the upstream WebSocket.


## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Add `python-socks[asyncio]>=2.7.1` to the `proxy` extra.
- Regenerate `uv.lock`, resolving `python-socks` 3.1.1. Existing package
versions are unchanged relative to the refreshed main parent.
- Add a package-contract regression test that asserts
`headroom-ai[proxy]` includes the SOCKS transport dependency.

## Testing

- [x] Focused optional-dependency tests pass
- [x] Full branch Ruff lint and formatting checks pass
- [ ] Type checking
- [x] Package-contract regression test added
- [x] Manual SOCKS runtime verification performed

### Test Output

```text
$ python -m pytest tests/test_optional_dependencies.py -q
3 passed
$ uv lock --check
Resolved 252 packages in 5ms
$ ruff check .
All checks passed!
$ ruff format --check .
1715 files already formatted
```

Validation used Python 3.12.11 and Ruff 0.16.8. Comparing package
versions against the refreshed main parent found no existing package
version changes; only `python-socks` 3.1.1 was added. The full test
suite was not rerun locally. The existing hosted `test (2)` failure is
`test_category_losing_its_last_pattern_drops_its_heading`, which the
maintainer previously reproduced on main.

## Real Behavior Proof

- Environment: macOS 26.6.2, Apple Silicon arm64, Python 3.12.11,
`websockets` 16.0, locked `python-socks` 3.1.1, live SOCKS proxy at
`127.0.0.1:7897`, existing Sub2API OpenAI-compatible provider.
- Exact steps: create an isolated environment containing
`websockets==16.0` and no `python-socks`. Set
`wss_proxy=socks5://127.0.0.1:7897` so `websockets` automatically
discovers the SOCKS proxy. Call `websockets.connect(<real upstream
/v1/responses WebSocket URL>, additional_headers=<existing bearer>,
ssl=<configured TLS context>, open_timeout=30)` without an explicit
proxy argument. Repeat with `python-socks[asyncio]==3.1.1` installed,
using the same endpoint, proxy, credential, and TLS context.
- Installation commands:

```sh
uv venv <before-env> --python 3.12
uv pip install --python <before-env>/bin/python websockets==16.0
uv pip install --python <after-env>/bin/python 'python-socks[asyncio]==3.1.1'
```

Captured runtime output on 2026-10-07:

```text
# Before
Python: 3.12.11
websockets: 16.0 ; python-socks: not installed
Discovery: wss_proxy=socks5://127.0.0.1:7897; provider: existing Sub2API endpoint
Upstream WebSocket handshake: ImportError connecting through a SOCKS proxy requires python-socks

# After
Python: 3.12.11
websockets: 16.0 ; python-socks: 3.1.1
Discovery: wss_proxy=socks5://127.0.0.1:7897; provider: existing Sub2API endpoint
Upstream WebSocket handshake: InvalidStatus server rejected WebSocket connection: HTTP 426
```

- Observed result: the missing transport error is gone and the real
upstream returns an HTTP handshake response after connecting through
SOCKS. The upstream's HTTP 426 remains; this is not evidence of a
successful upstream WebSocket session.
- Provider/model scope: this is a transport/handshake check, so no model
request was sent. The fresh validation above specifically verifies the
locked 3.1.1 transport rather than claiming a model completion over
WebSocket.
- Version clarification: the original manual observation preceded the
refreshed lockfile. This new before/after run explicitly tests the
currently locked 3.1.1; it does not claim every version allowed by
`>=2.7.1` was tested.
- Not tested: clean install of a built Headroom distribution,
Linux/Windows runtime, successful upstream WebSocket inference, or the
full suite.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: `headroom-ai[proxy]` and extras that
include it install one pure-Python SOCKS transport dependency; no
request routing or compression behavior changes without a SOCKS proxy.
- Kill switch / disable path: remove SOCKS proxy configuration from the
process/system environment.
- Unsafe override required: no.
- Qualification impact: package extras and lockfile only.
- Rollback path: revert this commit or deploy the prior package release.

## 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 commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] 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)

N/A.

## Additional Notes

### Dependency review

- **Why this package:** `websockets` delegates its optional SOCKS
transport to `python-socks`; adding the `asyncio` extra supplies the API
its runtime imports. Reimplementing SOCKS in Headroom would duplicate
that upstream transport without changing the integration point.
- **Maintainer and activity:** upstream is
[romis2012/python-socks](https://github.com/romis2012/python-socks),
maintained under the `romis2012` account. The repository is not
archived. Recent GitHub releases include 2.8.2 (2026-06-23), 3.0.0
(2026-08-11), and 3.1.0/3.1.1 (2026-09-08).
- **Security history checked:** an [OSV](https://osv.dev/) query for
PyPI `python-socks` 3.1.1 on 2026-10-07 returned no advisory records for
that version. This is a bounded database check, not a claim that the
package has never had a security issue.
- **Install surface:** the locked wheel is `py3-none-any` (pure Python).
On Python <3.11, the `asyncio` extra additionally requires
`async-timeout>=5.0.1`; on Python >=3.11 it adds no extra dependency.
The `trio` and `anyio` extras are not selected. Installation downloads
the package from PyPI; using the transport connects to the configured
SOCKS proxy and upstream. No separate native build or model download is
needed by this dependency.
- **Why this version:** the new dependency is needed for SOCKS
functionality in `websockets`, not a cosmetic upgrade. The requirement
remains `python-socks[asyncio]>=2.7.1`; the refreshed lock resolves
3.1.1, and the current runtime proof tests that exact release. Existing
package versions are unchanged relative to the refreshed main parent.

The package-contract test verifies the install extra. The real network
handshake above separately verifies runtime transport discovery.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3357"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
## Maintainer qualification — current main refresh

Current head: `0caa86656b9876705bfd80bd590070159e70df27`, containing
main `01d9194854233ef6ed04005cf0a5b8c32bf65d6d`.

The metadata/lock conflict retains current main's packaging and adds the
original `python-socks[asyncio]>=2.7.1` proxy dependency. The
regenerated lock preserves all 251 main package identities and all
existing non-project package records, adding only `python-socks`
**3.1.1**. Current qualification targets that locked release; any
earlier 3.0.0 report is historical rather than evidence for the
currently locked package.

Validation: three optional-dependency tests pass; Ruff, formatting, and
changed-file whitespace checks pass. A controlled runtime check on
Windows with Python **3.12.13**, `python-socks` **3.1.1**, and
`websockets` **16.0** established a WebSocket through a loopback SOCKS5
server and round-tripped `headroom-socks-runtime-probe`. Captured
output: `PASS loopback WebSocket through SOCKS5: Python 3.12.13,
python-socks 3.1.1, websockets 16.0; no provider/model used`.

This is a local transport smoke check, with no provider/model or
external provider request. It establishes the selected transport
dependency loads and works together with the WebSocket client; it does
not claim production-provider qualification. Hosted checks on the
refreshed head still require completion, and the existing
dependency-provenance review remains available for reconciliation. No PR
merge performed.
Dependency provenance for the currently locked **3.1.1** release: PyPI
and installed wheel metadata identify
`https://github.com/romis2012/python-socks`; the upstream repository is
not archived and reports activity on **2026-09-08**. The license is
**Apache-2.0**. The installed wheel is pure Python (`Root-Is-Purelib:
true`, `py3-none-any`). The selected asyncio extra requires
`async-timeout>=5.0.1` only on Python below 3.11; Trio and AnyIO
dependencies are optional extras and are not selected by this change. A
targeted OSV query for PyPI `python-socks` **3.1.1** on **2026-10-09**
returned no vulnerability records. Captured package metadata, repository
metadata, OSV response, and the controlled transport output support this
current-release qualification.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 17:53:51 -05:00
4f3d5ab341 fix(install): add orjson to [proxy] extra for LiteLLM provider backends (#2074)
## Description
Add `orjson` to the `[proxy]` extra so `uv tool install
"headroom-ai[all]"` installs a runtime dependency required by LiteLLM
provider backends (e.g. OpenRouter).

## Type of Change
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- Add `orjson>=3.9.14; platform_python_implementation != 'PyPy'` to
`[proxy]`.
- Regression test in `tests/test_optional_dependencies.py`.
- Minimal `uv.lock` update (proxy/all optional-deps + metadata only).

## Motivation
Fixes #2056. `headroom-ai[all]` installs `litellm` (core dep) but not
`orjson`. LiteLLM provider backends import `orjson` at runtime; LiteLLM
only declares it under `litellm[proxy]`, not base deps. Headroom does
not depend on `litellm[proxy]` (would pull the full LiteLLM proxy server
stack).

## Testing
- `uv run --extra dev python -m pytest
tests/test_optional_dependencies.py -q` — 2 passed
- `uvx --from ruff==0.15.17 ruff check
tests/test_optional_dependencies.py`
- `uvx --from ruff==0.15.17 ruff format --check
tests/test_optional_dependencies.py`

## Real Behavior Proof
- **Setup:** Ubuntu, Python 3.12.3
- **Verified:** dependency graph test confirms `orjson` is selected for
`[proxy]` and `[all]` extras after this patch.
- **Not tested locally:** full `uv tool install` end-to-end (local sdist
build requires Rust/C++ toolchain unavailable in this environment).
Reporter workaround `uv tool install ... --with orjson` confirms the
missing transitive dep diagnosis.

## Review Readiness
- [x] I have performed a self-review of my code
- [x] This PR is ready for human review

## Notes
- Reporter used Python 3.14.4; `litellm` is intentionally skipped on
3.14 (GH #956). This PR fixes the missing `orjson` install path for
supported Python versions using `[all]`.

Co-authored-by: syf2211 <syf2211@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-13 09:37:28 -04:00
Ben Younes fd0d29c92d fix(packaging): guard torch extras on intel macos (#2011)
## Description

Closes #1931

Guard the `ml` and `voice` `torch` optional dependencies on macOS x86_64
so `headroom-ai[all]` remains resolvable on Intel Macs where PyTorch
does not publish compatible wheels for this version floor. The lockfile
metadata is updated with the same markers.

## Type of Change

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring
- [ ] Performance improvement
- [ ] Test update
- [ ] Other

## Changes Made

- Added macOS x86_64 environment markers to `torch` in the `ml` and
`voice` extras.
- Updated `uv.lock` optional dependency metadata to match the guarded
extras.
- Added a packaging regression test that checks `[all]` keeps `ml` and
`voice` while guarding `torch` on macOS x86_64.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Formatting verified (`ruff format --check`)
- [ ] Manual testing performed

### Test Output

```text
$ python3 -m pytest tests/test_optional_dependencies.py -q
collected 1 item

tests/test_optional_dependencies.py .                                    [100%]

============================== 1 passed in 0.26s ===============================

$ .venv/bin/ruff check tests/test_optional_dependencies.py
All checks passed!

$ .venv/bin/ruff format --check tests/test_optional_dependencies.py pyproject.toml
1 file already formatted
```

## Test verification (RED -> GREEN)

RED, with the `torch` markers temporarily removed from `pyproject.toml`:

```text
tests/test_optional_dependencies.py F                                    [100%]
FAILED tests/test_optional_dependencies.py::test_all_extra_does_not_require_torch_on_macos_x86_64
E   assert False
```

GREEN, with this patch applied:

```text
tests/test_optional_dependencies.py .                                    [100%]
============================== 1 passed in 0.26s ===============================
```

## Real Behavior Proof

- Environment: Linux, Python 3.12.3, pytest 9.1.1, ruff 0.14.14.
- Exact command / steps: Removed the environment markers from `torch`,
ran the new packaging test, restored the markers, and reran the test
plus targeted ruff checks.
- Observed result: The test fails without the macOS x86_64 guard and
passes once the `ml` and `voice` `torch` requirements are guarded.
- Not tested: Full `uv run pytest`, full-project `uv run ruff check .`,
full-project `uv run ruff format --check .`, and `uv run mypy headroom`
were not run locally for this targeted packaging change.

## Review Readiness

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

## Checklist

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have added tests that prove my fix is effective
- [x] New and existing targeted tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream
modules

## Screenshots (if applicable)

N/A

## Additional Notes

No new dependency is added; this only narrows when the existing `torch`
optional dependency is selected.
2026-07-11 10:20:33 -05:00