nbxtensor 0.0.3__tar.gz → 0.0.5__tar.gz

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.5] - 2026-11-07
+
+### Fixed
+- **The library runs on Windows**: weights are read at their offset without `os.preadv` (Windows' `ReadFile` with an
+  OVERLAPPED offset), the BLAS's thread control is found beside numpy (`numpy.libs`) instead of through /proc, and the
+  GPU libraries are opened by their Windows names (nvcuda.dll, cudart64_12.dll from the runtime wheel's `bin`, nvml.dll,
+  amdhip64_6.dll, ze_loader.dll, OpenCL.dll). Written and tested with Windows simulated: the project has no Windows
+  machine yet.
+- **`python -m nbxtensor doctor` on a Mac without Triton exits 1**: it named the fix and exited 0, so a script could
+  not tell that nothing could run yet.
+- **The library imports on Windows**: its page size came from `os.sysconf`, which Windows does not have; and the code
+  generator's identity now reads a backend's files as `/` paths with its `.pyd` and `.dll` binaries, so the same code
+  has the same identity on every system.
+- **A certified setting that is not served says why**: where the directory holds a key proven under another code
+  generator than the running one, the line named a memory class that matched ("certified for 18 GB, this card is
+  18 GB, not served"); it now names both generators and the re-proof command. A setting proven on another memory class
+  is still said as such.
+
+## [0.0.4] - 2026-11-07
+
+### Added
+- **Triton for the Apple GPU in one command**: `python -m nbxtensor install-metal` installs the Metal wheels of the
+  project's fork NeuroBrix/triton-ext (Triton built with triton-ext, and imperatormk's AppleGPU backend as
+  `nbx-triton-apple`, triton-lang/triton-ext#126), each by the release URL and sha256 written in the library,
+  through pip with `--no-deps --require-hashes --no-index` — never an extra index nor a package name resolved on PyPI. The
+  wheels are for Python 3.12 and macOS 15 or later (release apple-v0.1.0+triton3.8.0); it refuses by name off an
+  Apple-silicon Mac, on another Python, or below the macOS the wheels are built for. `python -m nbxtensor doctor` on a Mac
+  without it says so and names the command; the Metal backend's refusal names it too. On a Mac, nbxtensor depends on
+  `pyobjc-framework-Metal`, through which it opens the Metal device; without it the run fell to a CPU profile and was
+  refused for triton-cpu, it is now refused by name with its install line.
+
+### Fixed
+- **nbxtensor installs on a Mac**: it depended on `triton` on every platform, and PyPI publishes no Triton for macOS, so
+  `pip install nbxtensor` — and with it the NeuroBrix engine, even its PyTorch engine on MPS — could not resolve on a
+  clean macOS environment. Triton is now a dependency where PyPI has it; on a Mac it is built from source with its Metal
+  backend (the README's install), and the library says by name what to build when it is absent.
+
 ## [0.0.3] - 2026-11-06
 
 ### Fixed
@@ -143,7 +180,9 @@ memory; the fix is in test).
 - **`flash_decode_split_kernel` and its route**: armed only by an environment switch (`NBX_FLASH_DECODE`, with `NBX_FD_BLOCK_N` and `NBX_FD_SEG`) and measured slower than the vector decode kernels; `flash_decode.py` keeps the fixed-order reduce they share.
 - **`conv1d_forward_kernel`**: launched by no route (a 1-D convolution runs through `conv2d`).
 
-[Unreleased]: https://github.com/NeuroBrix/nbxtensor/compare/v0.0.3...HEAD
+[Unreleased]: https://github.com/NeuroBrix/nbxtensor/compare/v0.0.5...HEAD
+[0.0.5]: https://github.com/NeuroBrix/nbxtensor/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/NeuroBrix/nbxtensor/compare/v0.0.3...v0.0.4
 [0.0.3]: https://github.com/NeuroBrix/nbxtensor/compare/v0.0.2...v0.0.3
 [0.0.2]: https://github.com/NeuroBrix/nbxtensor/compare/v0.0.1...v0.0.2
 [0.0.1]: https://github.com/NeuroBrix/nbxtensor/releases/tag/v0.0.1

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nbxtensor
-Version: 0.0.3
+Version: 0.0.5
 Summary: Run AI models without PyTorch: tensors, Triton kernels, planned memory and certified tuning, wherever Triton runs — NVIDIA, AMD, Intel and Apple GPUs.
 Project-URL: Homepage, https://github.com/NeuroBrix/nbxtensor
 Project-URL: Source, https://github.com/NeuroBrix/nbxtensor
@@ -12,8 +12,9 @@ License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: numpy
 Requires-Dist: nvidia-cuda-runtime-cu12; platform_system == 'Linux'
+Requires-Dist: pyobjc-framework-metal; platform_system == 'Darwin'
 Requires-Dist: pyyaml
-Requires-Dist: triton
+Requires-Dist: triton; platform_system != 'Darwin'
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
@@ -24,7 +25,7 @@ Description-Content-Type: text/markdown
 
 Run AI models without PyTorch, on any GPU Triton supports: tensors, Triton kernels, planned memory and certified tuning.
 
-Runs wherever Triton runs — NVIDIA, AMD, Intel and Apple Silicon GPUs. Inference first; training is not in this
+Runs wherever Triton runs — NVIDIA, AMD, Intel and Apple Silicon GPUs, on Linux, Windows and macOS. Inference first; training is not in this
 release. Found a bug on your hardware? [Open an issue](https://github.com/NeuroBrix/nbxtensor/issues) — we fix fast.
 
 [![PyPI](https://img.shields.io/pypi/v/nbxtensor)](https://pypi.org/project/nbxtensor/)
@@ -137,7 +138,7 @@ What changed from one version to the next — added, changed, fixed, removed —
 nbxtensor never needs torch: it is not a dependency, not even an optional one, and the library and its kernels run in
 an environment where torch is not installed (proven on Metal, 2026-10-29: `tools/torch_free_proof.py` records every
 attempt to import torch, caught ones included, and recorded none). Python 3.10 or later; its dependencies are numpy,
-pyyaml and Triton.
+pyyaml and Triton (on a Mac, `pyobjc-framework-Metal` and the Triton `install-metal` brings).
 
 ```
 pip install nbxtensor
@@ -155,14 +156,21 @@ install commands when one is not.
 
 **From the NeuroBrix repository** (contributors): `pip install -e nbxtensor`.
 
-**macOS, Apple silicon (Metal).** PyPI publishes no Triton for macOS, so Triton and its Metal backend are built from
-source, then nbxtensor is installed into that environment:
+**macOS, Apple silicon (Metal).** PyPI publishes no Triton for macOS. `install-metal` installs NeuroBrix's Triton
+build for Apple GPUs, [NeuroBrix/triton-ext](https://github.com/NeuroBrix/triton-ext) (Triton built with
+`TRITON_EXT_ENABLED=1` and the `nbx-triton-apple` backend; upstream:
+[triton-lang/triton-ext#126](https://github.com/triton-lang/triton-ext/pull/126)); each wheel is checked against the
+sha256 written in the library (Python 3.12, macOS 15 or later):
 
-1. Triton (github.com/triton-lang/triton) built with `TRITON_EXT_ENABLED=1`, which lets out-of-tree backends plug in;
-2. the AppleGPU backend of triton-ext (github.com/triton-lang/triton-ext, `backend/AppleGPU`), installed into the same
-   environment;
-3. `pyobjc-framework-Metal` (the library opens the Metal device through it);
-4. Xcode's Metal toolchain (`xcrun metal` must find the real compiler, not Xcode's placeholder: `TOOLCHAINS=Metal`).
+```
+pip install nbxtensor
+python -m nbxtensor install-metal
+```
+
+Xcode's Metal toolchain is the other requirement (`xcrun metal` must find the real compiler, not Xcode's placeholder:
+`TOOLCHAINS=Metal`); `python -m nbxtensor doctor` says what is missing. To build Triton and its Metal backend yourself
+instead: Triton (github.com/triton-lang/triton) built with `TRITON_EXT_ENABLED=1`, then triton-ext's `backend/AppleGPU`
+installed into the same environment.
 
 `nbxtensor.dtype` and `nbxtensor.shape` need neither a device nor Triton.
 
@@ -492,7 +500,7 @@ with the tensor class (API.md §4).
 
 ## Versions
 
-The first publication was **0.0.1**; this is **0.0.3**. Each fix published after it increments the number (0.0.4,
+The first publication was **0.0.1**; this is **0.0.5**. Each fix published after it increments the number (0.0.6,
 …), with no alpha or beta label. The rewrite of the core in Rust will be **2.0.0**. `nbxtensor.__version__` is the
 installed version.
 

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/README.md

@@ -4,7 +4,7 @@
 
 Run AI models without PyTorch, on any GPU Triton supports: tensors, Triton kernels, planned memory and certified tuning.
 
-Runs wherever Triton runs — NVIDIA, AMD, Intel and Apple Silicon GPUs. Inference first; training is not in this
+Runs wherever Triton runs — NVIDIA, AMD, Intel and Apple Silicon GPUs, on Linux, Windows and macOS. Inference first; training is not in this
 release. Found a bug on your hardware? [Open an issue](https://github.com/NeuroBrix/nbxtensor/issues) — we fix fast.
 
 [![PyPI](https://img.shields.io/pypi/v/nbxtensor)](https://pypi.org/project/nbxtensor/)
@@ -117,7 +117,7 @@ What changed from one version to the next — added, changed, fixed, removed —
 nbxtensor never needs torch: it is not a dependency, not even an optional one, and the library and its kernels run in
 an environment where torch is not installed (proven on Metal, 2026-10-29: `tools/torch_free_proof.py` records every
 attempt to import torch, caught ones included, and recorded none). Python 3.10 or later; its dependencies are numpy,
-pyyaml and Triton.
+pyyaml and Triton (on a Mac, `pyobjc-framework-Metal` and the Triton `install-metal` brings).
 
 ```
 pip install nbxtensor
@@ -135,14 +135,21 @@ install commands when one is not.
 
 **From the NeuroBrix repository** (contributors): `pip install -e nbxtensor`.
 
-**macOS, Apple silicon (Metal).** PyPI publishes no Triton for macOS, so Triton and its Metal backend are built from
-source, then nbxtensor is installed into that environment:
+**macOS, Apple silicon (Metal).** PyPI publishes no Triton for macOS. `install-metal` installs NeuroBrix's Triton
+build for Apple GPUs, [NeuroBrix/triton-ext](https://github.com/NeuroBrix/triton-ext) (Triton built with
+`TRITON_EXT_ENABLED=1` and the `nbx-triton-apple` backend; upstream:
+[triton-lang/triton-ext#126](https://github.com/triton-lang/triton-ext/pull/126)); each wheel is checked against the
+sha256 written in the library (Python 3.12, macOS 15 or later):
 
-1. Triton (github.com/triton-lang/triton) built with `TRITON_EXT_ENABLED=1`, which lets out-of-tree backends plug in;
-2. the AppleGPU backend of triton-ext (github.com/triton-lang/triton-ext, `backend/AppleGPU`), installed into the same
-   environment;
-3. `pyobjc-framework-Metal` (the library opens the Metal device through it);
-4. Xcode's Metal toolchain (`xcrun metal` must find the real compiler, not Xcode's placeholder: `TOOLCHAINS=Metal`).
+```
+pip install nbxtensor
+python -m nbxtensor install-metal
+```
+
+Xcode's Metal toolchain is the other requirement (`xcrun metal` must find the real compiler, not Xcode's placeholder:
+`TOOLCHAINS=Metal`); `python -m nbxtensor doctor` says what is missing. To build Triton and its Metal backend yourself
+instead: Triton (github.com/triton-lang/triton) built with `TRITON_EXT_ENABLED=1`, then triton-ext's `backend/AppleGPU`
+installed into the same environment.
 
 `nbxtensor.dtype` and `nbxtensor.shape` need neither a device nor Triton.
 
@@ -472,7 +479,7 @@ with the tensor class (API.md §4).
 
 ## Versions
 
-The first publication was **0.0.1**; this is **0.0.3**. Each fix published after it increments the number (0.0.4,
+The first publication was **0.0.1**; this is **0.0.5**. Each fix published after it increments the number (0.0.6,
 …), with no alpha or beta label. The rewrite of the core in Rust will be **2.0.0**. `nbxtensor.__version__` is the
 installed version.
 

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nbxtensor"
-version = "0.0.3"
+version = "0.0.5"
 description = "Run AI models without PyTorch: tensors, Triton kernels, planned memory and certified tuning, wherever Triton runs — NVIDIA, AMD, Intel and Apple GPUs."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -16,7 +16,11 @@ authors = [{ name = "NeuroBrix" }]
 # On Linux the CUDA runtime library its CUDA backend opens (libcudart.so.12), which the NVIDIA driver does not ship: a clean
 # machine with only the driver found no GPU runtime and the engine read the card as CPU-only (the stable's install test,
 # 2026-11-05). On a machine without an NVIDIA card it is a library nothing opens.
-dependencies = ["numpy", "triton", "pyyaml", "nvidia-cuda-runtime-cu12; platform_system == 'Linux'"]
+# Triton on every platform PyPI publishes it for; macOS has none (the Metal Triton is built from source, with triton-ext's
+# AppleGPU backend — the README's install), so a plain "triton" made the library uninstallable on a Mac (2026-11-06).
+# On a Mac the Metal device is opened through pyobjc's Metal framework; Triton for Metal comes from `install-metal`.
+dependencies = ["numpy", "triton; platform_system != 'Darwin'", "pyyaml", "nvidia-cuda-runtime-cu12; platform_system == 'Linux'",
+                "pyobjc-framework-Metal; platform_system == 'Darwin'"]
 
 [project.urls]
 Homepage = "https://github.com/NeuroBrix/nbxtensor"

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/__init__.py

@@ -13,5 +13,5 @@ first publication is 0.0.1, each fix after it increments, the Rust rewrite is
 """
 
 #: the one version number; `pyproject.toml` states the same (tests/test_version.py)
-__version__ = "0.0.3"
+__version__ = "0.0.5"
 __all__: list = []

nbxtensor-0.0.5/src/nbxtensor/__main__.py

@@ -0,0 +1,39 @@
+"""`python -m nbxtensor doctor`: which GPU backend this machine runs, and for every NVIDIA, AMD or Intel GPU on its PCI
+bus whether the runtime library and the Triton backend it needs are installed — with the vendor's install steps when
+one is missing (`backend.install_help`); on an Apple-silicon Mac, whether Triton for Metal is installed.
+`python -m nbxtensor install-metal [--dry-run]`: install Triton for the Apple GPU from this version's release
+(`backend.install_metal`)."""
+import sys
+
+
+def doctor() -> int:
+    from nbxtensor.backend import install_help, runtime
+    from nbxtensor.backend.metal_backend import is_apple_silicon, triton_metal_available
+    if is_apple_silicon() and not triton_metal_available():
+        print("Apple GPU found; Triton for Metal not installed — run: python -m nbxtensor install-metal")
+        return 1                     # nothing can run yet: a script reads it from the exit status
+    try:
+        backend = runtime.gpu_backend()
+        print(f"backend in force: {backend}" + (" (the Apple GPU, through Metal)" if backend == "metal" else ""))
+    except RuntimeError as exc:
+        backend = None
+        print(f"backend in force: none — {str(exc).splitlines()[0]}")
+    if backend != "metal" or install_help.pci_gpus():     # a Mac has no PCI GPU to report: nothing to install there
+        print(install_help.report())
+    return 0
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["doctor"]:
+        return doctor()
+    if argv[:1] == ["install-metal"] and set(argv[1:]) <= {"--dry-run"}:
+        import nbxtensor
+        from nbxtensor.backend import install_metal
+        return install_metal.main(nbxtensor.__version__, dry_run="--dry-run" in argv[1:])
+    print("usage: python -m nbxtensor doctor | install-metal [--dry-run]", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/backend/cpu/blas.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import ctypes
 import functools
 import platform
+import sys
 from pathlib import Path
 from typing import Optional, Tuple
 
@@ -33,6 +34,16 @@ _OPENBLAS_GET = ("scipy_openblas_get_num_threads64_", "scipy_openblas_get_num_th
 
 
 def _loaded_openblas() -> Optional[str]:
+    if sys.platform == "win32":
+        # no /proc on Windows: numpy's wheel ships its OpenBLAS beside the package (`numpy.libs`, older wheels
+        # `numpy/.libs`), loaded with numpy; ctypes opening the same path returns the module already in the process
+        import numpy
+        root = Path(numpy.__file__).resolve().parent
+        for d in (root.parent / "numpy.libs", root / ".libs"):
+            hits = sorted(d.glob("*openblas*.dll")) if d.is_dir() else []
+            if hits:
+                return str(hits[0])
+        return None
     maps = Path("/proc/self/maps")
     if not maps.is_file():
         return None

nbxtensor-0.0.5/src/nbxtensor/backend/install_metal.py

@@ -0,0 +1,107 @@
+"""`python -m nbxtensor install-metal`: install Triton for the Apple GPU — the project's own wheels (Triton built with
+TRITON_EXT_ENABLED=1, and triton-ext's AppleGPU backend as `nbx-triton-apple`), downloaded from the release of the
+project's fork, github.com/NeuroBrix/triton-ext. The AppleGPU backend is imperatormk's (triton-lang/triton-ext#126).
+
+PyPI publishes no Triton for macOS, so a Mac has no Triton after `pip install nbxtensor`. The wheels are fetched from
+the URLs written below, each checked against the sha256 written beside it (`pip --require-hashes`), with `--no-deps`:
+never through an extra index and never by a package name pip would look up on PyPI — anyone can publish a package
+named "triton-apple-backend" there (dependency confusion). A machine other than an Apple-silicon Mac, or a Python the
+table does not cover, is refused by name.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import re
+import subprocess
+import sys
+import tempfile
+from typing import List, Tuple
+
+#: the only place the wheels are fetched from: the releases of the project's fork of triton-ext
+RELEASES = "https://github.com/NeuroBrix/triton-ext/releases/download/"
+
+#: the Metal wheels per CPython tag: (URL of the release asset, sha256 of the file), Triton first; a tag absent here is
+#: refused by name. The fork's release apple-v0.1.0+triton3.8.0 (2026-11-07): Triton 3.8.0 (git 4a15f415) built with
+#: TRITON_EXT_ENABLED=1 and nbx-triton-apple 0.1.0, both macOS 15.0 arm64 (the prebuilt LLVM Triton links is minos 15.0);
+#: sha256 read on the downloaded assets.
+METAL_WHEELS: dict = {
+    "cp312": (
+        (RELEASES + "apple-v0.1.0%2Btriton3.8.0/triton-3.8.0%2Bgit4a15f415.nbx1-cp312-cp312-macosx_15_0_arm64.whl",
+         "b9084dc93ae7f1468062a03e713d49c9add9a1c9a609fae753a7b32a13b7a223"),
+        (RELEASES + "apple-v0.1.0%2Btriton3.8.0/nbx_triton_apple-0.1.0-cp312-cp312-macosx_15_0_arm64.whl",
+         "b9ed95c983b220b1fbf1300481b1e2f52a0435c10ee618ef7ccf60a132fe263c"),
+    ),
+}
+
+
+class InstallMetalRefused(RuntimeError):
+    """This machine or this Python has no Metal wheels in this version's table."""
+
+
+def _python_tag() -> str:
+    return f"cp{sys.version_info.major}{sys.version_info.minor}"
+
+
+def wheels(version: str) -> List[Tuple[str, str]]:
+    """[(url, sha256)] of the wheels this machine installs, or a named refusal."""
+    if not (platform.system() == "Darwin" and platform.machine() == "arm64"):
+        raise InstallMetalRefused(
+            f"install-metal installs Triton for the Apple GPU and runs on an Apple-silicon Mac only (this machine: "
+            f"{platform.system()} {platform.machine()}). Elsewhere Triton comes from PyPI with nbxtensor.")
+    tag = _python_tag()
+    if tag not in METAL_WHEELS:
+        covered = ", ".join(sorted(METAL_WHEELS)) or "none yet"
+        raise InstallMetalRefused(
+            f"nbxtensor {version} carries no Metal wheels for Python {sys.version_info.major}.{sys.version_info.minor} "
+            f"({tag}); covered: {covered}.")
+    entries = list(METAL_WHEELS[tag])
+    need = max(_min_macos(url) for url, _sha in entries)
+    have = _macos_version()
+    if have < need:
+        raise InstallMetalRefused(
+            f"macOS {'.'.join(map(str, need))} required for now: the Metal wheels of nbxtensor {version} are built for "
+            f"macOS {'.'.join(map(str, need))} and later (this Mac: macOS {'.'.join(map(str, have))}).")
+    return entries
+
+
+def _min_macos(url: str) -> Tuple[int, int]:
+    """The lowest macOS a wheel installs on, read from its platform tag (`macosx_15_0_arm64` -> (15, 0))."""
+    m = re.search(r"-macosx_(\d+)_(\d+)_arm64\.whl$", url)
+    if m is None:
+        raise InstallMetalRefused(f"not a macOS arm64 wheel: {url}")
+    return int(m.group(1)), int(m.group(2))
+
+
+def _macos_version() -> Tuple[int, int]:
+    parts = [int(p) for p in (platform.mac_ver()[0] or "0").split(".")[:2]]
+    return (parts + [0])[0], (parts + [0])[1]
+
+
+def pip_command(requirements: str) -> List[str]:
+    """pip on this interpreter, from a requirements file of URLs and hashes only: no index is read, nothing else."""
+    return [sys.executable, "-m", "pip", "install", "--no-deps", "--require-hashes", "--no-index", "-r", requirements]
+
+
+def requirements_text(entries: List[Tuple[str, str]]) -> str:
+    return "".join(f"{url} --hash=sha256:{sha}\n" for url, sha in entries)
+
+
+def main(version: str, dry_run: bool = False) -> int:
+    try:
+        entries = wheels(version)
+    except InstallMetalRefused as exc:
+        print(f"install-metal: {exc}", file=sys.stderr)
+        return 1
+    text = requirements_text(entries)
+    if dry_run:
+        print(text, end="")
+        print(" ".join(pip_command("<these lines>")))
+        return 0
+    fd, path = tempfile.mkstemp(prefix="nbxtensor-metal-", suffix=".txt")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(text)
+        return subprocess.call(pip_command(path))
+    finally:
+        os.unlink(path)

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/backend/launcher.py

@@ -488,14 +488,15 @@ class CudaDriver(_ModuleDriver):
 
     def __init__(self) -> None:
         lib = None
-        for name in ("libcuda.so.1", "libcuda.so"):
+        from nbxtensor.backend.libnames import CUDA_DRIVER
+        for name in CUDA_DRIVER:
             try:
                 lib = ctypes.CDLL(name)
                 break
             except OSError:
                 continue
         if lib is None:
-            raise RuntimeError("NeuroBrix launcher: libcuda not found")
+            raise RuntimeError(f"NeuroBrix launcher: the CUDA driver library not found (tried {CUDA_DRIVER})")
         self.lib = lib
         self._check(lib.cuInit(0), "cuInit")
         # ctypes infers the type of every argument at every call unless the signature is

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/backend/level_zero.py

@@ -27,7 +27,7 @@ import threading
 from typing import Dict, Optional, Tuple
 
 #: the Level Zero loader (`libze1` on Ubuntu), tried in order
-LIBS = ["libze_loader.so.1", "libze_loader.so"]
+from nbxtensor.backend.libnames import LEVEL_ZERO as LIBS   # noqa: E402
 
 # ZE_STRUCTURE_TYPE_* (ze.py)
 _ST_DRIVER_PROPERTIES, _ST_DEVICE_COMPUTE, _ST_QUEUE_GROUP, _ST_DEVICE_MEMORY = 0x1, 0x4, 0x6, 0x7
@@ -558,7 +558,7 @@ def runtime() -> LevelZeroRuntime:
 
 
 #: the OpenCL ICD loader (`ocl-icd-libopencl1`; Intel's runtime registers itself in it with intel-opencl-icd)
-OPENCL_LIBS = ["libOpenCL.so.1", "libOpenCL.so"]
+from nbxtensor.backend.libnames import OPENCL as OPENCL_LIBS   # noqa: E402
 _CL_DEVICE_TYPE_GPU, _CL_DEVICE_VENDOR_ID, _CL_DEVICE_EXTENSIONS, _CL_DEVICE_ID_INTEL = 4, 0x1001, 0x1030, 0x4251
 
 #: target facts Intel's compiler reads (intel/backend/compiler.py `parse_target`) -> the OpenCL extension that states

nbxtensor-0.0.5/src/nbxtensor/backend/libnames.py

@@ -0,0 +1,26 @@
+"""The vendor libraries the backends open through ctypes, named as each system names them: a shared object on Linux
+(`libcuda.so.1`), a DLL on Windows (`nvcuda.dll`). Read by the backend tables (`backend.runtime`), the launch driver
+(`backend.launcher`), the graph replay (`backend.replay_graph`), the expandable pool (`memory.vmm`) and Level Zero
+(`backend.level_zero`). Windows' names are the vendors' (NVIDIA: nvcuda.dll in System32 with the driver, cudart64_12.dll
+in the CUDA runtime wheel's `bin`, nvml.dll; AMD HIP SDK: amdhip64_6.dll; Intel: ze_loader.dll, OpenCL.dll).
+"""
+from __future__ import annotations
+
+import sys
+
+WINDOWS = sys.platform == "win32"
+
+#: the CUDA runtime, after the one the environment's wheel carries (`runtime._environment_runtime_libs`)
+CUDA_RUNTIME = ["cudart64_12.dll", "cudart64_110.dll"] if WINDOWS else ["libcudart.so", "libcudart.so.12", "libcudart.so.11.0"]
+#: the CUDA runtime file inside the nvidia-cuda-runtime wheel, and the wheel's directory that holds it
+CUDA_RUNTIME_IN_WHEEL = ("bin", "cudart64_12.dll") if WINDOWS else ("lib", "libcudart.so.12")
+#: the CUDA driver API
+CUDA_DRIVER = ["nvcuda.dll"] if WINDOWS else ["libcuda.so.1", "libcuda.so"]
+#: NVIDIA's management library
+NVML = ["nvml.dll"] if WINDOWS else ["libnvidia-ml.so.1", "libnvidia-ml.so"]
+#: the HIP runtime
+HIP_RUNTIME = ["amdhip64_6.dll", "amdhip64.dll"] if WINDOWS else ["libamdhip64.so", "libamdhip64.so.5"]
+#: the Level Zero loader
+LEVEL_ZERO = ["ze_loader.dll"] if WINDOWS else ["libze_loader.so.1", "libze_loader.so"]
+#: the OpenCL ICD loader
+OPENCL = ["OpenCL.dll"] if WINDOWS else ["libOpenCL.so.1", "libOpenCL.so"]

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/backend/metal_backend.py

@@ -139,6 +139,16 @@ class TritonMetalShaderCompilerMissingError(TritonMetalNotInstalledError):
     """
 
 
+class TritonMetalBindingMissingError(TritonMetalNotInstalledError):
+    """Raised when Triton for Metal is installed but pyobjc's Metal binding, through which the device is opened, is
+    not: the device cannot be opened, and the run would otherwise fall to a CPU profile."""
+
+
+def metal_binding_available() -> bool:
+    """pyobjc's Metal binding, through which the device is opened, is installed (asked without importing it)."""
+    return importlib.util.find_spec("Metal") is not None
+
+
 def is_apple_silicon() -> bool:
     """True on an Apple-Silicon Mac."""
     return platform.system() == "Darwin" and platform.machine() == "arm64"
@@ -573,27 +583,25 @@ def ensure_triton_metal_or_raise() -> None:
 
     if not triton_metal_available():
         raise TritonMetalNotInstalledError(
-            "The --triton engine needs a Triton backend that targets Metal, and "
-            "none is installed.\n"
-            "\n"
-            "Upstream Triton has no Apple GPU target. An out-of-tree backend "
-            "exists:\n"
-            "    pip install triton-msl        (MIT; needs Triton 3.7+ built "
-            "with TRITON_EXT_ENABLED=1)\n"
+            "The --triton engine needs Triton for the Apple GPU (Triton with "
+            "triton-ext's AppleGPU backend), and none is installed. PyPI publishes "
+            "no Triton for macOS; nbxtensor's release carries it:\n"
+            "    python -m nbxtensor install-metal\n"
             "\n"
-            "NeuroBrix does not install it for you: fetching a wheel at runtime "
-            "is a\n"
-            "supply-chain surface you did not consent to, and it fails "
-            "confusingly on\n"
-            "air-gapped machines.\n"
+            "A run does not install it for you: a download at run time is a "
+            "supply-chain surface you did not consent to.\n"
             "\n"
-            "Working alternative today: drop --triton. The default compiled "
-            "engine runs\n"
-            "on Apple GPUs through PyTorch MPS with no extra install.\n"
-            "\n"
-            "Status and known gaps: docs/internal/metal_adoption_plan_2026_09_03.md"
+            "Alternative: the PyTorch engine (--compiled) runs on the Apple GPU "
+            "through MPS (pip install torch \"neurobrix[pytorch]\")."
         )
 
+    if not metal_binding_available():
+        # the device is opened through pyobjc's Metal binding: without it the run found no device and fell to a CPU
+        # profile, refused there for triton-cpu with not a word about Metal (the Mac's clean venv, 2026-11-07 00:51)
+        raise TritonMetalBindingMissingError(
+            "The --triton engine opens the Apple GPU through pyobjc's Metal binding, and it is not installed:\n"
+            "    pip install pyobjc-framework-Metal")
+
     if not metal_shader_compiler_available():
         raise TritonMetalShaderCompilerMissingError(
             "A Triton Metal backend is installed, but Apple's offline shader "

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/backend/replay_graph.py

@@ -70,7 +70,8 @@ class _CudaGraphAPI:
     _inst = None
 
     def __init__(self) -> None:
-        lib = ctypes.CDLL("libcuda.so.1")
+        from nbxtensor.backend.libnames import CUDA_DRIVER
+        lib = ctypes.CDLL(CUDA_DRIVER[0])
 
         def bind(name, argtypes):
             fn = getattr(lib, name)

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/backend/runtime.py

@@ -39,23 +39,26 @@ def _environment_runtime_libs(package: str, names) -> list:
         return []
     import os
     root = list(spec.submodule_search_locations)[0]
+    from nbxtensor.backend.libnames import CUDA_RUNTIME_IN_WHEEL, WINDOWS
     out = []
     for n in names:
-        cand = os.path.join(root, "lib", n)
+        cand = os.path.join(root, CUDA_RUNTIME_IN_WHEEL[0], n)
         if os.path.exists(cand):
             out.append(cand)
+            if WINDOWS:                   # the DLL's own directory searched for what it loads
+                os.add_dll_directory(os.path.dirname(cand))
     return out
 
 
 # Runtime API mapping per backend
+from nbxtensor.backend import libnames as _LIB    # noqa: E402  the libraries as this system names them
 _GPU_BACKENDS = {
     "cuda": {
-        "rt_libs": _environment_runtime_libs("nvidia.cuda_runtime", ["libcudart.so.12"])
-                   + ["libcudart.so", "libcudart.so.12", "libcudart.so.11.0"],
+        "rt_libs": _environment_runtime_libs("nvidia.cuda_runtime", [_LIB.CUDA_RUNTIME_IN_WHEEL[1]]) + _LIB.CUDA_RUNTIME,
         # the driver API's library: the virtual memory primitives of the expandable pool (`memory.vmm`, R16)
-        "driver_libs": ["libcuda.so.1", "libcuda.so"],
+        "driver_libs": _LIB.CUDA_DRIVER,
         # the management library: what the driver attributes to THIS process on a device (`backend.process_memory`)
-        "management_libs": ["libnvidia-ml.so.1", "libnvidia-ml.so"],
+        "management_libs": _LIB.NVML,
         "pci_bus_id": "cudaDeviceGetPCIBusId",
         "malloc": "cudaMalloc", "free": "cudaFree",
         "memcpy": "cudaMemcpy", "memset": "cudaMemset",
@@ -100,7 +103,7 @@ _GPU_BACKENDS = {
         "device_enable_peer_access": "cudaDeviceEnablePeerAccess",
     },
     "hip": {
-        "rt_libs": ["libamdhip64.so", "libamdhip64.so.5"],
+        "rt_libs": _LIB.HIP_RUNTIME,
         # the same three facts as cuda's, declared ABSENT: the expandable pool speaks the CUDA driver's VMM calls only
         # (`memory.vmm`; HIP's hipMemCreate family is not wired), so a HIP device keeps its driver segments; and no
         # per-process accounting is read on ROCm (`backend.process_memory` answers None, the runtime's growth is not

{nbxtensor-0.0.3 → nbxtensor-0.0.5}/src/nbxtensor/io/read_rate.py

@@ -11,7 +11,8 @@ import time
 from concurrent.futures import ThreadPoolExecutor
 from typing import Dict, List, Optional, Sequence
 
-__all__ = ["PIECE", "WITNESS_BYTES", "START_BYTES", "mount_of", "pieces", "trial", "choose", "measure", "workers_for"]
+__all__ = ["PIECE", "WITNESS_BYTES", "START_BYTES", "mount_of", "pieces", "trial", "choose", "measure", "workers_for",
+           "can_bypass_the_cache"]
 
 PIECE = 16 << 20                       # the loaders' read piece
 
@@ -63,14 +64,21 @@ def pieces(files, max_bytes: int):
     return out, total
 
 
+def can_bypass_the_cache() -> bool:
+    """Whether this system lets a measure read past its page cache (macOS F_NOCACHE + msync, Linux posix_fadvise);
+    Windows offers neither through Python, and a rate read from the cache is not the storage's."""
+    return sys.platform == "darwin" or hasattr(os, "posix_fadvise")
+
+
 def trial(pieces, workers: int) -> float:
     """Bytes per second reading `pieces` with `workers` threads, the cache bypassed."""
+    from nbxtensor.io.safetensors import _read_at
     for path in {p for p, _, _ in pieces}:
         _evict(path, os.path.getsize(path))
     fds = {}
     for path, _, _ in pieces:
         if path not in fds:
-            fd = os.open(path, os.O_RDONLY)
+            fd = os.open(path, os.O_RDONLY | getattr(os, "O_BINARY", 0))
             _no_cache(fd)
             fds[path] = fd
     bufs = [bytearray(PIECE) for _ in range(workers)]
@@ -80,7 +88,7 @@ def trial(pieces, workers: int) -> float:
         buf = memoryview(bufs[i % workers])[:n]
         got = 0
         while got < n:
-            got += os.preadv(fds[path], [buf[got:]], off + got)
+            got += _read_at(fds[path], buf[got:], off + got)
         return n
 
     t = time.perf_counter()
@@ -146,6 +154,9 @@ def workers_for(directory, witness_dir=None, max_workers: Optional[int] = None,
     up to everything the files hold. When no size gives a stable measure, refused by name: never a silent None, never
     a default."""
     from pathlib import Path
+    if not can_bypass_the_cache():
+        raise RuntimeError(f"ZERO FALLBACK: no uncached read-rate measure on this system ({sys.platform}: no way to "
+                           f"read past the page cache) — no worker count is assumed")
     root = Path(directory)
     max_workers = max_workers or os.cpu_count() or 1
     files = [str(p) for p in sorted(root.glob(pattern), key=lambda p: -p.stat().st_size)[:4]]