flashrt-structures 0.2.0__py3-none-any.whl

flashrt_structures/swap.py

@@ -0,0 +1,398 @@
+"""Transactional module attachment — mechanism only, no policy.
+
+Swaps host modules for bound structure implementations atomically: every
+staged swap is applied only if all of them can be applied, and a handle
+restores the originals exactly. Which modules to swap, and whether an
+implementation passed its gates, is decided by the caller before
+staging; this layer refuses partial application by construction.
+
+The handle is also where the attachment answers for itself at runtime.
+Every swapped-in structure carries a guard recording the form it was
+calibrated for (:mod:`flashrt_structures.guard`); attaching gives each
+guard its path and a way to restore the host module, and
+``handle.report()`` reads them back. An attachment whose report shows
+fallbacks is one that is not running the structures it claims to — that
+has to be visible here, because nothing downstream can tell the
+difference.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import torch
+
+from .guard import GUARD_ATTR, SeamGuard, collect as _collect_guards
+
+
+def resolve_parent(root: torch.nn.Module, path: str) -> tuple[torch.nn.Module, str]:
+    """Resolve the parent module and attribute name for a dotted path."""
+    parts = path.split(".")
+    parent = root
+    for part in parts[:-1]:
+        parent = parent[int(part)] if part.isdigit() else getattr(parent, part)
+    attr = parts[-1]
+    leaf = parent[int(attr)] if attr.isdigit() else getattr(parent, attr)
+    if not isinstance(leaf, torch.nn.Module):
+        raise TypeError(f"{path!r} does not resolve to a torch.nn.Module")
+    return parent, attr
+
+
+def _get(parent: torch.nn.Module, attr: str) -> torch.nn.Module:
+    return parent[int(attr)] if attr.isdigit() else getattr(parent, attr)
+
+
+def _set(parent: torch.nn.Module, attr: str,
+         module: torch.nn.Module) -> None:
+    if attr.isdigit():
+        parent[int(attr)] = module
+    else:
+        setattr(parent, attr, module)
+
+
+@dataclass
+class AttachHandle:
+    """Restores the originals of one committed attachment."""
+
+    _entries: list[tuple[torch.nn.Module, str, torch.nn.Module]]
+    records: Mapping[str, Any] = field(default_factory=dict)
+    active: bool = True
+    _guards: dict[str, SeamGuard] = field(default_factory=dict)
+    _revert: list[Any] = field(default_factory=list)
+    _store: Any = None
+    _paths: list[str] = field(default_factory=list)
+
+    def consume(self, store=None) -> dict:
+        """Move every replaced module's weights off the device.
+
+        The resident tier is gone: an attachment no longer keeps a
+        second copy of the model in device memory for the sake of an
+        instant fallback. Each original's truth moves to the weight
+        store — the checkpoint file when provenance verifies, pinned
+        host memory otherwise — and its device storage is freed.
+        Fallback and ``detach`` both survive as restore-from-store:
+        slower, never wrong. Reversible until :meth:`finalize`.
+        """
+        from .storage import WeightStore
+
+        if store is None:
+            store = self._store or WeightStore(
+                checkpoint=self.records.get("checkpoint"))
+        self._store = store
+        freed = 0
+        serving = 0
+        paths = self._paths or [""] * len(self._entries)
+        for path, (parent, attr, original) in zip(paths, self._entries):
+            # a seat that actively calls its retained host (a cadence
+            # bank refreshing through the host projection) declares it:
+            # that original is serving, not merely held for fallback,
+            # and consuming it would corrupt the live path
+            current = _get(parent, attr)
+            if getattr(current, "_frt_host_serving", False):
+                serving += 1
+                continue
+            freed += store.stash_module(path, original)
+        # the caching allocator keeps the bind-era blocks reserved;
+        # hand them back so co-tenant CUDA consumers see the space —
+        # only unused cached blocks are released, capture pools are
+        # private and untouched
+        returned = 0
+        if torch.cuda.is_available():
+            before = torch.cuda.memory_reserved()
+            torch.cuda.empty_cache()
+            returned = before - torch.cuda.memory_reserved()
+        self.records = dict(self.records, consumed=dict(
+            store.stats, freed_bytes=freed, kept_serving=serving,
+            cache_returned_bytes=returned))
+        return {"consumed": True, "freed_bytes": freed,
+                "kept_serving": serving,
+                "cache_returned_bytes": returned,
+                "tiers": {"disk": store.stats["disk"],
+                          "ram": store.stats["ram"]}}
+
+    def finalize(self) -> dict:
+        """Make the consumption permanent.
+
+        Drops the restore tickets (including any host-RAM spill), flips
+        fallback off — a contract miss must refuse now, not restore —
+        and forbids ``detach``. Consumes first when the caller has not.
+        Irreversible, and says so in the receipt it returns.
+        """
+        if self._store is None:
+            self.consume()
+        freed = self.records.get("consumed", {}).get("freed_bytes", 0)
+        paths = set(self._paths)
+        for parent, attr, original in self._entries:
+            self._store.drop_module(original)
+            current = _get(parent, attr)
+            if hasattr(current, "_frt_can_fallback"):
+                current._frt_can_fallback = False
+        # the guard is the one that answers at call time: flip its own
+        # fallback bit too, or a contract miss would run an emptied host
+        for site, guard in self._guards.items():
+            root_site = site.split("::", 1)[0]
+            if root_site in paths:
+                guard.can_fallback = False
+        self.records = dict(self.records,
+                            finalized={"freed_bytes": freed})
+        self._finalized = True
+        return {"finalized": True, "freed_bytes": freed}
+
+    def detach(self) -> None:
+        """Restore every swapped module. Idempotent.
+
+        Consumed weights come back from the store first — the promise
+        is the same bit-exact host, backed by the checkpoint file or
+        the host-RAM spill instead of a resident device copy.
+
+        Also runs any ``revert`` callables the caller handed over. Some
+        seams are not modules at paths — an adapter that patches a
+        library-level function — and restoring only what ``setattr`` can
+        reach would leave those live while reporting the model as restored.
+        """
+        if getattr(self, "_finalized", False):
+            raise RuntimeError(
+                "attachment was finalized: the host originals were "
+                "released and detach is impossible")
+        if not self.active:
+            return
+        for parent, attr, original in reversed(self._entries):
+            if self._store is not None:
+                self._store.restore_module(original)
+            _set(parent, attr, original)
+        for undo in reversed(self._revert):
+            undo()
+        self._revert.clear()
+        for guard in self._guards.values():
+            guard.release_site()
+        self.active = False
+
+    # ---- what actually ran -----------------------------------------
+
+    def report(self) -> dict[str, dict[str, Any]]:
+        """Per-seam ledger: calls, fallbacks, and why.
+
+        The unit of truth for "did this attachment run what it says". A
+        seam with ``fallbacks`` above zero ran the host module for that
+        many calls; one with ``detached`` set gave up and put the host
+        module back. Tests assert on this rather than assuming it.
+
+        Counts are eager-only, and necessarily so: inside a compiled or
+        captured region the kernel runs without re-entering Python, so
+        there is nothing left to count. A captured host therefore reports
+        zero calls for the seams inside its graph — read that as "this
+        ledger does not cover the graph", not as "the seam did not run".
+        The graph's own parity check is what covers it.
+        """
+        return {site: guard.entry()
+                for site, guard in sorted(self._guards.items())}
+
+    def summary(self) -> dict[str, Any]:
+        """The report reduced to what a caller has to act on.
+
+        ``seams_never_called`` means "no eager call reached this seam",
+        which for a captured host is every seam in the graph. It is a
+        finding on an eager host and noise on a captured one.
+        """
+        entries = self.report()
+        fell_back = sorted(site for site, e in entries.items()
+                           if e["fallbacks"])
+        return {
+            "seams": len(entries),
+            "guarded_calls": sum(e["calls"] for e in entries.values()),
+            "fallbacks": sum(e["fallbacks"] for e in entries.values()),
+            "seams_fell_back": fell_back,
+            "seams_self_detached": sorted(
+                site for site, e in entries.items() if e["detached"]),
+            "seams_never_called": sorted(
+                site for site, e in entries.items() if not e["calls"]),
+            "clean": not fell_back,
+        }
+
+    def manifest(self) -> dict[str, Any]:
+        """One document answering "why does this box run this form".
+
+        The receipts exist — band decisions, variant trails, format
+        races, the workspace ledger, the weight-residency receipt — but
+        scattered, each with its own schema. Cross-box drift diagnosis
+        and decision transport both need the single view: device
+        fingerprint, every seam with its kind and its story, the
+        decisions consumed, the memory plan, and what happened to the
+        weights. Read-only; safe to serialize.
+        """
+        import json as _json
+
+        device = (torch.cuda.get_device_name(0)
+                  if torch.cuda.is_available() else "cpu")
+        decisions: dict[str, Any] = {}
+        try:
+            from .decisions import _cache_path
+            decisions = _json.loads(_cache_path().read_text())
+        except Exception:
+            pass
+        workspace_report: Any = None
+        try:
+            from .workspace import report as _ws_report
+            workspace_report = _ws_report()
+        except Exception:
+            pass
+        seams = {}
+        for site, guard in sorted(self._guards.items()):
+            entry = guard.entry()
+            seams[site] = {
+                "kind": entry.get("kind"),
+                "calls": entry.get("calls"),
+                "fallbacks": entry.get("fallbacks"),
+                "notes": entry.get("notes"),
+            }
+        return {
+            "device": device,
+            "seams": seams,
+            "summary": self.summary(),
+            "records": dict(self.records),
+            "decisions": {k: v for k, v in decisions.items()
+                          if k.startswith(device + "|")},
+            "workspace": workspace_report,
+        }
+
+    def raise_on_fallback(self) -> None:
+        """Assertion helper: fail loudly if any seam fell back.
+
+        For tests, and for callers who would rather not ship a run whose
+        seams quietly reverted. Reads the ledger, so it costs nothing in
+        the hot path.
+        """
+        summary = self.summary()
+        if summary["clean"]:
+            return
+        detail = {site: entry["last_reason"]
+                  for site, entry in self.report().items()
+                  if entry["fallbacks"]}
+        raise RuntimeError(
+            f"{len(detail)} seam(s) fell back to the host module during "
+            f"this attachment ({summary['fallbacks']} call(s) total): "
+            f"{detail}")
+
+
+def attach(
+    root: torch.nn.Module,
+    swaps: Mapping[str, torch.nn.Module],
+    *,
+    records: Mapping[str, Any] | None = None,
+    on_guard_fail: str = "fallback",
+    allow_training: bool = False,
+    observe: Mapping[str, torch.nn.Module] | None = None,
+    revert: Any = None,
+    store: Any = None,
+    consume: bool = False,
+) -> AttachHandle:
+    """Atomically replace the modules at ``swaps`` paths.
+
+    All paths are resolved and validated before the first swap is
+    applied; any resolution failure leaves the model untouched. Callers
+    pass the qualification ``records`` that justified the attachment so
+    the handle carries its own evidence.
+
+    ``on_guard_fail`` selects what a seam does when it is called outside
+    the form it was bound for: ``"fallback"`` runs the host module and
+    counts it in the ledger, ``"raise"`` refuses immediately. Development
+    and CI should use ``"raise"`` — a fallback a test tolerates is a
+    fallback nobody reads.
+
+    Attaching to a model in training mode is refused: these
+    implementations pack and quantise the host weights once at bind time,
+    so a gradient step would update the host copy and leave the kernel's
+    stale. Pass ``allow_training=True`` for a forward-only pass that
+    happens to sit inside a training script.
+
+    ``observe`` names modules that carry a guard but are not swapped here
+    — an adapter's routed seam. They are reported in the ledger and never
+    installed. ``revert`` collects undo callables for host mutations made
+    before this call, so ``detach`` restores those too.
+
+    Weight residency is a lifecycle, not a mode: attach → validate →
+    ``handle.consume()`` → optionally ``handle.finalize()``. Consuming
+    moves each replaced original's truth to the weight ``store`` (the
+    checkpoint file when provenance verifies, pinned host memory
+    otherwise) and frees its device storage — there is no resident
+    tier to keep. Fallback and ``detach`` restore from the store;
+    seats that declare their retained host as actively serving keep it
+    whole. Consumption comes after the caller's validation pass
+    because the attached model still owes the host schema (state_dict,
+    A/B reference arms, captures that alias host weights) until then;
+    ``consume=True`` collapses the steps for callers with no such
+    pass.
+    """
+    if not swaps and not observe:
+        raise ValueError("no swaps or routed seams staged")
+    if on_guard_fail not in ("fallback", "raise"):
+        raise ValueError(
+            f"on_guard_fail must be 'fallback' or 'raise', "
+            f"got {on_guard_fail!r}")
+    if root.training and not allow_training:
+        raise ValueError(
+            "structures.attach: the model is in training mode. These "
+            "implementations pack and quantise the host weights once at "
+            "bind time, so training through them would update the host "
+            "copy and leave the kernel's stale. Call model.eval() first, "
+            "or pass allow_training=True for a forward-only pass.")
+
+    staged: list[tuple[torch.nn.Module, str, torch.nn.Module,
+                       torch.nn.Module]] = []
+    for path, replacement in swaps.items():
+        parent, attr = resolve_parent(root, path)
+        staged.append((parent, attr, _get(parent, attr), replacement))
+
+    entries: list[tuple[torch.nn.Module, str, torch.nn.Module]] = []
+    try:
+        for parent, attr, original, replacement in staged:
+            _set(parent, attr, replacement)
+            entries.append((parent, attr, original))
+    except Exception:
+        for parent, attr, original in reversed(entries):
+            _set(parent, attr, original)
+        raise
+
+    # ---- give every guard its site and its own way out ----
+    # keyed by guard identity as well as by site: one module can be
+    # reachable by two routes (a composed block holds the host block, so a
+    # core hanging off the host's attention is found twice), and counting
+    # it twice would overstate how many seams an attachment has
+    guards: dict[str, SeamGuard] = {}
+    seen: set[int] = set()
+    # named seams first: an adapter knows what its routed seam should be
+    # called, and the same object found by walking a composed structure
+    # would otherwise claim it under an incidental path
+    for site, module in (observe or {}).items():
+        for child, guard in _collect_guards(module):
+            if id(guard) in seen:
+                continue
+            seen.add(id(guard))
+            key = site if not child else f"{site}::{child}"
+            guard.bind_site(key, restore=None, mode=on_guard_fail)
+            guards[key] = guard
+    for (parent, attr, original), (path, replacement) in zip(
+            entries, swaps.items()):
+        for child, guard in _collect_guards(replacement):
+            if id(guard) in seen:
+                continue
+            seen.add(id(guard))
+            site = path if not child else f"{path}::{child}"
+            # only the module actually swapped in at a path can restore
+            # itself; a guard held inside a composed structure reports but
+            # cannot exit on its own
+            restore = ((lambda p=parent, a=attr, o=original: _set(p, a, o))
+                       if not child else None)
+            guard.bind_site(site, restore=restore, mode=on_guard_fail)
+            guards[site] = guard
+
+    handle = AttachHandle(_entries=entries, records=dict(records or {}),
+                          _guards=guards, _revert=list(revert or ()),
+                          _store=store, _paths=list(swaps.keys()))
+    if consume:
+        handle.consume(store)
+    return handle
+
+
+__all__ = ["AttachHandle", "attach", "resolve_parent", "GUARD_ATTR"]

flashrt_structures/workspace.py

@@ -0,0 +1,110 @@
+"""Shared workspaces: seat scratch lives in a pool, not in every seat.
+
+A pack's sibling stash, a producer's residual scratch, a wire's packed
+buffer — their lifetimes all sit inside one layer's forward. Sequential
+layers therefore never need their own copies: every seat that asks for
+the same (shape, dtype, device, tag) receives the *same* tensor, and
+the pool's footprint is one layer's worth instead of layers x tokens.
+Capture-compatible by the same argument that makes memory pools
+capture-compatible: the graph records fixed pointers, and same-stream
+sequential lifetimes never overlap.
+
+Two lease kinds:
+- ``scratch``: contents are call-transient; the seat must write before
+  it reads (packs and producers already do).
+- ``ones``: constant-filled; shared freely and never written.
+
+The pool is also the accounting surface: :func:`report` returns bytes
+held and the reuse count per tag — the memory column of the receipt.
+"""
+
+from __future__ import annotations
+
+import weakref
+
+import torch
+
+_POOL: dict[tuple, torch.Tensor] = {}
+_LEASES: dict[str, int] = {}
+# exclusive leases are owned by their seats, not the pool; the receipt
+# tracks them through weak references so bytes leave the ledger the
+# moment a detached seat releases its buffer
+_EXCLUSIVE: dict[str, list] = {}
+
+
+def lease(shape, dtype, device, *, tag: str,
+          fill: str = "scratch",
+          exclusive: bool = False) -> torch.Tensor:
+    """One shared tensor for every seat asking this (shape, tag).
+
+    The pool's safety argument is single-stream sequential execution:
+    layer i's scratch is dead before layer i+1 writes it *because they
+    share one stream*. A caller leasing from a non-default stream is
+    outside that argument, and the pool refuses rather than corrupt
+    silently — multi-stream serving needs per-lane isolation first.
+
+    ``exclusive=True`` allocates a private tensor instead of joining
+    the shared slab, still counted in the pool's receipt. It exists
+    for *state*, not scratch: a buffer whose consumer is the host may
+    be retained past the tick (a KV cache holding a reader's view was
+    the measured failure — every layer's write clobbered every other
+    layer's cached slice, with every ledger clean). Sharing such a
+    buffer requires the immediacy of consumption as a verified fact;
+    absent that fact, state is exclusive.
+    """
+    if (torch.cuda.is_available()
+            and str(device).startswith("cuda")
+            and torch.cuda.current_stream()
+            != torch.cuda.default_stream()):
+        raise RuntimeError(
+            "workspace: leasing from a non-default CUDA stream — the "
+            "shared pool's lifetime argument only covers single-stream "
+            "sequential execution; isolate per-stream lanes first")
+    if exclusive:
+        buf = torch.zeros(*shape, dtype=dtype, device=device)
+        if fill == "ones":
+            buf.fill_(1)
+        _LEASES[tag] = _LEASES.get(tag, 0) + 1
+        _EXCLUSIVE.setdefault(tag, []).append(weakref.ref(buf))
+        return buf
+    key = (tuple(shape), dtype, str(device), tag, fill)
+    buf = _POOL.get(key)
+    if buf is None:
+        buf = torch.zeros(*shape, dtype=dtype, device=device)
+        if fill == "ones":
+            buf.fill_(1)
+        _POOL[key] = buf
+    _LEASES[tag] = _LEASES.get(tag, 0) + 1
+    return buf
+
+
+def report() -> dict:
+    """Bytes held and lease counts — the receipt's memory column.
+
+    ``held_bytes`` covers both the shared pool and every live exclusive
+    lease; ``exclusive_by_tag`` breaks the latter out so the receipt
+    shows what stayed private and what the pool actually deduplicated.
+    """
+    by_tag: dict[str, int] = {}
+    for (shape, dtype, _dev, tag, _fill), buf in _POOL.items():
+        by_tag[tag] = by_tag.get(tag, 0) + buf.numel() * buf.element_size()
+    exclusive_by_tag: dict[str, int] = {}
+    for tag, refs in _EXCLUSIVE.items():
+        live = [ref() for ref in refs]
+        refs[:] = [ref for ref, buf in zip(refs, live) if buf is not None]
+        held = sum(buf.numel() * buf.element_size()
+                   for buf in live if buf is not None)
+        if held:
+            exclusive_by_tag[tag] = held
+    return {"held_bytes": sum(by_tag.values())
+            + sum(exclusive_by_tag.values()),
+            "by_tag": by_tag,
+            "exclusive_by_tag": exclusive_by_tag,
+            "leases": dict(_LEASES)}
+
+
+def clear() -> None:
+    """Drop every pooled buffer (between hosts, or in tests)."""
+    _POOL.clear()
+    _LEASES.clear()
+    _EXCLUSIVE.clear()

flashrt_structures-0.2.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: flashrt-structures
+Version: 0.2.0
+Summary: Attach FlashRT's verified acceleration structures to an unmodified PyTorch host (lerobot, Isaac-GR00T, openpi, transformers, diffusers, vLLM, SGLang) with no fork and no edit to the host.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/flashrt-project/FlashRT-Structures
+Project-URL: Repository, https://github.com/flashrt-project/FlashRT-Structures
+Project-URL: Issues, https://github.com/flashrt-project/FlashRT-Structures/issues
+Project-URL: Engine, https://github.com/flashrt-project/FlashRT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flash-rt>=0.1.0
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Provides-Extra: hub
+Requires-Dist: kernels>=0.12; extra == "hub"
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Requires-Dist: safetensors; extra == "torch"
+Dynamic: license-file
+
+# FlashRT Structures
+
+Attach [FlashRT](https://github.com/flashrt-project/FlashRT)'s verified
+acceleration structures to an **unmodified** PyTorch host: `lerobot`,
+Isaac-GR00T, `openpi`, `transformers`, `diffusers`, and inside vLLM /
+SGLang. No fork, no edit to the host's source. Kernels arrive from the
+Hugging Face kernel hub at bind time.
+
+```python
+import flashrt_structures as structures
+
+plan = structures.attach(model, forward)   # discover → calibrate → gate → activate
+print(structures.explain(plan))            # bound / routed / kept-at-host / refused, with reasons
+
+loop = structures.decode_loop(model, max_len=4096)      # serving door
+out  = loop.generate(input_ids, max_new_tokens=256)
+```
+
+Measured on VLA, VLM, LLM and video models across RTX 5090 and Jetson AGX
+Thor; the films are in the
+[walkthrough](https://huggingface.co/spaces/liangsu9988/fast-kernels-are-not-fast-pipelines).
+
+## What this package is, and what it is not
+
+A *structure* is a versioned specification of one model region: boundary
+tensors, framework-neutral weight slots, calibration points, gates, and a
+plain-torch reference that is the gate's ground truth. Those
+specifications, and the per-host *bindings* that say where the positions
+sit on a concrete host, live in the FlashRT repository as
+`flash_rt.catalog` and ship in the pure-Python `flash-rt` wheel.
+
+This package is everything that acts on them for a PyTorch host:
+
+| layer | here |
+|---|---|
+| `impls/` | executable forms per structure family: FP8 / NVFP4 / weight-only projections and FFNs, fused norm producers, attention cores, fused decoder and vision towers, the whole-step decode loop, graph-lowering pins |
+| `adapters/` | host adapters: `transformers`, `diffusers`, Gemma / Qwen attention, gated-delta, and the vLLM / SGLang engine hooks |
+| `discover.py`, `autobuild.py`, `points.py`, `schemes.py`, `gates.py` | structural discovery, the one-pass discover → calibrate → bind assembly, calibration collection, quantisation schemes, accuracy judgment |
+| `guard.py`, `swap.py`, `frontdoor.py`, `stages.py`, `recipe.py` | the runtime contract and ledger, attach / detach, the one-call door, graph capture with declared swap windows, recipes |
+| `examples/` | the explicit pipeline: seat tables, calibration hooks and binder calls written out by hand for GR00T N1.7 and π0.5 |
+
+Structure specs, references and bindings are **not** here. A new structure
+or a new host binding is a change to `flash_rt/catalog/` in FlashRT; a new
+executable form, adapter or door is a change here.
+
+## Install
+
+```bash
+pip install flashrt-structures            # pulls flash-rt (pure Python) for the catalog
+pip install "flashrt-structures[hub]"     # + the kernel hub client, needed to bind
+```
+
+`flash-rt` must be a version that ships the catalog as `flash_rt.catalog`:
+FlashRT `main` after the structures split, or a wheel newer than 0.1.0
+(the 0.1.0 wheel on PyPI predates the split and still carries the layer
+inside `flash_rt.structures`). An older flash-rt makes `import
+flashrt_structures` fail with a message that says exactly this.
+
+Bring your own torch. Which kernels exist is decided by the torch version:
+the hub's published face is thickest at `torch 2.11 / cu128` on x86-64 and
+much thinner at the newest release. If binds refuse on a fresh install,
+check the torch version first.
+
+Three boundaries produce refusals that look like bugs and are not:
+
+- **Kernel availability follows the hub's build matrix, not this
+  package's.** The wheel installs on any torch; the kernels do not exist
+  for every torch.
+- **`HF_HUB_OFFLINE=1` makes every kernel unavailable, even with a fully
+  warm cache**, because a version specifier has to resolve refs online.
+  Air-gapped deployments should stage packages and point at them with
+  `LOCAL_KERNELS=<repo>=<path>` rather than switching the hub offline.
+- **aarch64 (Jetson Thor, sm_110) is not covered by the current
+  qualification pass.** Nothing in the wheel is architecture-bound, but
+  the engine adapters were last verified against vLLM 0.26 on Thor in
+  August 2026, not in the release run.
+
+## Where to read next
+
+- [`docs/hosts.md`](docs/hosts.md) — which door your host takes, how to
+  tell a seated run from a refused one from a door that never fired, how
+  to read a refusal, and what has been measured where.
+- [`docs/structures.md`](docs/structures.md) — the norm: what a structure
+  is, the three-layer split, calibration reuse, accuracy bands, the
+  runtime contract and ledger, and the norms that came from being wrong.
+- [`docs/serving_engines.md`](docs/serving_engines.md) — attaching inside
+  vLLM or SGLang without forking either.
+- [`docs/adopt_in_20_lines.md`](docs/adopt_in_20_lines.md) — a measured
+  Qwen3-VL-8B adoption, twenty lines end to end.
+- [`examples/README.md`](examples/README.md) — the explicit pipeline
+  against the automatic one, measured on two GR00T N1.7 hosts.
+- [`docs/structure_release_qualification.md`](docs/structure_release_qualification.md)
+  — how a structure moves from a reusable boundary to a released hardware
+  route.
+- [`AGENTS.md`](AGENTS.md) — the operating procedure for producing
+  structures; [`docs/structure_contributing.md`](docs/structure_contributing.md)
+  — the contribution boundary and PR self-review checklist.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest tests            # the CPU set; two *_gpu tests need a CUDA device and hub access
+```
+
+## License
+
+Apache-2.0, same as FlashRT.