nbxtensor 0.0.1__py3-none-any.whl

nbxtensor/backend/cpu/pool.py

@@ -0,0 +1,204 @@
+"""The CPU uses every core it is given (host work left on one core idled the rest of the machine): one thread pool, and a loop that cuts a large array
+into contiguous pieces run in parallel, on the model of ggml.
+
+numpy's element-wise ops, reductions and conversions run on one core; their inner loops release the GIL. So an op over
+a large array is cut into contiguous pieces, each piece run by a pool thread with the same numpy call on its slice:
+the pieces run on as many cores as the pool holds. Under a size threshold the threads cost more than they save, and
+the op runs inline; the threshold is MEASURED (inline against split, on this machine, per kind of work), never written
+by hand.
+
+- `threads()`: the pool's size. Default: what this library measures of the machine — on Apple silicon its performance
+  cores (`hw.perflevel0.physicalcpu`: an efficiency core in a parallel region holds every other thread at its barrier),
+  else the physical cores the process may run on (Linux: its CPU affinity and `/sys` topology; macOS:
+  `hw.physicalcpu`). An application sets its own (`set_threads`; NeuroBrix: its hardware profile's compute threads).
+- `parallel_for(n, run, kind)`: `run(start, stop)` over contiguous pieces of `[0, n)`, inline under the measured
+  threshold of `kind`; returns the pieces' results in order.
+- the BLAS numpy calls: as many threads as the pool outside it, one per piece inside `parallel_for` — no
+  oversubscription (`backend.cpu.blas`).
+- `numa_nodes()`: the NUMA nodes and their CPUs (Linux `/sys/devices/system/node`), `{}` where the machine has none to
+  report.
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import os
+import platform
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Sequence, Tuple
+
+__all__ = ["threads", "set_threads", "measured_threads", "numa_nodes", "pieces", "parallel_for",
+           "split_threshold", "set_split_threshold"]
+
+_LOCK = threading.Lock()
+_STATE: Dict[str, object] = {}          # "threads": int set by an application; "pool": the executor; "pool_size"
+_THRESHOLDS: Dict[str, int] = {}        # kind -> elements under which the work runs inline
+
+
+def _sysctl_int(name: str) -> Optional[int]:
+    r = subprocess.run(["sysctl", "-n", name], capture_output=True, text=True)
+    out = r.stdout.strip()
+    return int(out) if r.returncode == 0 and out.isdigit() else None
+
+
+def _linux_physical_cores() -> Optional[int]:
+    allowed = os.sched_getaffinity(0)
+    cores = set()
+    for cpu in allowed:
+        topo = Path(f"/sys/devices/system/cpu/cpu{cpu}/topology")
+        try:
+            cores.add((int((topo / "physical_package_id").read_text()), int((topo / "core_id").read_text())))
+        except (OSError, ValueError):
+            return None
+    return len(cores) or None
+
+
+def measured_threads() -> int:
+    """The compute cores this machine gives this process, as the library reads them (see the module's docstring).
+    Refused by name where no reading exists: the count is never guessed."""
+    system = platform.system()
+    if system == "Darwin":
+        n = _sysctl_int("hw.perflevel0.physicalcpu") or _sysctl_int("hw.physicalcpu")
+    elif system == "Linux":
+        n = _linux_physical_cores()
+    else:
+        n = None
+    if not n:
+        raise RuntimeError(f"ZERO FALLBACK: nbxtensor reads no physical core count on {system!r}; set the pool's size "
+                           f"(nbxtensor.backend.cpu.pool.set_threads)")
+    return int(n)
+
+
+def numa_nodes() -> Dict[int, Tuple[int, ...]]:
+    """{node: CPUs} from Linux's `/sys/devices/system/node`; `{}` where the machine reports none."""
+    root = Path("/sys/devices/system/node")
+    nodes: Dict[int, Tuple[int, ...]] = {}
+    for d in sorted(root.glob("node[0-9]*")) if root.is_dir() else ():
+        cpus: List[int] = []
+        for part in (d / "cpulist").read_text().strip().split(","):
+            if part:
+                lo, _, hi = part.partition("-")
+                cpus.extend(range(int(lo), int(hi or lo) + 1))
+        nodes[int(d.name[4:])] = tuple(cpus)
+    return nodes
+
+
+def threads() -> int:
+    """The pool's size: the application's (`set_threads`), else the library's measurement of the machine."""
+    n = _STATE.get("threads")
+    return int(n) if n is not None else measured_threads()
+
+
+def set_threads(n: Optional[int]) -> None:
+    """Set the pool's size (an int >= 1); `None` restores the library's measurement. The running pool is replaced."""
+    if n is not None and (not isinstance(n, int) or n < 1):
+        raise ValueError(f"set_threads: {n!r} — a pool holds one thread or more")
+    with _LOCK:
+        if n is None:
+            _STATE.pop("threads", None)
+        else:
+            _STATE["threads"] = n
+        pool = _STATE.pop("pool", None)
+        _STATE.pop("pool_size", None)
+    if pool is not None:
+        pool.shutdown(wait=True)
+    from nbxtensor.backend.cpu.blas import blas, set_blas_threads
+    if blas()[0] == "openblas":                       # the process's BLAS count follows the pool's size
+        set_blas_threads(threads())
+
+
+def _pool(size: int) -> concurrent.futures.ThreadPoolExecutor:
+    with _LOCK:
+        if _STATE.get("pool_size") != size:
+            old = _STATE.pop("pool", None)
+            if old is not None:
+                old.shutdown(wait=False)
+            _STATE["pool"] = concurrent.futures.ThreadPoolExecutor(max_workers=size, thread_name_prefix="nbx-cpu",
+                                                                   initializer=_one_blas_thread_here)
+            _STATE["pool_size"] = size
+        return _STATE["pool"]
+
+
+def _one_blas_thread_here() -> None:
+    """A pool thread runs its BLAS single-threaded (Accelerate's setting is per thread; OpenBLAS's count is the
+    process's and is lowered by `parallel_for` itself)."""
+    from nbxtensor.backend.cpu.blas import blas, set_blas_threads
+    if blas()[0] == "accelerate":
+        set_blas_threads(1)
+
+
+def pieces(n: int, parts: int) -> List[Tuple[int, int]]:
+    """`[0, n)` cut into at most `parts` contiguous, non-empty pieces of sizes differing by one at most, in order."""
+    if n < 0 or parts < 1:
+        raise ValueError(f"pieces: n={n}, parts={parts}")
+    parts = min(parts, n) or 1
+    base, extra = divmod(n, parts)
+    out, start = [], 0
+    for i in range(parts):
+        stop = start + base + (1 if i < extra else 0)
+        if stop > start:
+            out.append((start, stop))
+        start = stop
+    return out
+
+
+def split_threshold(kind: str, probe: Optional[Callable[[int], Callable[[int, int], object]]] = None) -> int:
+    """Elements of work of `kind` under which a split costs more than it saves — set (`set_split_threshold`) or
+    MEASURED once per process with `probe(n)` (which builds the work on `n` elements: a callable of (start, stop)),
+    by timing inline against split at growing sizes. A kind never set nor probed is refused by name."""
+    if kind in _THRESHOLDS:
+        return _THRESHOLDS[kind]
+    if probe is None:
+        raise KeyError(f"split_threshold: kind {kind!r} has no threshold set and no probe to measure it")
+    size = threads()
+    n = 1 << 12
+    while n <= 1 << 26:
+        run = probe(n)
+        inline = _best_of(lambda: run(0, n))
+        split = _best_of(lambda: [f.result() for f in [_pool(size).submit(run, a, b) for a, b in pieces(n, size)]])
+        if split < inline:
+            _THRESHOLDS[kind] = n
+            return n
+        n <<= 1
+    _THRESHOLDS[kind] = n          # no size measured faster split: work this large or smaller runs inline
+    return n
+
+
+def _best_of(fn, repeat: int = 5) -> float:
+    best = float("inf")
+    for _ in range(repeat):
+        t = time.perf_counter()
+        fn()
+        best = min(best, time.perf_counter() - t)
+    return best
+
+
+def set_split_threshold(kind: str, n: Optional[int]) -> None:
+    """Set (or with `None` forget, to measure again) the threshold of `kind`."""
+    if n is None:
+        _THRESHOLDS.pop(kind, None)
+    elif not isinstance(n, int) or n < 1:
+        raise ValueError(f"set_split_threshold: {n!r}")
+    else:
+        _THRESHOLDS[kind] = n
+
+
+def parallel_for(n: int, run: Callable[[int, int], object], kind: str,
+                 probe: Optional[Callable[[int], Callable[[int, int], object]]] = None) -> Sequence[object]:
+    """`run(start, stop)` over contiguous pieces of `[0, n)`: inline (one piece) under `kind`'s threshold or on a pool
+    of one thread, else one piece per pool thread. The pieces' results, in order."""
+    size = threads()
+    if size == 1 or n < split_threshold(kind, probe):
+        return [run(0, n)]
+    from nbxtensor.backend.cpu.blas import blas, set_blas_threads
+    process_wide = blas()[0] == "openblas"           # a count for the whole process: 1 while the pieces run
+    if process_wide:
+        set_blas_threads(1)
+    try:
+        futures = [_pool(size).submit(run, a, b) for a, b in pieces(n, size)]
+        return [f.result() for f in futures]
+    finally:
+        if process_wide:
+            set_blas_threads(size)

nbxtensor/backend/cpu_backend.py

@@ -0,0 +1,162 @@
+"""
+Triton-CPU backend detection and gate.
+
+NeuroBrix triton modes (`--triton`, `--triton-sequential`) on a CPU-only
+profile (no visible GPU) require the upstream `triton-cpu` package from
+``triton-lang/triton-cpu``. We do NOT bundle, auto-fetch, or vendor it.
+When it is missing we raise a clean error naming the install command and
+a viable alternative (`--compiled` runs on CPU without any extra
+install).
+
+Rationale (per project doctrine, P-PRISM-NEVER-REFUSE v2 / S3
+2026-05-12):
+- Security: auto-fetching a wheel at runtime is a supply-chain surface
+  the user did not consent to.
+- Trust: the user controls their environment; surprising side-effects
+  on `neurobrix run` damage that trust.
+- Air-gapped deployments: enterprise ML datacenters run on isolated
+  networks where auto-fetch fails with a confusing network error.
+- Alignment: llama.cpp, vLLM, transformers, torch itself do not
+  auto-install optional backends.
+
+Numerical coverage gaps that remain blocked by upstream issues are
+tracked in `triton/triton_cpu_coverage_gaps.md`. The
+``TRITON_CPU_FP16_UPSTREAM_BLOCKED`` marker below is read by the
+dispatcher to decide whether to refuse a fp16 launch with a clear
+message or fall through to a documented escalation path.
+
+R34 (model-agnostic) preserved — nothing in this module is keyed on
+model name. R33 (zero-torch in triton) preserved — this module does
+not import torch, even at boundary.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+# Marker constants — read by the triton-CPU dispatcher path to gate
+# launches that are known to fail or drift on the current upstream.
+# These exist so a future P-TRITON-CPU-FP16-UPSTREAM-FOLLOWUP can flip
+# them in one place when the upstream issues close.
+TRITON_CPU_FP16_UPSTREAM_BLOCKED: bool = True  # triton-cpu #147 (Dot3D), #144
+TRITON_CPU_MASKED_BLOCKPTR_GEMM_BLOCKED: bool = True  # triton-cpu #222
+
+
+class TritonCPUNotInstalledError(ImportError):
+    """Raised when `--triton` is invoked on a CPU-only profile and the
+    upstream `triton-cpu` package is missing.
+
+    The message is intentionally actionable: install command, docs
+    pointer, and a viable already-working alternative.
+    """
+
+
+def _is_cpu_only_profile() -> bool:
+    """True when the ENGINE resolves no GPU backend on this run.
+
+    `CUDA_VISIBLE_DEVICES=""` still forces CPU: it is the standard way to
+    hide GPUs and it is a deliberate instruction, not a probe.
+
+    Everything else is asked of the engine's own detection, which knows
+    CUDA, ROCm and Metal, rather than of `libcuda.so.1`. Loading that
+    library was the whole test until 2026-09-06, and on an Apple machine it
+    fails for the ordinary reason that there is no NVIDIA driver — so
+    `--triton` refused a real GPU as "CPU-only" and told the user to build
+    triton-cpu. The question this function asks is "has this run a GPU",
+    and one vendor's driver is not that question.
+    """
+    visible = os.environ.get("CUDA_VISIBLE_DEVICES")
+    if visible == "":
+        return True
+    try:
+        from nbxtensor.backend.runtime import gpu_backend
+        gpu_backend()
+        return False
+    except Exception:
+        # No backend resolved at all — genuinely CPU-only. The detection
+        # raises rather than returning a sentinel, which is the answer.
+        return True
+
+
+def _triton_cpu_available() -> bool:
+    """Probe the upstream `triton-cpu` install without importing it."""
+    try:
+        # Upstream exposes either `triton_cpu` (older releases) or
+        # registers itself under `triton.backends.cpu` (newer). We
+        # accept either; both indicate the user installed the package.
+        import importlib.util
+        if importlib.util.find_spec("triton_cpu") is not None:
+            return True
+        # Newer integration path: triton with CPU backend registered.
+        spec = importlib.util.find_spec("triton.backends.cpu")
+        if spec is not None:
+            return True
+    except Exception:
+        return False
+    return False
+
+
+def ensure_triton_cpu_or_raise() -> None:
+    """Verify `triton-cpu` is installed when we're on a CPU-only profile.
+
+    Call sites: the entry points of `--triton` / `--triton-sequential`
+    on `RuntimeExecutor` and the CLI before any triton import that would
+    otherwise produce a cryptic `triton.runtime.driver.active` error.
+
+    Raises:
+        TritonCPUNotInstalledError: with an actionable message naming
+        the install command, docs path, and the `--compiled` fallback
+        that already works on CPU without any extra install.
+    """
+    if not _is_cpu_only_profile():
+        return  # GPU visible — standard triton path.
+    if _triton_cpu_available():
+        # Pre-set the env var so the triton runtime picks the CPU
+        # backend at first driver query. Must happen BEFORE any
+        # `import triton.runtime.driver` in this process.
+        os.environ.setdefault("TRITON_CPU_BACKEND", "1")
+        return
+    raise TritonCPUNotInstalledError(
+        "neurobrix run --triton (or --triton-sequential) on a CPU-only "
+        "device requires the upstream triton-cpu package, which is NOT "
+        "installed in this environment.\n"
+        "\n"
+        "Upstream does NOT publish a PyPI wheel today — install is "
+        "build-from-source:\n"
+        "    git clone https://github.com/triton-lang/triton-cpu.git\n"
+        "    cd triton-cpu\n"
+        "    pip install -r python/requirements.txt\n"
+        "    pip install -e .\n"
+        "(prerequisites: LLVM, CMake, Ninja, C++17 compiler. "
+        "Expect ~30 min build + ~15 GB peak disk.)\n"
+        "\n"
+        "See docs/triton_cpu_install.md for full instructions and "
+        "verification command.\n"
+        "\n"
+        "Alternative (no extra install required): run with --compiled. "
+        "The PyTorch CPU backend is mature and is the recommended "
+        "production path for CPU-only inference today. Numerical "
+        "fp16 paths on triton-cpu have known upstream gaps "
+        "(triton-cpu issues #147, #222); --compiled has no such gaps."
+    )
+
+
+def is_cpu_triton_active() -> bool:
+    """True iff triton-cpu has been selected for this process.
+
+    Set after `ensure_triton_cpu_or_raise()` succeeds on a CPU-only
+    profile. Downstream code (DeviceAllocator, wrappers, kv_cache)
+    uses this to branch between CUDA pointers and host pointers.
+    """
+    return os.environ.get("TRITON_CPU_BACKEND") == "1"
+
+
+def get_install_instructions() -> str:
+    """Return the install instructions string. Useful for CLI `--help`
+    text and error consolidation. Single source of truth for the
+    message so it cannot drift between sites."""
+    return (
+        "pip install triton-cpu   "
+        "(see docs/triton_cpu_install.md for build-from-source)"
+    )

nbxtensor/backend/device_facts.py

@@ -0,0 +1,105 @@
+"""Device facts the library reads itself, so it runs with no application around it (API.md section 11).
+
+Each answers from the device or from the backend's own documented capability — never from an application's profile.
+An application may still provide its own answer through `nbxtensor.host` (NeuroBrix provides the one its hardware
+profile declares); with none provided, the library's reading here is the answer.
+
+- `host_shares_memory_with_device()`: Metal asks the device (`MTLDevice.hasUnifiedMemory`); CUDA asks the runtime
+  (`cudaDeviceGetAttribute(cudaDevAttrIntegrated)`, attribute 18 of the CUDA runtime API's `cudaDeviceAttr`). A
+  backend whose answer is not read here is refused by name.
+- `kernels_carry_fp64()`: whether the backend's kernels compute float64 — Metal: no (the Metal Shading Language has
+  no double type); CUDA and HIP: yes (every NVIDIA and AMD GPU computes it, at whatever rate).
+- `memory_gb(memory_mb)` / `device_memory_gb(device_idx)`: a card's memory rounded to GB, the size a certified kernel
+  setting is proven for (an entry serves only cards of the size it was proven on: a 16 GB and a 32 GB V100 share an
+  architecture and not their best tiles under memory pressure). The device's memory is the one an application declared
+  (`declare_device_memory`: a census shadow sees no card; a plan made for a profile) or, with none declared, the
+  driver's total, read once per device.
+- `certified_dir()`: the default store of certified kernel settings: one directory per user in the platform's cache
+  (`$XDG_CACHE_HOME`, else `~/.cache`), `nbxtensor/certified/` — empty until the autotune fills it.
+"""
+from __future__ import annotations
+
+import ctypes
+import os
+from pathlib import Path
+
+__all__ = ["host_shares_memory_with_device", "kernels_carry_fp64", "certified_dir", "memory_gb", "declare_device_memory",
+           "device_memory_gb"]
+
+_CUDA_DEV_ATTR_INTEGRATED = 18      # cudaDevAttrIntegrated (CUDA Runtime API, enum cudaDeviceAttr)
+_FP64 = {"cuda": True, "hip": True, "metal": False}
+_DECLARED_MEMORY: dict = {}          # device index -> bytes an application declared
+_MEASURED_MEMORY: dict = {}          # device index -> bytes the driver reported, read once
+
+
+def memory_gb(memory_mb) -> "int | None":
+    """Memory in MB, rounded to GB (`round(mb / 1024)`); None when unknown or not positive."""
+    try:
+        mb = float(memory_mb)
+    except (TypeError, ValueError):
+        return None
+    return int(round(mb / 1024)) if mb > 0 else None
+
+
+def declare_device_memory(device_idx: int, nbytes) -> None:
+    """An application states device `device_idx`'s memory in bytes (None forgets it): a census shadow, which sees no
+    card, or a plan made for a profile whose card is not the one in this process."""
+    if nbytes is None:
+        _DECLARED_MEMORY.pop(int(device_idx), None)
+    else:
+        _DECLARED_MEMORY[int(device_idx)] = int(nbytes)
+
+
+def declared_device_memory() -> dict:
+    """The declared devices' memory, by index (a copy)."""
+    return dict(_DECLARED_MEMORY)
+
+
+def device_memory_gb(device_idx: int) -> "int | None":
+    """Device `device_idx`'s memory in GB: the declared one, else the driver's total (read once); None when neither
+    answers (no card visible and none declared)."""
+    idx = int(device_idx)
+    nbytes = _DECLARED_MEMORY.get(idx)
+    if nbytes is None:
+        if idx not in _MEASURED_MEMORY:
+            from nbxtensor.memory.allocator import DeviceAllocator
+            _MEASURED_MEMORY[idx] = int(DeviceAllocator.device_total_bytes(idx))
+        nbytes = _MEASURED_MEMORY[idx]
+    return memory_gb(nbytes / (1 << 20)) if nbytes and nbytes > 0 else None
+
+
+def host_shares_memory_with_device() -> bool:
+    """Does the current device draw from the host's memory pool?"""
+    from . import runtime as _rt
+    name = _rt.gpu_backend()
+    if name == "metal":
+        return bool(_rt.gpu_runtime().has_unified_memory)
+    if name == "cuda":
+        rt = _rt.gpu_runtime()
+        rc, dev = _rt.device_memory().get_device()
+        value = ctypes.c_int()
+        if rc == 0:
+            rc = rt.cudaDeviceGetAttribute(ctypes.byref(value), ctypes.c_int(_CUDA_DEV_ATTR_INTEGRATED),
+                                           ctypes.c_int(dev))
+        if rc != 0:
+            raise RuntimeError(f"ZERO FALLBACK: cudaDeviceGetAttribute(cudaDevAttrIntegrated) failed (error {rc}): "
+                               f"whether this device shares the host's memory is not known")
+        return bool(value.value)
+    raise RuntimeError(f"ZERO FALLBACK: whether a {name!r} device shares the host's memory is not read by nbxtensor; "
+                       f"provide it (nbxtensor.host.provide('host_shares_memory_with_device', ...))")
+
+
+def kernels_carry_fp64(profile=None) -> bool:
+    """Do the backend's kernels compute float64? (`profile`: an application's hardware profile, which an application's
+    own answer reads; the library's answer is the backend's.)"""
+    from . import runtime as _rt
+    name = _rt.gpu_backend()
+    if name not in _FP64:
+        raise RuntimeError(f"ZERO FALLBACK: nbxtensor does not know whether {name!r} kernels compute float64")
+    return _FP64[name]
+
+
+def certified_dir() -> Path:
+    """The library's own store of certified kernel settings, in the user's cache."""
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+    return Path(base) / "nbxtensor" / "certified"

nbxtensor/backend/device_files.py

@@ -0,0 +1,129 @@
+"""The library's device files: the kernel-relevant description of each device, one file per device
+(`devices/<vendor>/<name>.yml`, beside this module) — API.md section 11.
+
+What a kernel reads of a device lives here: its identification (`compute_capability`, `compute_capability_matches`,
+`architecture`), the tiles, the shared memory and registers, the warp size, the matrix unit, the dispatch limits, the
+autotune's screen tolerances and buckets. The list is the device-key census (`docs/nbxtensor/device_keys.txt`).
+
+An application may keep its own facts about the same devices in its own files (NeuroBrix: Prism's budgets and measured
+rates, in `config/vendors/<vendor>/<name>.yml`) and give the library their directory (`nbxtensor.host`,
+`vendors_dir`, optional). The two halves of one device are MERGED, and a key in both is refused by name: a fact is
+written once. With no application, the library's half is the whole description.
+"""
+from __future__ import annotations
+
+import copy
+import functools
+from pathlib import Path
+from typing import Any, Dict, Iterator, Optional, Tuple
+
+DEVICES = Path(__file__).resolve().parent / "devices"
+
+__all__ = ["DEVICES", "names", "read", "merge", "merged", "describe", "param", "in_force", "for_arch", "forget"]
+
+
+@functools.lru_cache(maxsize=None)
+def _parsed(path: str) -> Dict[str, Any]:
+    import yaml
+    with open(path) as f:
+        return yaml.safe_load(f) or {}
+
+
+def read(vendor: str, name: str) -> Dict[str, Any]:
+    """The library's half of device `vendor/name` (a copy), `{}` when the library describes none."""
+    path = DEVICES / vendor / f"{name}.yml"
+    return copy.deepcopy(_parsed(str(path))) if path.is_file() else {}
+
+
+def merge(library: Dict[str, Any], application: Dict[str, Any], where: str = "") -> Dict[str, Any]:
+    """The two halves of one device as one description; a key written in both is refused by name."""
+    out = copy.deepcopy(library)
+    for key, value in application.items():
+        if key not in out:
+            out[key] = copy.deepcopy(value)
+        elif isinstance(out[key], dict) and isinstance(value, dict):
+            out[key] = merge(out[key], value, f"{where}{key}.")
+        else:
+            raise ValueError(f"device file {where}{key}: written in both the library's device file and the "
+                             f"application's — a fact is written once (nbxtensor/backend/devices)")
+    return out
+
+
+def _application_dir() -> Optional[Path]:
+    from nbxtensor import host
+    if "vendors_dir" not in host.provided():
+        return None
+    return Path(host.need("vendors_dir")())
+
+
+def names() -> Iterator[Tuple[str, str, Path]]:
+    """(vendor, name, path) of every device described by the library or by the application, once each."""
+    seen = {}
+    roots = [DEVICES] + ([d] if (d := _application_dir()) is not None else [])
+    for root in roots:
+        for path in sorted(root.glob("*/*.yml")):
+            seen.setdefault((path.parent.name, path.stem), path)
+    for (vendor, name), path in sorted(seen.items()):
+        yield vendor, name, path
+
+
+def merged(vendor: str, name: str) -> Dict[str, Any]:
+    """Device `vendor/name` whole: the library's half merged with the application's, when it gave its directory."""
+    app = _application_dir()
+    app_half = {}
+    if app is not None and (app / vendor / f"{name}.yml").is_file():
+        app_half = copy.deepcopy(_parsed(str(app / vendor / f"{name}.yml")))
+    return merge(read(vendor, name), app_half, f"{vendor}/{name}: ")
+
+
+@functools.lru_cache(maxsize=256)
+def _described(vendor: str, name: str, app: Optional[str]) -> Dict[str, Any]:
+    app_half = {}
+    if app is not None and (Path(app) / vendor / f"{name}.yml").is_file():
+        app_half = _parsed(str(Path(app) / vendor / f"{name}.yml"))
+    lib_path = DEVICES / vendor / f"{name}.yml"
+    if not app_half and not lib_path.is_file():
+        known = ", ".join(f"{v}/{n}" for v, n, _ in names()) or "none"
+        raise LookupError(f"ZERO FALLBACK: no device file describes {vendor}/{name} (the library's "
+                          f"backend/devices/{vendor}/{name}.yml, nor the application's). Known: {known}")
+    return merge(_parsed(str(lib_path)) if lib_path.is_file() else {}, app_half, f"{vendor}/{name}: ")
+
+
+def describe(vendor: str, name: str) -> Dict[str, Any]:
+    """Device `vendor/name` whole (both halves), refused by name when neither describes it — the reader a kernel
+    asks for its device's facts. Merged once per process; a copy is handed out."""
+    app = _application_dir()
+    return copy.deepcopy(_described(vendor, name, None if app is None else str(app)))
+
+
+def param(vendor: str, name: str, section: str, key: str, default):
+    """One `<section>.<key>` of device `vendor/name`, `default` when the device states no such key (the device
+    itself is refused by name when nothing describes it) — the per-op reader: no copy of the whole description."""
+    app = _application_dir()
+    value = (_described(vendor, name, None if app is None else str(app)).get(section) or {}).get(key, _ABSENT)
+    if value is _ABSENT:
+        return default
+    return copy.deepcopy(value) if isinstance(value, (dict, list)) else value
+
+
+_ABSENT = object()
+
+
+def in_force() -> Dict[str, Any]:
+    """The description of the device the launch target names (both halves merged), `{}` when no device file matches
+    it — what every kernel setting reads, resolved once per process."""
+    from nbxtensor.ops import _configs
+    return _configs.active_vendor_profile()
+
+
+def for_arch(arch: str) -> Dict[str, Any]:
+    """The description an arch string resolves to, read WITHOUT a launch target (a caller the target depends on, or
+    a derivation that binds no device), and recorded as the one in force."""
+    from nbxtensor.ops import _configs
+    return _configs.vendor_profile_for_arch(arch)
+
+
+def forget() -> None:
+    """Forget the description in force: the next reader resolves it again (after the launch target is bound)."""
+    from nbxtensor.ops import _configs
+    _configs._ACTIVE_PROFILE.clear()

nbxtensor/backend/device_names.py

@@ -0,0 +1,18 @@
+"""The arch string a device is known by: the key its device file and its certified kernel settings are found under.
+
+A device reports a model name ("Apple M4 Pro", "Tesla V100-SXM2-16GB"); the arch string is that name lowercased with
+spaces hyphenated — "apple-m4-pro". One rule, owned by the library (it was a service the application provided,
+`nbxtensor.host`), read by the Metal backend and by any application keying its own files the same way.
+"""
+from __future__ import annotations
+
+import functools
+from typing import Optional
+
+__all__ = ["arch_string"]
+
+
+@functools.lru_cache(maxsize=16)
+def arch_string(model: Optional[str]) -> str:
+    """The arch string of a device's model name: lowercased, spaces hyphenated ("Apple M4 Pro" -> "apple-m4-pro")."""
+    return str(model or "").strip().lower().replace(" ", "-")