Confine the legacy Kwik constraints to the phy[kwik] extra

phy's own code uses no numpy API removed in 2.0, so the main dependency set
moves to numpy>=1.23 with no upper bound and requires-python stays >=3.10.
Regular users get numpy 2.x and Python 3.13.

Everything the legacy Kwik GUI needs is confined to the kwik extra, which
provides one self-contained, fully working setup -- opening .kwik files,
curating them, and the recluster action (shift+ctrl+K, re-running KlustaKwik2):

  numpy>=1.23,<1.24  the last numpy the legacy klusta/klustakwik2 stack was
                     written against; keeps the whole Kwik surface on tested
                     ground. Caps the Kwik GUI at Python 3.10-3.11 (numpy 1.23
                     ships no cp312 wheels).
  setuptools<81      klusta/__init__.py imports pkg_resources, dropped in 81
  six                klusta declares no dependencies of its own

The numpy pin is deliberately conservative rather than strictly required:
reclustering runs on newer numpy (verified via klusta.launch.cluster(), the
function the GUI action calls, on numpy 1.26.4), and even numpy 2 works once
ndarray.tostring() -> .tobytes() in klusta/kwik/h5.py and
klustakwik2/precomputations.py is fixed upstream. Pinning to <1.24 trades those
newer versions for a single tested baseline; the cap can be relaxed later.

Verified: phy[kwik] resolves on Python 3.11 (numpy 1.23.5, scipy 1.15.3) and the
full KwikCreator -> KwikModel -> launch.cluster() round-trip passes.

Author: Sachuriga

README.md

@@ -46,14 +46,74 @@ python -m pip install --upgrade pip
 pip install phy
 ```
 
-This installs the GUI runtime dependencies as part of the main package.
+This installs the GUI runtime dependencies as part of the main package. phy
+itself works with numpy 1.x and numpy 2.x; only the legacy Kwik GUI is
+constrained, and those constraints live in the `kwik` extra so that they apply
+to nobody else.
 
-If you plan to use the legacy Kwik GUI, also install:
+### Installing from a git checkout
+
+To run phy from this repository rather than from PyPI:
 
 ```bash
-pip install klusta klustakwik2
+conda create -n phy python=3.13 -y
+conda activate phy
+
+git clone https://github.com/cortex-lab/phy.git
+cd phy
+pip install -e .
 ```
 
+`-e` (editable) means `git pull` updates your install with no reinstall step.
+Drop the `-e` for a plain copy. To install straight from GitHub without a local
+clone:
+
+```bash
+pip install "phy @ git+https://github.com/cortex-lab/phy.git"
+```
+
+### Kwik GUI dependencies
+
+**The legacy Kwik GUI requires Python 3.10 or 3.11.** It depends on `klusta` and
+`klustakwik2`, both unmaintained since 2018, and the `kwik` extra pins
+`numpy>=1.23,<1.24` to keep the whole legacy stack on the numpy it was written
+against (see below). numpy 1.23 publishes no cp312 wheels, so Python 3.12 and
+3.13 are out for the Kwik GUI. Nothing here affects a plain `pip install phy`.
+
+```bash
+pip install "phy[kwik]"
+```
+
+On macOS and on Apple Silicon there are no `klustakwik2` wheels, and its
+`setup.py` imports numpy at build time, so build isolation has to be disabled:
+
+```bash
+pip install "cython>=3.0"
+pip install --no-build-isolation klustakwik2
+pip install "phy[kwik]"
+```
+
+The `kwik` extra enforces three constraints, all of them caused by the two legacy
+packages rather than by phy:
+
+* `numpy>=1.23,<1.24` — the last numpy the legacy stack was written against. This
+  keeps the entire Kwik surface on tested ground and gives one self-contained
+  setup, at the cost of Python 3.12+ support. It is deliberately conservative:
+  reclustering itself runs on newer numpy, and even numpy 2 works once two
+  upstream call sites (`ndarray.tostring()` in `klusta/kwik/h5.py` and
+  `klustakwik2/precomputations.py`, removed in numpy 2.0) are updated to
+  `.tobytes()`. When those fixes are released upstream the cap can be relaxed.
+* `setuptools<81` — `klusta/__init__.py` imports `pkg_resources`, removed in 81.
+* `six` — `klusta` declares no dependencies of its own at all.
+
+Under this extra, opening `.kwik` files, curating them, and the GUI's `recluster`
+action (`shift+ctrl+K`, which re-runs KlustaKwik2) all work.
+
+Note that `klustakwik2` must also be *compiled* against the numpy major version
+it will run under: a later `pip install` that pulls a different numpy into the
+environment can break it with
+`ImportError: numpy.core.multiarray failed to import`.
+
 ## Quick start
 
 Open the Template GUI on a spike sorting output directory containing `params.py`:

pyproject.toml

@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
 requires-python = ">=3.10"
 
@@ -34,7 +35,7 @@ dependencies = [
     "joblib",
     "matplotlib",
     "mtscomp",
-    "numpy",
+    "numpy>=1.23",
     "pillow",
     "pip",
     "PyQt5>=5.15.11,<5.16",
@@ -55,6 +56,30 @@ Repository = "https://github.com/cortex-lab/phy"
 Documentation = "https://phy.readthedocs.io/en/latest/"
 
 [project.optional-dependencies]
+# Legacy Kwik GUI. Both klusta and klustakwik2 are unmaintained (last releases
+# 2018) and constrain the environment in ways phy itself does not, so everything
+# legacy is confined to this extra to give one self-contained, fully working Kwik
+# setup (open, curate, and recluster) without holding back the main package:
+#
+#   numpy>=1.23,<1.24  Pinned conservatively to the last numpy the legacy stack
+#                 was written against, so the whole Kwik surface -- not just the
+#                 parts phy exercises in CI -- stays on tested ground. This is
+#                 deliberately tighter than strictly required (reclustering itself
+#                 runs on newer numpy), and it is what caps the Kwik GUI at Python
+#                 3.10-3.11: numpy 1.23 ships no cp312 wheels.
+#   setuptools<81 klusta/__init__.py imports pkg_resources, dropped in 81.
+#   six           klusta declares no dependencies at all, and imports six.
+#
+# klustakwik2 has no wheels outside manylinux/win, and its setup.py imports numpy
+# at build time, so elsewhere it needs:
+#   pip install --no-build-isolation klustakwik2
+kwik = [
+    "klusta",
+    "klustakwik2",
+    "six",
+    "numpy>=1.23,<1.24",
+    "setuptools<81",
+]
 dev = [
     "Cython>=3.0",
     "pytest",