Make torch and the sklearn stack optional extras

[cboulay]

Closes #22.

The pure-numpy processors need none of torch, scikit-learn, river or pandas, but installing ezmsg-learn to use e.g. the LRR re-referencer paid for a full PyTorch install. The backends now live behind extras:

pip install ezmsg-learn              # numpy-only processors
pip install "ezmsg-learn[sklearn]"   # + pandas, river, scikit-learn
pip install "ezmsg-learn[torch]"     # + torch
pip install "ezmsg-learn[all]"       # everything

This is a breaking change for anyone relying on pip install ezmsg-learn to supply a backend, with no deprecation cycle — as agreed on the issue, since the main downstream consumer is updated in lockstep.

Two adjustments to the shape proposed in the issue

• scipy had to join the base dependencies, not an extra. model/refit_kalman.py imports scipy.linalg.solve_discrete_are at module level and reaches it transitively via scikit-learn today; it would have broken on a base install. numpy and array-api-compat are declared as the issue suggested.
• dim_reduce belongs to the sklearn group. dim_reduce/adaptive_decomp.py imports sklearn.decomposition at module level, and incremental_decomp.py imports from it. The issue's module table doesn't list either.

Error messages

New src/ezmsg/learn/_optional.py builds the message; each module behind an extra wraps its backend import:

ezmsg.learn.process.base requires the optional 'torch' dependencies of ezmsg-learn,
which are not installed. Install them with: pip install "ezmsg-learn[torch]"

Two modules do better than a straight guard

• util.py needs no extra at all now. Only the ADAPTIVE_REGRESSORS/STATIC_REGRESSORS registries touch river/sklearn, so they're built on demand; the enums and ClassifierMessage are pure ezmsg. The public registry names are preserved lazily via PEP 562 __getattr__.
• collection/sample_adapt_regressor.py imports its backend lazily, so it needs only the extra for the model_type in use — and none at all for model_type="kalman". It would otherwise have been the one module requiring [all].

Tests and CI

tests/unit/test_optional_deps.py asserts two properties:

1. In a subprocess, that no base-install module transitively loads a backend — this is what catches someone later adding a top-level import torch to ssr.py.
2. That each guarded module names its extra. Only observable without the extra installed, so these skip in the dev environment and run for real in a new minimal-install CI job that installs with no extras.

The test and docs dependency-groups pull ezmsg-learn[all], so uv sync and the docs build still get every backend. (tool.uv.default-extras isn't supported by the current uv, so the self-referential extra is the working route.)

The docs workflow also gains --no-sync: uv run was re-syncing to the default groups and silently undoing the preceding uv sync --only-group docs, so the declared docs environment and the built one were different. The docs group now declares ezmsg-learn[all] outright instead of inheriting backends from the test group.

Verification

• Full suite: 356 passed, 24 skipped (unit + dim_reduce + integration); ruff check and ruff format clean.
• Fresh venv with pip install . installs no torch/sklearn/river/pandas. All 33 optional-dep tests pass there; from ezmsg.learn.process.ssr import LRRSettings, LRRUnit works with torch absent from sys.modules; the kalman collection builds with zero backends loaded.
• Docs, running the new CI sequence from a deleted .venv: build succeeds with the same 4 pre-existing warnings, all 20 module source pages generated, and API pages carry real content across both extras (process.torch 9 classes, process.rnn 4, dim_reduce.adaptive_decomp 10, process.ssr 7).

🤖 Generated with Claude Code