feat: autofit[nss] install extra (Phase 4 of nss_first_class_sampler)

[Jammy2211]

Summary

Phase 4 of the nss_first_class_sampler roadmap — pip install autofit[nss] is now the single command that installs af.NSS and all its dependencies. Replaces the multi-step install saga documented in z_projects/profiling/FINDINGS_v3.md. Closes #1276.

pip install autofit[nss]
python -c "import autofit as af; af.NSS()"  # works

Approach (Option C from the prompt's matrix)

The original Phase 4 prompt recommended Option A — full vendoring of ~1300 LOC of nss + blackjax/ns into PyAutoFit. Investigation revealed modern pip 23+ handles URL-direct deps cleanly, so the lighter Option C path (pip extra with pinned git+ URLs) works without ongoing re-vendor maintenance burden. Verified empirically on a fresh venv.

The pin choice matters

Initial try with HEAD of handley-lab/blackjax (5dbf89a9) failed: HEAD adds numpy>=1.25 which conflicts with PyAutoFit's anesthetic==2.8.14 (numpy<2.0). Pinned to ef45acd2f instead — the May 2026 "Merge PR #60 — double_compile" commit, which is what was installed locally and validated through the entire Phase 1-3 work. The same anesthetic cap will release when Python 3.13 anesthetic>=2.9 takes over; revisit the blackjax pin in that bump.

What's in the extra

nss = [
    "fastprogress<1.1",
    "blackjax @ git+https://github.com/handley-lab/blackjax.git@ef45acd2f2fa0cca15adbdcd3ff7cb3a98987cb5",
    "nss @ git+https://github.com/yallup/nss.git@69159b0f4a3a53123b9eec7df91e4ed3885e4dc4",
]

The fastprogress<1.1 pin avoids fastprogress 1.1.5's transitive pull of python-fasthtml + starlette + uvicorn etc. The two URL deps win the resolver fight against mainline blackjax via pip's direct-URL precedence.

CI

New workflow at .github/workflows/nss_install_smoke.yml:

• Triggers on pull_request (catches local pyproject.toml regressions before merge).
• Runs on 0 3 * * 0 cron (Sundays 03:00 UTC — catches upstream drift past the pinned SHAs).
• Fresh Ubuntu venv, pip install -e PyAutoFit[nss], then a Python smoke that imports autofit, nss.ns, blackjax.ns.adaptive (asserting the fork's init attribute exists), and instantiates af.NSS().

Test plan

• pytest test_autofit — 1258 passed, 1 skipped (1252 baseline + 6 NSS unit tests from Phase 2-3; no regression).
• Fresh python -m venv /tmp/nss_install_smoke && pip install -e PyAutoFit[nss] on Python 3.12 — completes in ~3 minutes, installs blackjax 0.1.0b1.dev85+gef45acd2f, nss 0.1.0, jax 0.7.1, numpy 1.26.4, and the rest of the transitive tree without dependency conflicts.
• Fresh-venv import autofit as af; af.NSS(n_live=10, ...) succeeds end-to-end. blackjax.ns.adaptive.init exists (canonical check for the handley-lab fork).
• NSS unit tests (15/15) still pass — the updated ImportError text still matches the existing pytest.raises(ImportError, match=...) regex.

API Changes

Pure additive at the install layer (autofit[nss] extra). The af.NSS ImportError message changes to reference the new install command. No code-API changes.
See full details below.

Full API Changes (for automation & release notes)

Added

• autofit[nss] install extra in PyAutoFit/pyproject.toml. Pulls fastprogress<1.1 + handley-lab/blackjax fork at SHA ef45acd2f + yallup/nss at SHA 69159b0f.

Changed Behaviour

• autofit.NSS.__init__ ImportError message now references pip install autofit[nss] instead of the manual pip install git+https://... recipe. Pre-feat: autofit[nss] install extra (Phase 4 of nss_first_class_sampler) #1276 message regex (af.NSS requires the optional \nss` package`) still matches.

Migration

Users who previously followed the manual install recipe from FINDINGS_v3.md can switch to pip install autofit[nss]. No action required for existing installs — both paths produce a working af.NSS.

🤖 Generated with Claude Code