Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Build and publish signed prebuilt CUDA 13 wheels for torch 2.13 and 2.14 (#11515)
Daniel Hana868d2213a36
diff --git a/.github/scripts/patch_mamba_cxx20.py b/.github/scripts/patch_mamba_cxx20.pynew file mode 100644index 00000000000..f8a5b52ab5d--- /dev/null+++ b/.github/scripts/patch_mamba_cxx20.py@@ -0,0 +1,75 @@+#!/usr/bin/env python3+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Switch mamba-ssm's CUDA build from -std=c++17 to -std=c++20, which torch 2.13 requires.++state-spaces/mamba compiles its Mamba-1 selective-scan kernels at C++17. torch 2.13 raised its+own headers to C++20, and nvcc stops at the first construct it cannot parse at 17, so the build+fails before it produces anything. flash-attn already made the same change upstream+(Dao-AILab/flash-attention#2899); mamba has not, which is why this file exists and there is no+equivalent for the other two packages.++Only the four `-std=c++17` occurrences inside setup.py's `if KEEP_CUDA_BUILD:` block are+touched, in both the HIP and the CUDA branch, because both are inside it and leaving one behind+would mean the patch silently stops applying if upstream reorders them.++It is deliberately NOT a `git apply` of a diff. A diff carries line numbers and context, so an+unrelated edit above it turns "upstream changed the flags" into "the hunk did not apply", and+the two want different responses. This asserts on the text instead: every occurrence must be one+of the two known states, an already-patched file is a success with nothing to do, and anything+else -- a new flag, a third branch, a c++23 bump upstream -- fails loudly so a human decides,+rather than building something nobody chose.++Usage: patch_mamba_cxx20.py <path to mamba setup.py>+"""++from __future__ import annotations++import sys+from pathlib import Path++OLD = '"-std=c++17"'+NEW = '"-std=c++20"'++# Two in the HIP branch, two in the CUDA branch: the "cxx" list and the nvcc list of each.+EXPECTED_OCCURRENCES = 4+++def patch(path: Path) -> int:+ source = path.read_text(encoding = "utf-8")++ already = source.count(NEW)+ found = source.count(OLD)++ if found == 0 and already >= EXPECTED_OCCURRENCES:+ print(f"{path}: already at c++20 ({already} occurrences), nothing to do")+ return 0++ if found != EXPECTED_OCCURRENCES:+ print(+ f"::error::{path}: expected {EXPECTED_OCCURRENCES} occurrences of {OLD}, "+ f"found {found} (and {already} of {NEW}). Upstream changed the compile flags; "+ "re-read setup.py before bumping the pin.",+ file = sys.stderr,+ )+ return 1++ path.write_text(source.replace(OLD, NEW), encoding = "utf-8")+ print(f"{path}: {found} occurrences of {OLD} -> {NEW}")+ return 0+++def main(argv: list[str]) -> int:+ if len(argv) != 2:+ print("usage: patch_mamba_cxx20.py <setup.py>", file = sys.stderr)+ return 2+ path = Path(argv[1])+ if not path.is_file():+ print(f"::error::{path} does not exist", file = sys.stderr)+ return 1+ return patch(path)+++if __name__ == "__main__":+ raise SystemExit(main(sys.argv))diff --git a/.github/scripts/prebuilt_wheels.py b/.github/scripts/prebuilt_wheels.pynew file mode 100644index 00000000000..c80cc1c3077--- /dev/null+++ b/.github/scripts/prebuilt_wheels.py@@ -0,0 +1,484 @@+#!/usr/bin/env python3+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The build plan for the prebuilt CUDA wheels, and the release notes that describe them.++prebuilt-cuda-wheels.yml needs three things that are all awkward inside YAML and all worth a+unit test: a matrix expanded from free-text dispatch inputs, the upstream wheel filename for a+cell, and a release body regenerated from whatever is on the release right now. They live here+together because they share one table -- SPECS below -- and a drift between the name a cell+builds and the name the notes advertise is the one failure nobody would notice until a user's+pip install 404s.++Every value that reaches a shell command in the workflow is validated against that table rather+than interpolated from the dispatch input. The workflow is dispatch-only and gated, but an+input that becomes `git checkout $REF` is a command injection whether or not the door in front+of it is locked, so package, torch and python are resolved to known-good constants here and the+raw input is never used again.++Subcommands:++ matrix read UW_PACKAGES / UW_TORCH_VERSIONS / UW_PYTHON_VERSIONS from the environment+ and print the `include` list for the build matrix as JSON.+ wheel-name print the single upstream-style filename for one cell.+ notes read `sha256 filename` lines on stdin and print the release body.++Usage:+ prebuilt_wheels.py matrix+ prebuilt_wheels.py wheel-name --package flash-attn --torch 2.13.0 --python 3.13+ prebuilt_wheels.py notes --tag prebuilt-wheels-cu13 --repo unslothai/unsloth < SHA256SUMS+"""++from __future__ import annotations++import argparse+import json+import os+import sys++# The CUDA major that every wheel here is built against, and the only one. It is the local+# version segment upstream writes (cu13), not the toolkit patch level: upstream normalises+# 13.x to "13" in get_wheel_url(), and a wheel built with 13.0 and one built with 13.2 are+# interchangeable for the purpose the tag serves, which is "do not install this on cu12".+CUDA_TAG = "13"++# The toolkit actually installed on the runner. Separate from CUDA_TAG because this one is a+# real apt package version and is reported in the notes, where "cu13" alone would be vague.+CUDA_TOOLKIT = "13.0"++# torch 2.7 and newer ship pip wheels built with _GLIBCXX_USE_CXX11_ABI=1, so there is no+# abiFALSE variant to build for 2.13 or 2.14 -- upstream's own matrix excludes it from 2.7 on.+# The tag is still in the filename because it is in every upstream filename, and a resolver+# that pattern-matches upstream names has to find it here too.+CXX11_ABI = "TRUE"++# Linux x86_64 only. The wheel is tagged linux_x86_64 rather than manylinux_*, exactly as+# upstream tags its own, so pip installs it on any glibc without a floor check; the practical+# floor is the runner's glibc, which is why the build runs on ubuntu-22.04 (glibc 2.35) and+# not on ubuntu-latest.+PLATFORM_TAG = "linux_x86_64"++# Source revisions, pinned to a commit rather than a branch or a tag.+#+# flash-attn 2.8.4 does not exist as an upstream release: 2.8.3.post1 is the newest tag, and+# the version in flash_attn/__init__.py on main has already moved to 2.8.4. The pin is the+# commit that carries that version AND the c++20 switch (Dao-AILab/flash-attention#2899),+# which is what makes it build against torch 2.13 at all.+#+# mamba-ssm and causal-conv1d are pinned to the commit their released version was cut from.+SPECS = {+ "flash-attn": {+ "dist": "flash_attn",+ "version": "2.8.4",+ "repo": "Dao-AILab/flash-attention",+ "ref": "edb5c76ee329b18ed95d1f7ea9aa522a1331ab7d",+ "submodules": True,+ # The build is one nvcc invocation per (kernel, arch) and the kernels are large. On a+ # 4-core, 16 GB hosted runner nvcc 13 goes OOM above one job; this is upstream's own+ # value for the cu13 legs of its publish matrix, arrived at the same way.+ "max_jobs": "1",+ "nvcc_threads": "2",+ "env": {+ "FLASH_ATTENTION_FORCE_BUILD": "TRUE",+ "FLASH_ATTENTION_FORCE_CXX11_ABI": CXX11_ABI,+ # Upstream's default is "80;90;100;110;120". 110 (Thor) is dropped because nothing+ # Unsloth targets runs it and each arch is a full pass over every kernel. 86 and 89+ # are absent for a different reason: they are not needed. A cubin is compatible+ # forward across the minor versions of its major, so sm_80 code runs on sm_86 and+ # sm_89 hardware, and setup.py additionally emits PTX for the newest arch so an+ # unlisted future card JITs rather than failing.+ "FLASH_ATTN_CUDA_ARCHS": "80;90;100;120",+ },+ # ~4.5 h for the four architectures at MAX_JOBS=1. GitHub kills a job at 6 h, so the+ # build is wrapped in `timeout` below that, to fail as a build timeout with logs+ # rather than as a job cancellation with none.+ "build_timeout": "300m",+ "import_names": ["flash_attn", "flash_attn_2_cuda"],+ },+ "causal-conv1d": {+ "dist": "causal_conv1d",+ "version": "1.7.0",+ "repo": "Dao-AILab/causal-conv1d",+ "ref": "cd81f0413cad2fc1e6f17e785ac39f59aae690cd",+ "submodules": False,+ "max_jobs": "4",+ "nvcc_threads": "2",+ "env": {+ "CAUSAL_CONV1D_FORCE_BUILD": "TRUE",+ },+ "build_timeout": "120m",+ "import_names": ["causal_conv1d", "causal_conv1d_cuda"],+ },+ "mamba-ssm": {+ "dist": "mamba_ssm",+ "version": "2.3.2.post1",+ "repo": "state-spaces/mamba",+ "ref": "e9594ce1c732d97440f0332fdc43170a2294dbfa",+ "submodules": False,+ "max_jobs": "4",+ "nvcc_threads": "2",+ "env": {+ "MAMBA_FORCE_BUILD": "TRUE",+ # Mamba-1's selective-scan CUDA kernels are opt-in upstream. They are the reason+ # this wheel is worth building: without them mamba_ssm falls back to the reference+ # path, and selective_scan_cuda -- the extension whose missing symbols are the+ # whole ABI problem -- is not in the wheel at all.+ "MAMBA_KEEP_CUDA_BUILD": "TRUE",+ },+ # The one source edit in this workflow. See patch_mamba_cxx20.py.+ "patch": "cxx20",+ "build_timeout": "180m",+ "import_names": ["mamba_ssm", "selective_scan_cuda"],+ },+}++# torch minors, not patch levels, are what the ABI is keyed on, but the build needs an exact+# version to pip install, so the table is keyed by the full version and the minor is derived.+TORCH_VERSIONS = ("2.13.0", "2.14.0")++# cp313 is the default and the only one the dispatch defaults to, because each extra+# interpreter is a whole extra flash-attn build. 3.11 and 3.12 are here so a run can add them+# as separate cells when the queue can afford it. 3.14 is deliberately absent: torch publishes+# a cu130 wheel for it, but nothing in the Unsloth stack is tested on 3.14 yet.+PYTHON_VERSIONS = ("3.11", "3.12", "3.13")++DEFAULT_PACKAGES = tuple(SPECS)+DEFAULT_TORCH = TORCH_VERSIONS+DEFAULT_PYTHON = ("3.13",)+++def torch_minor(torch_version: str) -> str:+ """2.13.0 -> 2.13. The local version segment carries the minor and nothing finer."""+ major, minor = torch_version.split(".")[:2]+ return f"{major}.{minor}"+++def python_tag(python_version: str) -> str:+ """3.13 -> cp313."""+ major, minor = python_version.split(".")[:2]+ return f"cp{major}{minor}"+++def local_version(torch_version: str) -> str:+ """The `+cu13torch2.13cxx11abiTRUE` segment, byte for byte as upstream writes it."""+ return f"+cu{CUDA_TAG}torch{torch_minor(torch_version)}cxx11abi{CXX11_ABI}"+++def wheel_name(package: str, torch_version: str, python_version: str) -> str:+ """The published filename for one cell.++ This is the whole point of the local version segment: pip refuses to install a wheel whose+ local version does not match what was requested, and a direct URL install of+ `...torch2.13...` into a torch 2.14 environment is a mistake the filename can prevent and+ an `undefined symbol` traceback at import time cannot.+ """+ spec = SPECS[package]+ tag = python_tag(python_version)+ return (+ f"{spec['dist']}-{spec['version']}{local_version(torch_version)}"+ f"-{tag}-{tag}-{PLATFORM_TAG}.whl"+ )+++def _split(raw: str) -> list[str]:+ return [item.strip() for item in raw.replace("\n", ",").split(",") if item.strip()]+++def _resolve(raw: str, allowed, default, label: str) -> list[str]:+ """Free text in, allowlisted constants out, in the order the allowlist declares them.++ Order matters for more than tidiness: the matrix is emitted in this order and GitHub+ dispatches cells in it, so the longest build in the set starts first rather than last.+ """+ wanted = _split(raw) or list(default)+ unknown = [item for item in wanted if item not in allowed]+ if unknown:+ raise SystemExit(+ f"unknown {label}: {', '.join(sorted(unknown))}. " f"Allowed: {', '.join(allowed)}."+ )+ return [item for item in allowed if item in wanted]+++def build_matrix(+ packages: str = "",+ torches: str = "",+ pythons: str = "",+) -> list[dict]:+ chosen_packages = _resolve(packages, DEFAULT_PACKAGES, DEFAULT_PACKAGES, "package")+ chosen_torch = _resolve(torches, TORCH_VERSIONS, DEFAULT_TORCH, "torch version")+ chosen_python = _resolve(pythons, PYTHON_VERSIONS, DEFAULT_PYTHON, "python version")++ include = []+ for torch_version in chosen_torch:+ for python_version in chosen_python:+ for package in chosen_packages:+ spec = SPECS[package]+ include.append(+ {+ "package": package,+ "dist": spec["dist"],+ "version": spec["version"],+ "repo": spec["repo"],+ "ref": spec["ref"],+ "submodules": "recursive" if spec["submodules"] else "false",+ "patch": spec.get("patch", ""),+ "torch": torch_version,+ "torch_mm": torch_minor(torch_version),+ "python": python_version,+ "python_tag": python_tag(python_version),+ "cuda_tag": CUDA_TAG,+ "abi": CXX11_ABI,+ "max_jobs": spec["max_jobs"],+ "nvcc_threads": spec["nvcc_threads"],+ "build_timeout": spec["build_timeout"],+ "build_env": " ".join(+ f"{key}={value}" for key, value in spec["env"].items()+ ),+ "import_names": " ".join(spec["import_names"]),+ "wheel_name": wheel_name(package, torch_version, python_version),+ # Only used for the job name in the Actions UI, where "flash-attn /+ # torch 2.13 / cp313" is the difference between reading the matrix and+ # counting the cells.+ "label": f"{package} / torch {torch_minor(torch_version)} / "+ f"{python_tag(python_version)}",+ }+ )+ return include+++def parse_wheel_name(name: str) -> dict | None:+ """Filename back to the facts the notes table needs, or None if it is not one of ours.++ Deliberately strict. The release holds SHA256SUMS and .sigstore.json bundles beside the+ wheels, and a loose parse would put them in the table as packages.+ """+ if not name.endswith(f"-{PLATFORM_TAG}.whl"):+ return None+ stem = name[: -len(f"-{PLATFORM_TAG}.whl")]+ parts = stem.split("-")+ if len(parts) != 4:+ return None+ dist, version_local, tag, abi_tag = parts+ if tag != abi_tag or "+" not in version_local:+ return None+ _, local = version_local.split("+", 1)+ if not local.startswith(f"cu{CUDA_TAG}torch") or "cxx11abi" not in local:+ return None+ torch_part, abi = local[len(f"cu{CUDA_TAG}torch") :].split("cxx11abi", 1)+ package = next((key for key, spec in SPECS.items() if spec["dist"] == dist), None)+ if package is None:+ return None+ return {+ "package": package,+ "dist": dist,+ "version": SPECS[package]["version"],+ "torch": torch_part,+ "cuda": CUDA_TAG,+ "python": tag,+ "abi": abi,+ "name": name,+ }+++NOTES_PREAMBLE = """\+Prebuilt Linux x86_64 CUDA 13 wheels for flash-attn, causal-conv1d and mamba-ssm, built against \+PyTorch 2.13 and 2.14.++### Why these exist++Upstream publishes prebuilt wheels for these three packages, but only against PyTorch 2.10 and \+2.11. Those wheels were ABI compatible through torch 2.12 and stopped being so at 2.13:++- `torch 2.13` changed `c10::impl::cow::materialize_cow_storage` and the signature of \+`c10::cuda::c10_cuda_check_implementation`, so an upstream wheel imports on 2.13 as \+`ImportError: undefined symbol: ...`.+- `torch 2.14` changed it again, so a 2.13 wheel is not usable on 2.14 either.++There is no version of these wheels that covers several torch minors from 2.13 on. Every torch \+minor needs its own build, which is what this release is: one wheel per (package, torch minor, \+interpreter), named so it cannot be installed against the wrong one.++Building them from source instead takes roughly five hours of nvcc for flash-attn alone, needs \+the CUDA toolkit present, and is out of reach on most machines that want to run the result.++### Compatibility++| | |+| --- | --- |+| Platform | Linux x86_64 only |+| CUDA | 13.0 toolkit, `cu13` wheels, usable with any CUDA 13.x runtime |+| PyTorch | exactly the minor in the filename, any patch level of it |+| GPU architectures | sm_80, sm_86, sm_89, sm_90, sm_100, sm_120 |+| C++11 ABI | `TRUE`, matching every PyTorch pip wheel from 2.7 on |+| glibc | 2.35 or newer (built on Ubuntu 22.04) |++sm_86 and sm_89 are covered by the sm_80 cubin, which is forward compatible across the minor \+versions of its major. Newer architectures fall back to the embedded PTX and JIT on first use.++Not covered: Windows, macOS, ROCm, CUDA 12 or earlier, aarch64, and free-threaded interpreters.++### Installing++```+pip install https://github.com/{repo}/releases/download/{tag}/<wheel>+```++The `+cu13torch2.13cxx11abiTRUE` segment in each filename is a PEP 440 local version. pip \+refuses to install a wheel whose local version does not match the environment it was built \+for, so picking the wrong torch is a clean install error rather than an `undefined symbol` \+traceback the first time a kernel is called.++### Verifying++Every wheel is signed with [Sigstore](https://www.sigstore.dev/) through GitHub OIDC, with the \+bundle published beside it as `<wheel>.sigstore.json`, and carries an \+[SLSA build provenance](https://slsa.dev/) attestation.++Sigstore, which proves the wheel was produced by this workflow in this repository:++```+python -m pip install sigstore+python -m sigstore verify identity \\+ --cert-identity "https://github.com/{repo}/.github/workflows/prebuilt-cuda-wheels.yml@refs/heads/main" \\+ --cert-oidc-issuer https://token.actions.githubusercontent.com \\+ --bundle <wheel>.sigstore.json \\+ <wheel>+```++`verify identity` rather than `verify github`, because it takes both the identity and the issuer \+on every sigstore-python version; `verify github` dropped `--cert-oidc-issuer` in 4.0 and takes \+`--repository` and `--ref` instead. Use whichever your installed version accepts.++Build provenance, which reports the exact run, commit and workflow that produced it. Needs \+GitHub CLI 2.49 or newer:++```+gh attestation verify <wheel> --repo {repo}+```++Digests, which is the cheap check and still worth doing:++```+sha256sum -c SHA256SUMS --ignore-missing+```++### Wheels+"""+++def render_notes(entries: list[tuple[str, str]], tag: str, repo: str) -> str:+ """Release body from `(sha256, filename)` pairs.++ Regenerated from the release's current assets on every publish rather than appended to, so+ a second run that adds the torch 2.14 half produces notes describing both halves, and a+ third run that replaces one wheel does not leave the old digest in the table.+ """+ rows = []+ for digest, name in entries:+ parsed = parse_wheel_name(name)+ if parsed is None:+ continue+ rows.append((parsed, digest))+ rows.sort(key = lambda row: (row[0]["torch"], row[0]["python"], row[0]["package"]))++ lines = [NOTES_PREAMBLE.format(repo = repo, tag = tag).rstrip("\n"), ""]+ if not rows:+ lines.append("No wheels are attached to this release yet.")+ return "\n".join(lines) + "\n"++ lines.append("| Wheel | Package | Version | torch | CUDA | Python | C++11 ABI | sha256 |")+ lines.append("| --- | --- | --- | --- | --- | --- | --- | --- |")+ for parsed, digest in rows:+ lines.append(+ "| `{name}` | {package} | {version} | {torch} | {cuda} | {python} | {abi} | `{digest}` |".format(+ digest = digest, **parsed+ )+ )+ lines.append("")+ lines.append(+ f"{len(rows)} wheels, each with a `.sigstore.json` bundle beside it. "+ "`SHA256SUMS` lists the same digests in `sha256sum -c` form."+ )+ return "\n".join(lines) + "\n"+++def _cmd_matrix(args: argparse.Namespace) -> int:+ include = build_matrix(+ packages = os.environ.get("UW_PACKAGES", ""),+ torches = os.environ.get("UW_TORCH_VERSIONS", ""),+ pythons = os.environ.get("UW_PYTHON_VERSIONS", ""),+ )+ matrix = json.dumps({"include": include}, separators = (",", ":"))+ print(matrix)++ # Writing the step output here rather than echoing it in YAML keeps the JSON -- which is+ # full of quotes and braces -- out of a shell round trip entirely.+ if args.github:+ output = os.environ.get("GITHUB_OUTPUT")+ if output:+ with open(output, "a", encoding = "utf-8") as handle:+ handle.write(f"matrix={matrix}\n")+ handle.write(f"count={len(include)}\n")+ summary = os.environ.get("GITHUB_STEP_SUMMARY")+ if summary:+ listing = "\n".join(f"- `{cell['wheel_name']}`" for cell in include)+ with open(summary, "a", encoding = "utf-8") as handle:+ handle.write(f"### Build plan\n\n{len(include)} cells:\n\n{listing}\n")+ return 0+++def _cmd_wheel_name(args: argparse.Namespace) -> int:+ if args.package not in SPECS:+ raise SystemExit(f"unknown package: {args.package}")+ if args.torch not in TORCH_VERSIONS:+ raise SystemExit(f"unknown torch version: {args.torch}")+ if args.python not in PYTHON_VERSIONS:+ raise SystemExit(f"unknown python version: {args.python}")+ print(wheel_name(args.package, args.torch, args.python))+ return 0+++def _cmd_notes(args: argparse.Namespace) -> int:+ entries = []+ for line in sys.stdin:+ line = line.strip()+ if not line:+ continue+ digest, _, name = line.partition(" ")+ if not name:+ digest, _, name = line.partition(" ")+ entries.append((digest.strip(), name.strip().lstrip("*")))+ sys.stdout.write(render_notes(entries, tag = args.tag, repo = args.repo))+ return 0+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description = __doc__.splitlines()[0])+ sub = parser.add_subparsers(dest = "command", required = True)++ matrix_parser = sub.add_parser("matrix", help = "print the build matrix as JSON")+ matrix_parser.add_argument(+ "--github",+ action = "store_true",+ help = "also append matrix/count to $GITHUB_OUTPUT and a listing to $GITHUB_STEP_SUMMARY",+ )+ matrix_parser.set_defaults(func = _cmd_matrix)++ name_parser = sub.add_parser("wheel-name", help = "print the filename for one cell")+ name_parser.add_argument("--package", required = True)+ name_parser.add_argument("--torch", required = True)+ name_parser.add_argument("--python", required = True)+ name_parser.set_defaults(func = _cmd_wheel_name)++ notes_parser = sub.add_parser("notes", help = "print the release body, digests on stdin")+ notes_parser.add_argument("--tag", required = True)+ notes_parser.add_argument("--repo", required = True)+ notes_parser.set_defaults(func = _cmd_notes)++ args = parser.parse_args(argv)+ return args.func(args)+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/.github/scripts/prebuilt_wheels_forward.py b/.github/scripts/prebuilt_wheels_forward.pynew file mode 100644index 00000000000..8e68d33af7f--- /dev/null+++ b/.github/scripts/prebuilt_wheels_forward.py@@ -0,0 +1,132 @@+#!/usr/bin/env python3+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Run one real kernel from a freshly installed prebuilt wheel, on a real GPU.++The import gate in prebuilt-cuda-wheels.yml runs on a CPU runner and catches the failure this+whole release exists to avoid: a wheel built against the wrong torch resolves no symbols at+dlopen time and dies with `undefined symbol`. This catches the next one along, which an import+cannot: a wheel that loads fine but carries no cubin the card can run, and fails at the first+launch with `no kernel image is available for execution on the device`.++So the assertions here are about the kernel executing and producing finite numbers, not about+numerical quality -- that is upstream's test suite's job, and it is not what a wheel build can+regress. flash-attn is additionally compared against SDPA, because it is the one of the three+with a cheap reference implementation already in torch.++Usage: prebuilt_wheels_forward.py <flash-attn|causal-conv1d|mamba-ssm>+"""++from __future__ import annotations++import sys++import torch+++def _device() -> str:+ if not torch.cuda.is_available():+ raise SystemExit("::error::no CUDA device visible; this script must run on a GPU runner")+ name = torch.cuda.get_device_name(0)+ capability = torch.cuda.get_device_capability(0)+ print(+ f"torch {torch.__version__}, CUDA {torch.version.cuda}, {name} sm_{capability[0]}{capability[1]}"+ )+ return "cuda"+++def check_flash_attn(device: str) -> None:+ import flash_attn+ from flash_attn import flash_attn_func++ print("flash_attn", flash_attn.__version__)+ batch, seq, heads, dim = 2, 256, 8, 64+ shape = (batch, seq, heads, dim)+ query, key, value = (+ torch.randn(shape, device = device, dtype = torch.bfloat16, requires_grad = True)+ for _ in range(3)+ )+ out = flash_attn_func(query, key, value, causal = True)+ assert out.shape == shape, out.shape+ assert torch.isfinite(out).all(), "flash_attn forward produced non-finite values"++ out.float().pow(2).mean().backward()+ for name, tensor in (("q", query), ("k", key), ("v", value)):+ assert tensor.grad is not None, f"no gradient for {name}"+ assert torch.isfinite(tensor.grad).all(), f"non-finite gradient for {name}"++ reference = torch.nn.functional.scaled_dot_product_attention(+ *(tensor.detach().transpose(1, 2).float() for tensor in (query, key, value)),+ is_causal = True,+ ).transpose(1, 2)+ error = (out.float() - reference).abs().max().item()+ print(f" max abs error against SDPA: {error:.4f}")+ # bf16 accumulation, not a tolerance anyone should tighten: the point is that the kernel+ # computed attention rather than returning plausible-looking garbage.+ assert error < 0.1, error+++def check_causal_conv1d(device: str) -> None:+ import causal_conv1d+ from causal_conv1d import causal_conv1d_fn++ print("causal_conv1d", getattr(causal_conv1d, "__version__", "unknown"))+ batch, channels, length, width = 2, 64, 128, 4+ x = torch.randn(batch, channels, length, device = device, dtype = torch.bfloat16)+ weight = torch.randn(channels, width, device = device, dtype = torch.bfloat16)+ bias = torch.randn(channels, device = device, dtype = torch.bfloat16)+ out = causal_conv1d_fn(x, weight, bias, activation = "silu")+ assert out.shape == (batch, channels, length), out.shape+ assert torch.isfinite(out).all(), "causal_conv1d produced non-finite values"+ print(f" out {tuple(out.shape)} mean {out.float().mean().item():.6f}")+++def check_mamba_ssm(device: str) -> None:+ import mamba_ssm+ from mamba_ssm.ops.selective_scan_interface import selective_scan_fn++ # Imported for its own sake: this is the extension torch 2.13 stopped loading, and the one+ # the C++20 patch exists for. Importing mamba_ssm alone does not prove it is present.+ import selective_scan_cuda++ print("mamba_ssm", mamba_ssm.__version__, selective_scan_cuda.__file__)+ batch, dim, length, state = 2, 64, 128, 16+ u = torch.randn(batch, dim, length, device = device, requires_grad = True)+ delta = torch.rand(batch, dim, length, device = device, requires_grad = True)+ a = (-torch.rand(dim, state, device = device)).detach().clone().requires_grad_(True)+ b = torch.randn(batch, 1, state, length, device = device, requires_grad = True)+ c = torch.randn(batch, 1, state, length, device = device, requires_grad = True)+ d = torch.randn(dim, device = device, requires_grad = True)++ out = selective_scan_fn(u, delta, a, b, c, d, delta_softplus = True)+ if isinstance(out, tuple):+ out = out[0]+ assert out.shape == (batch, dim, length), out.shape+ assert torch.isfinite(out).all(), "selective_scan produced non-finite values"++ out.float().pow(2).mean().backward()+ assert u.grad is not None and torch.isfinite(u.grad).all(), "non-finite gradient for u"+ print(f" out {tuple(out.shape)} grad_u_norm {u.grad.float().norm().item():.6f}")+++CHECKS = {+ "flash-attn": check_flash_attn,+ "causal-conv1d": check_causal_conv1d,+ "mamba-ssm": check_mamba_ssm,+}+++def main(argv: list[str]) -> int:+ if len(argv) != 2 or argv[1] not in CHECKS:+ print(f"usage: prebuilt_wheels_forward.py <{'|'.join(CHECKS)}>", file = sys.stderr)+ return 2+ package = argv[1]+ torch.manual_seed(0)+ CHECKS[package](_device())+ print(f"{package}: forward pass ok")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main(sys.argv))diff --git a/.github/workflows/prebuilt-cuda-wheels.yml b/.github/workflows/prebuilt-cuda-wheels.ymlnew file mode 100644index 00000000000..dfd360fde24--- /dev/null+++ b/.github/workflows/prebuilt-cuda-wheels.yml@@ -0,0 +1,571 @@+# Prebuilt CUDA 13 wheels for flash-attn, causal-conv1d and mamba-ssm, for the torch minors+# nobody else builds them for.+#+# Upstream publishes prebuilt wheels against torch 2.10 and 2.11. Those load on 2.12 -- measured,+# see the comment on _PREBUILT_WHEEL_TORCH_MM in studio/backend/utils/wheel_utils.py -- and stop+# loading at 2.13, because 2.13 changed c10::impl::cow::materialize_cow_storage and the signature+# of c10::cuda::c10_cuda_check_implementation. 2.14 changed it again. An upstream wheel on either+# is an `ImportError: undefined symbol` at import time, and the fallback is a source build: about+# five hours of nvcc for flash-attn, on a machine that has to have the CUDA toolkit installed.+# So every torch minor from 2.13 on needs its own wheel set, and this is where they come from.+#+# Dispatch only, once per torch minor, and `publish: false` is the default: a run then builds,+# smoke tests and signs, and leaves everything as artifacts to inspect. Nothing here is reachable+# from a pull request, because the publish job writes a release under our name.+#+# What is signed and how, in the same shape release-desktop.yml and woa-wheelhouse.yml sign their+# binaries: a `release-signing` environment so the job is gateable, and no key material we own.+# For a Python wheel the mechanism is Sigstore rather than Authenticode -- a .whl is a zip and has+# no Authenticode subject interface package, and unlike the win_arm64 wheelhouse there are no PE+# images inside these to sign individually. Sigstore signs with an ephemeral, GitHub-OIDC-issued+# certificate, so what a consumer verifies is "this workflow, in this repository, produced this+# file", which is the claim worth making and needs no long-lived private key to make it.+name: Prebuilt CUDA wheels++on:+ workflow_dispatch:+ inputs:+ torch_versions:+ description: 'torch versions to build for, comma separated (2.13.0, 2.14.0)'+ type: string+ default: '2.13.0,2.14.0'+ python_versions:+ description: 'interpreters, comma separated (3.11, 3.12, 3.13). Each one is a full extra build'+ type: string+ default: '3.13'+ packages:+ description: 'packages, comma separated (flash-attn, causal-conv1d, mamba-ssm)'+ type: string+ default: 'flash-attn,causal-conv1d,mamba-ssm'+ release_tag:+ description: 'release tag to publish under'+ type: string+ default: 'prebuilt-wheels-cu13'+ publish:+ description: 'upload to the release (otherwise artifacts only)'+ type: boolean+ default: false+ draft:+ description: 'keep the release a draft (unpublished, visible to maintainers only)'+ type: boolean+ default: true+ gpu_smoke:+ description: 'also run a real forward pass on the self-hosted GPU runner (slow, optional)'+ type: boolean+ default: false++permissions:+ contents: read++concurrency:+ # Per repository, not per ref. Two runs would fight over the same release tag and the same+ # self-hosted GPU runner, and a wheel build is too expensive to cancel a running one for a+ # newer dispatch, so they queue instead.+ group: prebuilt-cuda-wheels-${{ github.repository }}+ cancel-in-progress: false++jobs:+ plan:+ name: Plan the matrix+ runs-on: ubuntu-latest+ timeout-minutes: 10+ outputs:+ matrix: ${{ steps.plan.outputs.matrix }}+ count: ${{ steps.plan.outputs.count }}+ steps:+ - name: Harden runner (egress block)+ uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1+ with:+ egress-policy: block+ disable-sudo: true+ allowed-endpoints: >+ api.github.com:443+ github.com:443++ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false++ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.12'++ # Every dispatch input that later reaches a shell command -- the source repository, the+ # git ref, the build environment -- is resolved here against the allowlist in+ # prebuilt_wheels.py, and the raw text is never used again. The workflow is gated, but an+ # input that becomes `git checkout $REF` is a command injection either way.+ - name: Expand the dispatch inputs into a matrix+ id: plan+ env:+ UW_PACKAGES: ${{ inputs.packages }}+ UW_TORCH_VERSIONS: ${{ inputs.torch_versions }}+ UW_PYTHON_VERSIONS: ${{ inputs.python_versions }}+ run: |+ set -euo pipefail+ # --github writes matrix= and count= into $GITHUB_OUTPUT itself. The JSON is full of+ # quotes and braces and there is no reason to send it through a shell round trip.+ python3 .github/scripts/prebuilt_wheels.py matrix --github++ build:+ name: ${{ matrix.label }}+ needs: plan+ if: needs.plan.outputs.count != '0'+ # ubuntu-22.04 deliberately, not ubuntu-latest. These wheels are tagged linux_x86_64, which+ # pip installs without checking glibc, so the runner's glibc IS the compatibility floor: 2.35+ # here against 2.39 on 24.04. Upstream builds its own wheels on 22.04 for the same reason.+ runs-on: ubuntu-22.04+ # flash-attn is ~4.5 h of nvcc at MAX_JOBS=1. GitHub's hard job limit is 6 h and a job that+ # hits it is reported as "cancelled" with no logs kept, so the build step carries its own+ # shorter `timeout` and this sits just above it.+ timeout-minutes: 340+ permissions:+ contents: read+ strategy:+ fail-fast: false+ # One cell at a time would be safe and would also take a week. Five is what the free+ # runner pool serves without pushing every other workflow in the org behind it.+ max-parallel: 5+ matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}+ steps:+ - name: Harden runner (audit)+ # Audit, not block. This job talks to the apt CUDA repository, PyPI, the PyTorch wheel+ # index and two upstream GitHub repositories, and a blocklist tuned on one of those+ # moving would fail a four-hour build at the last step.+ uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1+ with:+ egress-policy: audit++ - name: Checkout Unsloth (build scripts only)+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ path: unsloth+ persist-credentials: false+ sparse-checkout: |+ .github/scripts+ sparse-checkout-cone-mode: false++ - name: Checkout ${{ matrix.repo }}+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ repository: ${{ matrix.repo }}+ ref: ${{ matrix.ref }}+ path: src+ submodules: ${{ matrix.submodules }}+ persist-credentials: false++ # The CUDA toolkit is ~4 GB installed and the flash-attn build tree is another few, against+ # ~25 GB free on a fresh runner. These three directories are ~13 GB of preinstalled+ # toolchains this job never touches.+ - name: Free up disk space+ run: |+ set -euo pipefail+ df -h /+ sudo rm -rf /usr/share/dotnet /opt/ghc /opt/hostedtoolcache/CodeQL /usr/local/lib/android || true+ df -h /++ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: ${{ matrix.python }}++ # From NVIDIA's apt repository rather than a third-party setup action: this job installs a+ # compiler that then produces binaries we sign and publish, so the fewer parties between+ # NVIDIA and nvcc the better. Bounded and retried through the same helper the rest of the+ # repository uses, because an unbounded apt step does not fail, it spends the job's whole+ # budget and is reported as "cancelled" with every later step skipped.+ - name: Install the CUDA ${{ matrix.cuda_tag }} toolkit+ timeout-minutes: 25+ env:+ RETRY_ATTEMPTS: '2'+ RETRY_ATTEMPT_TIMEOUT: '600'+ run: |+ set -euo pipefail+ keyring=cuda-keyring_1.1-1_all.deb+ curl --fail --silent --show-error --location --retry 5 --retry-delay 5 \+ -o "$keyring" \+ "https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/$keyring"+ sudo dpkg -i "$keyring"+ bash unsloth/.github/scripts/retry-with-apt-lock.sh sudo sh -c \+ 'apt-get update && apt-get install -y --no-install-recommends cuda-toolkit-13-0'+ echo "/usr/local/cuda-13.0/bin" >> "$GITHUB_PATH"+ echo "CUDA_HOME=/usr/local/cuda-13.0" >> "$GITHUB_ENV"++ # 10 GB of swap. nvcc's peak RSS on the sm_100 flash-attn kernels is the reason MAX_JOBS is+ # 1; swap is what keeps a single job that briefly exceeds the runner's 16 GB from being+ # OOM-killed four hours in.+ - name: Set up swap space+ run: |+ set -euo pipefail+ sudo fallocate -l 10G /mnt/swapfile+ sudo chmod 600 /mnt/swapfile+ sudo mkswap /mnt/swapfile+ sudo swapon /mnt/swapfile+ free -h++ - name: Install torch ${{ matrix.torch }}+cu130+ run: |+ set -euo pipefail+ python -m pip install --upgrade pip+ python -m pip install 'setuptools>=77' wheel ninja packaging+ python -m pip install --no-cache-dir "torch==${{ matrix.torch }}" \+ --index-url https://download.pytorch.org/whl/cu130+ nvcc --version+ python -c "import torch; print('torch', torch.__version__, 'cuda', torch.version.cuda, 'cxx11abi', torch._C._GLIBCXX_USE_CXX11_ABI)"+ python - <<'PY'+ import os, sys, torch+ want_torch = os.environ["MATRIX_TORCH"]+ if torch.__version__.split("+")[0] != want_torch:+ sys.exit(f"installed torch {torch.__version__}, wanted {want_torch}")+ if not torch.version.cuda.startswith("13."):+ sys.exit(f"torch reports CUDA {torch.version.cuda}, wanted 13.x")+ # The wheel filename claims cxx11abiTRUE. If torch ever ships abiFALSE wheels again the+ # name would be a lie, and a lie in a filename is worse than a failure here.+ if not torch._C._GLIBCXX_USE_CXX11_ABI:+ sys.exit("torch was built with _GLIBCXX_USE_CXX11_ABI=0; the cxx11abiTRUE tag would be wrong")+ PY+ env:+ MATRIX_TORCH: ${{ matrix.torch }}++ # The one source edit in this workflow, and only for mamba-ssm. Its setup.py compiles the+ # Mamba-1 selective-scan kernels at -std=c++17; torch 2.13's headers require C++20, and+ # nvcc stops at the first std::variant it cannot parse. flash-attn already made this change+ # upstream (Dao-AILab/flash-attention#2899), which is part of why its pin is a commit and+ # not the last tag. The script asserts on the text it replaces, so an upstream fix fails+ # this step loudly rather than silently building something else.+ - name: Patch mamba-ssm for the torch 2.13 C++20 requirement+ if: matrix.patch == 'cxx20'+ run: python3 unsloth/.github/scripts/patch_mamba_cxx20.py src/setup.py++ - name: Build the wheel+ id: build+ working-directory: src+ env:+ MAX_JOBS: ${{ matrix.max_jobs }}+ NVCC_THREADS: ${{ matrix.nvcc_threads }}+ BUILD_ENV: ${{ matrix.build_env }}+ BUILD_TIMEOUT: ${{ matrix.build_timeout }}+ run: |+ set -euo pipefail+ # Each entry is NAME=VALUE from the allowlisted table in prebuilt_wheels.py, so this is+ # exporting constants, not dispatch input.+ for pair in $BUILD_ENV; do+ export "${pair?}"+ echo "export $pair"+ done+ echo "MAX_JOBS=$MAX_JOBS NVCC_THREADS=$NVCC_THREADS timeout=$BUILD_TIMEOUT"+ timeout --signal=INT --kill-after=120 "$BUILD_TIMEOUT" \+ python setup.py bdist_wheel --dist-dir=dist++ # Upstream's own naming, reproduced rather than approximated: the local version segment is+ # what stops pip installing a torch 2.13 wheel into a torch 2.14 environment. Asserting the+ # pre-rename name first is what makes it honest -- it proves the version that was BUILT is+ # the version the published name claims, rather than renaming whatever fell out of dist/.+ - name: Name the wheel the way upstream names it+ working-directory: src+ env:+ DIST: ${{ matrix.dist }}+ VERSION: ${{ matrix.version }}+ PYTHON_TAG: ${{ matrix.python_tag }}+ WHEEL_NAME: ${{ matrix.wheel_name }}+ run: |+ set -euo pipefail+ built="$(ls dist/*.whl)"+ expected_raw="dist/${DIST}-${VERSION}-${PYTHON_TAG}-${PYTHON_TAG}-linux_x86_64.whl"+ if [ "$built" != "$expected_raw" ]; then+ echo "::error::built $built, expected $expected_raw before renaming"+ exit 1+ fi+ mv "$built" "dist/${WHEEL_NAME}"+ ls -l dist/++ # The whole reason this release exists, so it is a gate and not a report. A fresh venv with+ # the matching torch, the wheel installed from the file, and the compiled extension+ # imported out of process. An upstream wheel on torch 2.13 dies exactly here, with+ # `undefined symbol: _ZN3c104impl3cow21materialize_cow_storageERNS_11StorageImplE`, and a+ # wheel of ours that is built against the wrong torch would die the same way.+ #+ # No GPU on this runner, and none needed: importing a torch C++ extension resolves every+ # symbol against libtorch and libc10 at dlopen time, which is the entire failure mode. The+ # tiny forward pass is the gpu-smoke job below.+ - name: Smoke test the wheel in a fresh venv+ env:+ WHEEL_NAME: ${{ matrix.wheel_name }}+ IMPORT_NAMES: ${{ matrix.import_names }}+ MATRIX_TORCH: ${{ matrix.torch }}+ run: |+ set -euo pipefail+ python -m venv "$RUNNER_TEMP/smoke"+ "$RUNNER_TEMP/smoke/bin/python" -m pip install --quiet --upgrade pip+ "$RUNNER_TEMP/smoke/bin/python" -m pip install --quiet --no-cache-dir \+ "torch==${MATRIX_TORCH}" --index-url https://download.pytorch.org/whl/cu130+ # --no-deps: causal-conv1d and mamba-ssm declare each other and transformers, none of+ # which has anything to do with whether this .so loads, and all of which would drag a+ # second torch resolution into the venv.+ "$RUNNER_TEMP/smoke/bin/python" -m pip install --quiet --no-deps \+ "src/dist/${WHEEL_NAME}"+ for name in $IMPORT_NAMES; do+ echo "importing $name"+ "$RUNNER_TEMP/smoke/bin/python" -c "+ import importlib, sys, torch+ module = importlib.import_module('$name')+ print(' ok:', '$name', getattr(module, '__version__', ''), getattr(module, '__file__', ''))+ "+ done+ "$RUNNER_TEMP/smoke/bin/python" -m pip list | grep -Ei 'torch|flash|mamba|causal'++ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: wheel-${{ matrix.dist }}-torch${{ matrix.torch_mm }}-${{ matrix.python_tag }}+ path: src/dist/${{ matrix.wheel_name }}+ if-no-files-found: error+ # Already a compressed zip. Recompressing 500 MB of it buys nothing and costs minutes.+ compression-level: 0+ retention-days: 7++ # Optional, off by default, and the only job that touches a GPU. The import gate above catches+ # the ABI failure this release exists to avoid; this catches the rarer one where the wheel+ # imports but carries no cubin the card can run. It is a separate job because the build runners+ # have no GPU and the self-hosted one is shared with the Docker smoke tests.+ gpu-smoke:+ name: GPU forward pass+ needs: [plan, build]+ if: inputs.gpu_smoke+ runs-on: [self-hosted, gpu]+ timeout-minutes: 90+ permissions:+ contents: read+ strategy:+ fail-fast: false+ max-parallel: 1+ matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false+ sparse-checkout: |+ .github/scripts+ sparse-checkout-cone-mode: false++ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1+ with:+ name: wheel-${{ matrix.dist }}-torch${{ matrix.torch_mm }}-${{ matrix.python_tag }}+ path: dist++ - name: Forward pass on the real card+ env:+ WHEEL_NAME: ${{ matrix.wheel_name }}+ MATRIX_TORCH: ${{ matrix.torch }}+ PACKAGE: ${{ matrix.package }}+ run: |+ set -euo pipefail+ nvidia-smi+ rm -rf gpu-smoke-venv+ "python${{ matrix.python }}" -m venv gpu-smoke-venv+ ./gpu-smoke-venv/bin/python -m pip install --quiet --upgrade pip+ ./gpu-smoke-venv/bin/python -m pip install --quiet --no-cache-dir \+ "torch==${MATRIX_TORCH}" --index-url https://download.pytorch.org/whl/cu130+ ./gpu-smoke-venv/bin/python -m pip install --quiet --no-deps "dist/${WHEEL_NAME}"+ ./gpu-smoke-venv/bin/python .github/scripts/prebuilt_wheels_forward.py "$PACKAGE"++ sign:+ name: Sign and attest+ needs: [plan, build]+ runs-on: ubuntu-latest+ timeout-minutes: 45+ # Named for the same reason release-desktop.yml and woa-wheelhouse.yml name it: it is what+ # makes this job gateable. There are no secrets to scope here -- Sigstore uses an ephemeral+ # certificate issued against the run's OIDC token, which is the point of choosing it -- but+ # the identity that certificate binds to is ours, so approval belongs in front of it.+ environment: release-signing+ permissions:+ # The OIDC token Sigstore and the attestation both exchange for a short-lived certificate.+ id-token: write+ # actions/attest-build-provenance writes the attestation to the repository's attestation+ # store. It is NOT contents: write; nothing in this job can touch a release.+ attestations: write+ contents: read+ steps:+ - name: Harden runner (audit)+ uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1+ with:+ egress-policy: audit++ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false++ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.12'++ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1+ with:+ pattern: wheel-*+ merge-multiple: true+ path: wheels++ # A short matrix leg would otherwise publish a set missing an interpreter or a torch minor,+ # which reads downstream as "no wheel for you" and sends the user into a source build. The+ # plan job already counted the cells; this asserts the same number arrived.+ - name: Every planned wheel arrived+ env:+ EXPECTED: ${{ needs.plan.outputs.count }}+ run: |+ set -euo pipefail+ ls -l wheels/+ actual="$(find wheels -name '*.whl' -type f | wc -l)"+ if [ "$actual" -ne "$EXPECTED" ]; then+ echo "::error::expected $EXPECTED wheels, got $actual"+ exit 1+ fi+ echo "$actual wheels"++ - name: SHA256SUMS+ run: |+ set -euo pipefail+ cd wheels+ sha256sum -- *.whl | sort -k2 > SHA256SUMS+ cat SHA256SUMS++ # Sigstore, with a GitHub OIDC identity: no key of ours exists to be stolen, and what a+ # consumer verifies is the workflow ref and the issuer, not a fingerprint they have to have+ # obtained from somewhere trustworthy first. One .sigstore.json bundle per wheel, published+ # beside it.+ - name: Sign every wheel with Sigstore+ uses: sigstore/gh-action-sigstore-python@790bc6befb9d733738f18d8f895854b453640ec9 # v3.5.0+ with:+ inputs: ./wheels/*.whl+ # Verified again immediately, in this job, against the identity the release notes tell+ # consumers to check. A bundle that only verifies with different arguments than the+ # documented ones is a bundle nobody can use.+ verify: true+ verify-cert-identity: https://github.com/${{ github.repository }}/.github/workflows/prebuilt-cuda-wheels.yml@${{ github.ref }}+ verify-oidc-issuer: https://token.actions.githubusercontent.com+ upload-signing-artifacts: false+ # Only meaningful on a `release` event, which this is not. Set anyway so a future+ # trigger change cannot quietly start attaching assets from here.+ release-signing-artifacts: false++ # SLSA provenance, which answers a different question than the signature does: the+ # signature says we produced it, the provenance says which run, which commit and which+ # workflow produced it, and `gh attestation verify` checks it with no extra tooling.+ # subject-checksums takes the whole set in one attestation rather than one per wheel.+ - name: Attest build provenance+ uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2+ with:+ subject-checksums: wheels/SHA256SUMS++ - name: What is about to be published+ run: |+ set -euo pipefail+ ls -l wheels/+ missing=0+ for whl in wheels/*.whl; do+ if [ ! -f "$whl.sigstore.json" ]; then+ echo "::error::no Sigstore bundle for $(basename "$whl")"+ missing=1+ fi+ done+ [ "$missing" -eq 0 ]++ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: prebuilt-cuda-wheels-signed+ path: |+ wheels/*.whl+ wheels/*.sigstore.json+ wheels/SHA256SUMS+ if-no-files-found: error+ compression-level: 0+ retention-days: 7++ publish:+ name: Publish the release+ needs: sign+ if: inputs.publish+ runs-on: ubuntu-latest+ timeout-minutes: 30+ permissions:+ # The only job in this workflow that can write a release, and it builds nothing.+ contents: write+ steps:+ - name: Harden runner (audit)+ uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1+ with:+ egress-policy: audit++ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false++ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.12'++ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1+ with:+ name: prebuilt-cuda-wheels-signed+ path: wheels++ # Created once and then added to. A run for torch 2.14 must not disturb the torch 2.13+ # wheels already on the tag, so: create if absent, upload with --clobber, and regenerate+ # the notes from what the release holds AFTERWARDS rather than from what this run built.+ #+ # --latest=false on both paths. This tag is a wheelhouse, not a product release, and the+ # repository's latest release is what the installers and the README resolve to.+ - name: Create or update the release+ env:+ GH_TOKEN: ${{ github.token }}+ TAG: ${{ inputs.release_tag }}+ DRAFT: ${{ inputs.draft }}+ TITLE: 'Flash-Attention2, Causal-Conv1D, Mamba_SSM Binaries'+ run: |+ set -euo pipefail+ # A draft release has no tag yet, so it is found by listing, not by tag lookup.+ # shellcheck disable=SC2016 # $tag is a jq variable, not a shell one+ existing="$(gh release list --repo "$GITHUB_REPOSITORY" --limit 200 --json tagName \+ --jq --arg tag "$TAG" '.[] | select(.tagName == $tag) | .tagName')"+ if [ -z "$existing" ]; then+ gh release create "$TAG" \+ --repo "$GITHUB_REPOSITORY" \+ --title "$TITLE" \+ --latest=false \+ --draft="$DRAFT" \+ --notes "Prebuilt CUDA 13 wheels. Release notes are regenerated from the attached assets below."+ else+ gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --title "$TITLE" --latest=false --draft="$DRAFT"+ fi+ gh release upload "$TAG" --repo "$GITHUB_REPOSITORY" --clobber \+ wheels/*.whl wheels/*.sigstore.json wheels/SHA256SUMS++ # Regenerated from the release's OWN assets, using the digest GitHub reports per asset+ # rather than the SHA256SUMS this run uploaded. Those agree when nothing went wrong, and+ # when they disagree the table should describe what a user will actually download. It also+ # makes the notes correct after a second run that only added half the matrix.+ - name: Regenerate the release notes from the published assets+ env:+ GH_TOKEN: ${{ github.token }}+ TAG: ${{ inputs.release_tag }}+ DRAFT: ${{ inputs.draft }}+ run: |+ set -euo pipefail+ # Listed rather than looked up by tag: a draft release has no tag object yet.+ # shellcheck disable=SC2016 # $tag is a jq variable, not a shell one+ gh api --paginate "repos/$GITHUB_REPOSITORY/releases?per_page=100" \+ --jq --arg tag "$TAG" '.[] | select(.tag_name == $tag) | .assets[] | select(.name | endswith(".whl")) | "\(.digest // "sha256:unknown" | sub("^sha256:"; "")) \(.name)"' \+ > published.txt+ sort -k2 -o published.txt published.txt+ cat published.txt+ python3 .github/scripts/prebuilt_wheels.py notes \+ --tag "$TAG" --repo "$GITHUB_REPOSITORY" < published.txt > notes.md+ gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --notes-file notes.md --latest=false --draft="$DRAFT"+ cat notes.md >> "$GITHUB_STEP_SUMMARY"++ - name: Report the release URL+ env:+ TAG: ${{ inputs.release_tag }}+ run: |+ set -euo pipefail+ {+ echo+ echo "Published to https://github.com/$GITHUB_REPOSITORY/releases/tag/$TAG"+ } >> "$GITHUB_STEP_SUMMARY"diff --git a/studio/backend/utils/wheel_utils.py b/studio/backend/utils/wheel_utils.pyindex b3ce42e32de..1e296117656 100644--- a/studio/backend/utils/wheel_utils.py+++ b/studio/backend/utils/wheel_utils.py@@ -105,6 +105,55 @@ def prebuilt_wheel_torch_mm(torch_mm: str) -> str:return _PREBUILT_WHEEL_TORCH_MM.get(torch_mm, torch_mm)+# ── Wheels we build ourselves ─────────────────────────────────────────────────+# Upstream stops at torch 2.11 and the reuse window above stops at 2.12, because torch 2.13 broke the extension ABI again -- it changed c10::impl::cow::materialize_cow_storage and the signature of c10::cuda::c10_cuda_check_implementation, so an upstream wheel raises "undefined symbol" at import -- and 2.14 changed it once more. There is no upstream asset to point at and no older one that loads, so from 2.13 on we build the wheels and resolve to our own release. Built by .github/workflows/prebuilt-cuda-wheels.yml, one per (package, torch minor, interpreter), Sigstore-signed, on the tag below.+UNSLOTH_PREBUILT_RELEASE_BASE_URL = "https://github.com/unslothai/unsloth/releases/download"+UNSLOTH_PREBUILT_RELEASE_TAG = "prebuilt-wheels-cu13"++# Keyed on the torch minor, and exact rather than a floor: a wheel is built against one minor and there is no evidence any future one will load it, which is exactly the assumption that made the upstream wheels stop working here. A new torch minor adds a row only after the workflow has built and smoke-tested it.+_UNSLOTH_PREBUILT_TORCH_MM = frozenset({"2.13", "2.14"})++# The package version published on that tag, which is not the version the upstream branches resolve: the builds are newer because they had to be cut from a source revision that compiles against torch 2.13 at all. flash-attn 2.8.4 in particular exists only as a commit upstream, carrying the c++20 switch from Dao-AILab/flash-attention#2899.+_UNSLOTH_PREBUILT_VERSIONS = {+ "flash_attn": "2.8.4",+ "causal_conv1d": "1.7.0",+ "mamba_ssm": "2.3.2.post1",+}+++def unsloth_prebuilt_wheel_url(*, filename_prefix: str, env: dict[str, str] | None) -> str | None:+ """Our own prebuilt wheel for this environment, or None to leave resolution unchanged.++ Every gate here is narrower than it strictly has to be, because the cost of the two answers is not symmetric: returning None costs a source build the user was already facing, and returning a URL for a combination we did not publish costs a 404 and the same source build with a misleading log line in front of it. So it answers only for the exact cells the workflow builds, and the torch minor, CUDA major, ABI, interpreter and platform must all match. Linux x86_64 only: nothing else is built, and Windows, macOS and linux_aarch64 keep whatever behaviour they have today.+ """+ if env is None:+ return None+ if env.get("torch_mm") not in _UNSLOTH_PREBUILT_TORCH_MM:+ return None+ # cu13 only. The workflow builds against the CUDA 13 toolkit and nothing else.+ if env.get("cuda_major") != "13":+ return None+ if env.get("platform_tag") != "linux_x86_64":+ return None+ # Every torch pip wheel from 2.7 on is built with _GLIBCXX_USE_CXX11_ABI=1, so there is no abiFALSE variant to publish. A torch built otherwise -- a source build, an NGC image -- is not something these wheels can serve.+ if env.get("cxx11abi") != "TRUE":+ return None+ python_tag = env.get("python_tag")+ if not python_tag:+ return None+ package_version = _UNSLOTH_PREBUILT_VERSIONS.get(filename_prefix)+ if package_version is None:+ return None++ filename = (+ f"{filename_prefix}-{package_version}"+ f"+cu{env['cuda_major']}torch{env['torch_mm']}"+ f"cxx11abi{env['cxx11abi']}-{python_tag}-{python_tag}"+ f"-{env['platform_tag']}.whl"+ )+ return f"{UNSLOTH_PREBUILT_RELEASE_BASE_URL}/{UNSLOTH_PREBUILT_RELEASE_TAG}/{filename}"++def direct_wheel_url(*,filename_prefix: str,@@ -116,6 +165,11 @@ def direct_wheel_url(if env is None or not env.get("cuda_major"):return None+ # Checked before the upstream filename is built, not after: for torch 2.13+ the upstream URL this would otherwise return names an asset that has never existed, so there is nothing to fall back to and no reason to prefer it. Every caller -- causal-conv1d and mamba-ssm on both the training and the inference path -- picks this up without changing its own arguments, which is why the override lives here rather than at each call site.+ ours = unsloth_prebuilt_wheel_url(filename_prefix = filename_prefix, env = env)+ if ours is not None:+ return ours+filename = (f"{filename_prefix}-{package_version}"f"+cu{env['cuda_major']}torch{prebuilt_wheel_torch_mm(env['torch_mm'])}"@@ -278,6 +332,10 @@ def flash_attn_package_version(torch_mm: str) -> str | None:def flash_attn_wheel_url(env: dict[str, str] | None) -> str | None:if env is None:return None+ # flash-attn does not reach direct_wheel_url on torch 2.13+: flash_attn_package_version returns None there and this function bails before the URL is ever built, so the override has to be asked here too. It is the same predicate and the same table; only the entry point differs.+ ours = unsloth_prebuilt_wheel_url(filename_prefix = "flash_attn", env = env)+ if ours is not None:+ return ourspackage_version = flash_attn_package_version(prebuilt_wheel_torch_mm(env["torch_mm"]))if package_version is None:return Nonediff --git a/tests/python/test_prebuilt_cuda_wheels.py b/tests/python/test_prebuilt_cuda_wheels.pynew file mode 100644index 00000000000..16f3c1ebc1e--- /dev/null+++ b/tests/python/test_prebuilt_cuda_wheels.py@@ -0,0 +1,647 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The wheels we build ourselves, and the resolver that has to find them.++Upstream publishes prebuilt flash-attn / causal-conv1d / mamba-ssm wheels against torch 2.10 and+2.11, reused through 2.12. torch 2.13 broke the extension ABI (materialize_cow_storage, the+c10_cuda_check_implementation signature) and 2.14 broke it again, so from 2.13 on the wheels come+from .github/workflows/prebuilt-cuda-wheels.yml and a release on this repository.++Two halves have to agree for that to work at all, and they live in different languages in+different directories: the workflow decides what a wheel is CALLED, and wheel_utils decides what+the installer ASKS FOR. A disagreement between them is a 404 and a five-hour source build, and+neither half can notice it alone. So the central test here builds the filename both ways for+every cell the workflow can produce and asserts they are the same string.++The rest pins what must not move:++* 2.4 through 2.12 keep resolving to upstream, unchanged, including the 2.11/2.12 reuse;+* the override is Linux x86_64, cu13, cxx11abiTRUE only, so Windows, macOS, aarch64, CUDA 12 and+ a non-C++11-ABI torch keep exactly the behaviour they have today;+* the workflow stays dispatch-only, keeps `contents: write` on the publish job alone, and keeps+ every action pinned to a SHA, because it signs and publishes binaries under our identity.+"""++from __future__ import annotations++import importlib.util+import json+import re+import subprocess+import sys+from pathlib import Path++import pytest+import yaml++REPO = Path(__file__).resolve().parents[2]+WORKFLOW = REPO / ".github" / "workflows" / "prebuilt-cuda-wheels.yml"+SCRIPTS = REPO / ".github" / "scripts"++sys.path.insert(0, str(REPO / "studio"))+sys.path.insert(0, str(REPO / "studio" / "backend"))++from utils import wheel_utils # noqa: E402+++def _load(name: str, path: Path):+ spec = importlib.util.spec_from_file_location(name, path)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++prebuilt_wheels = _load("prebuilt_wheels", SCRIPTS / "prebuilt_wheels.py")+++def env(+ *,+ torch_mm: str = "2.13",+ cuda_major: str = "13",+ cxx11abi: str = "TRUE",+ python_tag: str = "cp313",+ platform_tag: str = "linux_x86_64",+) -> dict[str, str]:+ """The shape probe_torch_wheel_env() returns, with the fields the resolvers read."""+ return {+ "torch_mm": torch_mm,+ "cuda_major": cuda_major,+ "cxx11abi": cxx11abi,+ "python_tag": python_tag,+ "platform_tag": platform_tag,+ "torch_version": f"{torch_mm}.0+cu{cuda_major}0",+ "cuda_version": "13.0",+ }+++OUR_BASE = "https://github.com/unslothai/unsloth/releases/download/prebuilt-wheels-cu13/"+++def triggers(doc: dict) -> dict:+ """PyYAML is YAML 1.1, where a bare `on:` key parses as the boolean True."""+ return doc.get(True) if True in doc else doc.get("on")+++# ── The two halves agree ──────────────────────────────────────────────────────+++class TestWorkflowAndResolverAgree:+ def test_every_cell_the_workflow_builds_is_what_the_resolver_asks_for(self):+ """The one test this whole file exists for.++ The workflow renames its build output to prebuilt_wheels.wheel_name(...); the installer+ downloads the basename of unsloth_prebuilt_wheel_url(...). Nothing else checks that+ those are the same string, and if they ever differ the symptom is a 404 on a user's+ machine rather than a red run here.+ """+ checked = 0+ for package, spec in prebuilt_wheels.SPECS.items():+ for torch_version in prebuilt_wheels.TORCH_VERSIONS:+ for python_version in prebuilt_wheels.PYTHON_VERSIONS:+ built = prebuilt_wheels.wheel_name(package, torch_version, python_version)+ url = wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = spec["dist"],+ env = env(+ torch_mm = prebuilt_wheels.torch_minor(torch_version),+ python_tag = prebuilt_wheels.python_tag(python_version),+ ),+ )+ assert url is not None, (package, torch_version, python_version)+ assert url.rsplit("/", 1)[1] == built+ assert url.startswith(OUR_BASE)+ checked += 1+ # 3 packages x 2 torch minors x 3 interpreters. A silently emptied table would+ # otherwise pass this class without asserting anything.+ assert checked == 18++ def test_the_versions_published_are_the_versions_resolved(self):+ for package, spec in prebuilt_wheels.SPECS.items():+ assert wheel_utils._UNSLOTH_PREBUILT_VERSIONS[spec["dist"]] == spec["version"], package++ def test_the_two_torch_tables_are_the_same_set(self):+ built = {prebuilt_wheels.torch_minor(version) for version in prebuilt_wheels.TORCH_VERSIONS}+ assert built == set(wheel_utils._UNSLOTH_PREBUILT_TORCH_MM)++ def test_the_release_tag_the_workflow_defaults_to_is_the_one_we_resolve(self):+ workflow = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))+ default = triggers(workflow)["workflow_dispatch"]["inputs"]["release_tag"]["default"]+ assert default == wheel_utils.UNSLOTH_PREBUILT_RELEASE_TAG+++# ── The override fires exactly where it should ────────────────────────────────+++class TestOverrideScope:+ @pytest.mark.parametrize("torch_mm", ["2.13", "2.14"])+ @pytest.mark.parametrize(+ "prefix,version",+ [("flash_attn", "2.8.4"), ("causal_conv1d", "1.7.0"), ("mamba_ssm", "2.3.2.post1")],+ )+ def test_exact_url(self, torch_mm, prefix, version):+ url = wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = prefix, env = env(torch_mm = torch_mm)+ )+ assert url == (+ f"{OUR_BASE}{prefix}-{version}+cu13torch{torch_mm}"+ "cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"+ )++ @pytest.mark.parametrize("torch_mm", ["2.4", "2.9", "2.10", "2.11", "2.12", "2.15", "3.0"])+ def test_other_torch_minors_are_not_ours(self, torch_mm):+ assert (+ wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = "flash_attn", env = env(torch_mm = torch_mm)+ )+ is None+ )++ @pytest.mark.parametrize("platform_tag", ["linux_aarch64", "win_amd64", "macosx_11_0_arm64"])+ def test_only_linux_x86_64(self, platform_tag):+ assert (+ wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = "mamba_ssm", env = env(platform_tag = platform_tag)+ )+ is None+ )++ @pytest.mark.parametrize("cuda_major", ["11", "12", "14", ""])+ def test_only_cuda_13(self, cuda_major):+ assert (+ wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = "mamba_ssm", env = env(cuda_major = cuda_major)+ )+ is None+ )++ def test_only_cxx11_abi_true(self):+ assert (+ wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = "flash_attn", env = env(cxx11abi = "FALSE")+ )+ is None+ )++ def test_unknown_package_is_not_ours(self):+ assert wheel_utils.unsloth_prebuilt_wheel_url(filename_prefix = "xformers", env = env()) is None++ def test_no_env_is_not_ours(self):+ assert (+ wheel_utils.unsloth_prebuilt_wheel_url(filename_prefix = "flash_attn", env = None) is None+ )++ @pytest.mark.parametrize("python_tag", ["cp311", "cp312", "cp313"])+ def test_every_interpreter_we_build(self, python_tag):+ url = wheel_utils.unsloth_prebuilt_wheel_url(+ filename_prefix = "flash_attn", env = env(python_tag = python_tag)+ )+ assert url is not None and f"-{python_tag}-{python_tag}-" in url+++# ── Nothing that worked before changed ────────────────────────────────────────+++class TestBackwardsCompatible:+ def test_torch_210_still_resolves_upstream_flash_attn(self):+ url = wheel_utils.flash_attn_wheel_url(env(torch_mm = "2.10"))+ assert url == (+ "https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.1/"+ "flash_attn-2.8.1+cu13torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"+ )++ @pytest.mark.parametrize("torch_mm", ["2.11", "2.12"])+ def test_the_torch210_reuse_window_is_untouched(self, torch_mm):+ assert wheel_utils.prebuilt_wheel_torch_mm(torch_mm) == "2.10"+ url = wheel_utils.flash_attn_wheel_url(env(torch_mm = torch_mm))+ assert "torch2.10" in url+ assert "Dao-AILab" in url++ def test_torch_29_still_resolves_upstream(self):+ url = wheel_utils.flash_attn_wheel_url(env(torch_mm = "2.9"))+ assert "Dao-AILab/flash-attention/releases/download/v2.8.3/" in url+ assert "torch2.9" in url++ def test_upstream_causal_conv1d_url_is_unchanged_on_212(self):+ url = wheel_utils.direct_wheel_url(+ filename_prefix = "causal_conv1d",+ package_version = "1.6.1",+ release_tag = "v1.6.1.post4",+ release_base_url = "https://github.com/Dao-AILab/causal-conv1d/releases/download",+ env = env(torch_mm = "2.12"),+ )+ assert url == (+ "https://github.com/Dao-AILab/causal-conv1d/releases/download/v1.6.1.post4/"+ "causal_conv1d-1.6.1+cu13torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"+ )++ def test_213_takes_over_the_same_call(self):+ """Same call site, same arguments, different answer only for the new minors."""+ url = wheel_utils.direct_wheel_url(+ filename_prefix = "causal_conv1d",+ package_version = "1.6.1",+ release_tag = "v1.6.1.post4",+ release_base_url = "https://github.com/Dao-AILab/causal-conv1d/releases/download",+ env = env(torch_mm = "2.13"),+ )+ assert (+ url+ == f"{OUR_BASE}causal_conv1d-1.7.0+cu13torch2.13cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"+ )++ def test_a_windows_env_still_reaches_upstream_for_a_non_our_package(self):+ """The override must not become a Windows gate for anything else that uses this path."""+ url = wheel_utils.direct_wheel_url(+ filename_prefix = "something_else",+ package_version = "1.0",+ release_tag = "v1.0",+ release_base_url = "https://example.invalid/download",+ env = env(torch_mm = "2.13", platform_tag = "win_amd64"),+ )+ assert url == (+ "https://example.invalid/download/v1.0/"+ "something_else-1.0+cu13torch2.13cxx11abiTRUE-cp313-cp313-win_amd64.whl"+ )++ def test_no_cuda_still_resolves_to_nothing(self):+ assert (+ wheel_utils.direct_wheel_url(+ filename_prefix = "flash_attn",+ package_version = "2.8.1",+ release_tag = "v2.8.1",+ release_base_url = "https://example.invalid/download",+ env = env(cuda_major = ""),+ )+ is None+ )+++# ── The build plan ────────────────────────────────────────────────────────────+++class TestMatrix:+ def test_defaults_are_both_torch_minors_on_cp313(self):+ include = prebuilt_wheels.build_matrix()+ assert len(include) == 6+ assert {cell["torch"] for cell in include} == {"2.13.0", "2.14.0"}+ assert {cell["python_tag"] for cell in include} == {"cp313"}+ assert {cell["package"] for cell in include} == set(prebuilt_wheels.SPECS)++ def test_extra_interpreters_are_separate_cells(self):+ include = prebuilt_wheels.build_matrix(pythons = "3.11,3.12,3.13")+ assert len(include) == 18+ assert len({cell["wheel_name"] for cell in include}) == 18++ def test_one_torch_minor_at_a_time(self):+ include = prebuilt_wheels.build_matrix(torches = "2.14.0")+ assert {cell["torch_mm"] for cell in include} == {"2.14"}++ @pytest.mark.parametrize(+ "kwargs",+ [+ {"packages": "flash-attn; rm -rf /"},+ {"packages": "torchvision"},+ {"torches": "2.12.0"},+ {"torches": "$(whoami)"},+ {"pythons": "3.9"},+ {"pythons": "3.13 && curl evil"},+ ],+ )+ def test_anything_not_on_the_allowlist_is_refused(self, kwargs):+ with pytest.raises(SystemExit):+ prebuilt_wheels.build_matrix(**kwargs)++ def test_every_cell_carries_what_the_steps_read(self):+ needed = {+ "package",+ "dist",+ "version",+ "repo",+ "ref",+ "submodules",+ "patch",+ "torch",+ "torch_mm",+ "python",+ "python_tag",+ "cuda_tag",+ "abi",+ "max_jobs",+ "nvcc_threads",+ "build_timeout",+ "build_env",+ "import_names",+ "wheel_name",+ "label",+ }+ for cell in prebuilt_wheels.build_matrix(pythons = "3.11,3.12,3.13"):+ assert needed <= set(cell), needed - set(cell)++ def test_sources_are_pinned_to_a_commit(self):+ """A branch or a floating tag would make a rebuild silently different from the last one,+ which for a signed binary is the one property worth keeping."""+ for package, spec in prebuilt_wheels.SPECS.items():+ assert re.fullmatch(r"[0-9a-f]{40}", spec["ref"]), (package, spec["ref"])++ def test_the_build_env_is_name_equals_value_pairs_only(self):+ """The workflow `export`s these. Anything with a space or a shell metacharacter in it+ would be an injection with a constant on the other end, which is still an injection."""+ for cell in prebuilt_wheels.build_matrix():+ for pair in cell["build_env"].split(" "):+ assert re.fullmatch(r"[A-Z0-9_]+=[A-Za-z0-9_;.,-]+", pair), pair++ def test_force_build_is_set_for_every_package(self):+ """Without it each setup.py downloads an upstream wheel and repackages it, which for+ torch 2.13 means publishing the very binary that does not load."""+ for package, spec in prebuilt_wheels.SPECS.items():+ forced = [key for key in spec["env"] if key.endswith("FORCE_BUILD")]+ assert len(forced) == 1, package+ assert spec["env"][forced[0]] == "TRUE", package++ def test_mamba_keeps_the_cuda_kernels(self):+ """MAMBA_KEEP_CUDA_BUILD is opt-in upstream, and selective_scan_cuda -- the extension+ whose missing symbols are the entire problem -- is absent from the wheel without it."""+ assert prebuilt_wheels.SPECS["mamba-ssm"]["env"]["MAMBA_KEEP_CUDA_BUILD"] == "TRUE"+ assert "selective_scan_cuda" in prebuilt_wheels.SPECS["mamba-ssm"]["import_names"]++ def test_flash_attn_archs_cover_what_we_claim(self):+ archs = prebuilt_wheels.SPECS["flash-attn"]["env"]["FLASH_ATTN_CUDA_ARCHS"].split(";")+ # 86 and 89 are covered by the 80 cubin, which is forward compatible across the minor+ # versions of its major. Those two must NOT be listed: each one is a full extra pass+ # over every kernel for nothing.+ assert archs == ["80", "90", "100", "120"]+++class TestWheelNames:+ def test_the_local_version_segment_is_upstreams(self):+ """Byte for byte what Dao-AILab and state-spaces put in their own release assets, so a+ wheel of ours drops into any tooling that already pattern-matches theirs."""+ assert (+ prebuilt_wheels.wheel_name("flash-attn", "2.13.0", "3.13")+ == "flash_attn-2.8.4+cu13torch2.13cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"+ )+ assert (+ prebuilt_wheels.wheel_name("mamba-ssm", "2.14.0", "3.12")+ == "mamba_ssm-2.3.2.post1+cu13torch2.14cxx11abiTRUE-cp312-cp312-linux_x86_64.whl"+ )+ assert (+ prebuilt_wheels.wheel_name("causal-conv1d", "2.13.0", "3.11")+ == "causal_conv1d-1.7.0+cu13torch2.13cxx11abiTRUE-cp311-cp311-linux_x86_64.whl"+ )++ def test_round_trip(self):+ for package in prebuilt_wheels.SPECS:+ name = prebuilt_wheels.wheel_name(package, "2.14.0", "3.13")+ parsed = prebuilt_wheels.parse_wheel_name(name)+ assert parsed["package"] == package+ assert parsed["torch"] == "2.14"+ assert parsed["python"] == "cp313"+ assert parsed["abi"] == "TRUE"++ @pytest.mark.parametrize(+ "name",+ [+ "SHA256SUMS",+ "flash_attn-2.8.4+cu13torch2.13cxx11abiTRUE-cp313-cp313-linux_x86_64.whl.sigstore.json",+ "flash_attn-2.8.1+cu12torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl",+ "torch-2.13.0-cp313-cp313-linux_x86_64.whl",+ ],+ )+ def test_things_that_are_not_our_wheels_are_not_parsed_as_wheels(self, name):+ assert prebuilt_wheels.parse_wheel_name(name) is None+++class TestReleaseNotes:+ def _notes(self):+ entries = [+ (f"{index:064x}", prebuilt_wheels.wheel_name(package, torch, "3.13"))+ for index, (package, torch) in enumerate(+ (package, torch)+ for torch in prebuilt_wheels.TORCH_VERSIONS+ for package in prebuilt_wheels.SPECS+ )+ ]+ entries.append(("deadbeef", "SHA256SUMS"))+ return prebuilt_wheels.render_notes(+ entries, tag = "prebuilt-wheels-cu13", repo = "unslothai/unsloth"+ )++ def test_every_wheel_is_listed_with_its_digest(self):+ notes = self._notes()+ for torch in prebuilt_wheels.TORCH_VERSIONS:+ for package in prebuilt_wheels.SPECS:+ assert f"`{prebuilt_wheels.wheel_name(package, torch, '3.13')}`" in notes+ assert "| 6 wheels" not in notes+ assert "6 wheels, each with a `.sigstore.json` bundle beside it." in notes++ def test_non_wheel_assets_are_not_rows(self):+ assert "| `SHA256SUMS` |" not in self._notes()++ def test_the_verification_commands_are_the_ones_the_workflow_signs_with(self):+ notes = self._notes()+ assert "python -m sigstore verify identity" in notes+ assert (+ "https://github.com/unslothai/unsloth/.github/workflows/prebuilt-cuda-wheels.yml"+ in notes+ )+ assert "--cert-oidc-issuer https://token.actions.githubusercontent.com" in notes+ assert "gh attestation verify <wheel> --repo unslothai/unsloth" in notes+ assert "sha256sum -c SHA256SUMS" in notes++ def test_it_says_why_these_exist_with_the_actual_symbols(self):+ notes = self._notes()+ assert "materialize_cow_storage" in notes+ assert "c10_cuda_check_implementation" in notes+ assert "Linux x86_64 only" in notes+ assert "Not covered: Windows, macOS, ROCm" in notes++ def test_an_empty_release_does_not_render_an_empty_table(self):+ notes = prebuilt_wheels.render_notes([], tag = "t", repo = "o/r")+ assert "No wheels are attached" in notes+ assert "| Wheel | Package |" not in notes+++class TestMambaPatch:+ SOURCE = """+extra_compile_args = {+ "cxx": ["-O3", "-std=c++17"],+ "nvcc": ["-O3", "-std=c++17"],+}+other = {+ "cxx": ["-O3", "-std=c++17"],+ "nvcc": ["-O3", "-std=c++17"],+}+"""++ def _run(self, tmp_path, source):+ setup = tmp_path / "setup.py"+ setup.write_text(source, encoding = "utf-8")+ result = subprocess.run(+ [sys.executable, str(SCRIPTS / "patch_mamba_cxx20.py"), str(setup)],+ capture_output = True,+ text = True,+ )+ return result, setup++ def test_it_patches_all_four(self, tmp_path):+ result, setup = self._run(tmp_path, self.SOURCE)+ assert result.returncode == 0, result.stderr+ patched = setup.read_text(encoding = "utf-8")+ assert patched.count('"-std=c++20"') == 4+ assert '"-std=c++17"' not in patched++ def test_it_is_idempotent(self, tmp_path):+ result, setup = self._run(tmp_path, self.SOURCE)+ assert result.returncode == 0+ again = subprocess.run(+ [sys.executable, str(SCRIPTS / "patch_mamba_cxx20.py"), str(setup)],+ capture_output = True,+ text = True,+ )+ assert again.returncode == 0, again.stderr+ assert "nothing to do" in again.stdout+ assert setup.read_text(encoding = "utf-8").count('"-std=c++20"') == 4++ def test_an_upstream_change_fails_loudly(self, tmp_path):+ """If upstream makes this change itself, or moves to c++23, the run must stop rather+ than build something nobody chose."""+ result, _ = self._run(tmp_path, self.SOURCE.replace('"-std=c++17"', '"-std=c++23"', 2))+ assert result.returncode == 1+ assert "expected 4 occurrences" in result.stderr++ def test_a_missing_file_fails(self, tmp_path):+ result = subprocess.run(+ [sys.executable, str(SCRIPTS / "patch_mamba_cxx20.py"), str(tmp_path / "nope.py")],+ capture_output = True,+ text = True,+ )+ assert result.returncode == 1+++# ── The workflow itself ───────────────────────────────────────────────────────++[email protected](scope = "module")+def workflow():+ return yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))+++class TestWorkflow:+ def test_dispatch_only(self, workflow):+ """It signs binaries and writes a release under our identity. A pull_request or push+ trigger would put both behind whatever a fork can propose."""+ assert set(triggers(workflow)) == {"workflow_dispatch"}++ def test_publishing_is_opt_in(self, workflow):+ """A run that only builds, smoke tests and signs is the default, so the expensive and+ irreversible half has to be asked for."""+ inputs = triggers(workflow)["workflow_dispatch"]["inputs"]+ assert inputs["publish"]["default"] is False+ assert inputs["gpu_smoke"]["default"] is False+ assert workflow["jobs"]["publish"]["if"] == "inputs.publish"+ assert workflow["jobs"]["gpu-smoke"]["if"] == "inputs.gpu_smoke"++ def test_only_publish_can_write_contents(self, workflow):+ assert workflow["permissions"] == {"contents": "read"}+ for name, job in workflow["jobs"].items():+ permissions = job.get("permissions", {})+ if name == "publish":+ assert permissions == {"contents": "write"}+ else:+ assert permissions.get("contents", "read") == "read", name++ def test_only_the_sign_job_gets_an_oidc_token(self, workflow):+ for name, job in workflow["jobs"].items():+ permissions = job.get("permissions", {})+ expected = "write" if name == "sign" else None+ assert permissions.get("id-token") == expected, name+ assert permissions.get("attestations") == expected, name++ def test_the_signing_job_names_the_gateable_environment(self, workflow):+ assert workflow["jobs"]["sign"]["environment"] == "release-signing"++ def test_the_publish_job_builds_nothing(self, workflow):+ """contents: write and a compiler in the same job is how a poisoned build reaches a+ release. The publish job only downloads an artifact and uploads it."""+ steps = workflow["jobs"]["publish"]["steps"]+ body = json.dumps(steps)+ assert "setup.py" not in body+ assert "pip install" not in body++ def test_it_never_becomes_the_latest_release(self, workflow):+ """The repository's latest release is what the installers and the README resolve to.+ A wheelhouse tag must not take it."""+ body = json.dumps(workflow["jobs"]["publish"]["steps"])+ assert body.count("--latest=false") == 3+ assert "gh release create" in body+ assert "--clobber" in body++ def test_every_action_is_pinned_to_a_sha(self, workflow):+ for name, job in workflow["jobs"].items():+ for step in job["steps"]:+ uses = step.get("uses")+ if uses is None:+ continue+ assert re.fullmatch(r"[^@]+@[0-9a-f]{40}", uses), (name, uses)++ def test_it_signs_with_sigstore_and_attests_provenance(self, workflow):+ uses = [step.get("uses", "") for step in workflow["jobs"]["sign"]["steps"]]+ assert any(u.startswith("sigstore/gh-action-sigstore-python@") for u in uses)+ assert any(u.startswith("actions/attest-build-provenance@") for u in uses)++ def test_the_signature_is_verified_in_the_same_job(self, workflow):+ """A bundle nobody checked is a bundle nobody can rely on, and it must verify against+ the identity the release notes tell people to use."""+ step = next(+ step+ for step in workflow["jobs"]["sign"]["steps"]+ if step.get("uses", "").startswith("sigstore/")+ )+ assert step["with"]["verify"] is True+ identity = step["with"]["verify-cert-identity"]+ assert ".github/workflows/prebuilt-cuda-wheels.yml@" in identity+ assert step["with"]["verify-oidc-issuer"] == "https://token.actions.githubusercontent.com"++ def test_the_build_job_gates_on_the_import(self, workflow):+ """The import check is the point of the release. If it ever becomes informational this+ workflow publishes exactly the broken wheels it exists to replace."""+ smoke = next(+ step+ for step in workflow["jobs"]["build"]["steps"]+ if step.get("name", "").startswith("Smoke test")+ )+ assert "continue-on-error" not in smoke+ assert "importlib.import_module" in smoke["run"]++ def test_the_build_runs_on_the_older_ubuntu(self, workflow):+ """The wheels are tagged linux_x86_64, which pip installs without a glibc check, so the+ runner's glibc is the real compatibility floor."""+ assert workflow["jobs"]["build"]["runs-on"] == "ubuntu-22.04"++ def test_the_gpu_job_uses_a_label_that_already_exists(self, workflow):+ """Never invent a runner label: a job with one queues until the run is cancelled."""+ existing = set()+ for path in (REPO / ".github" / "workflows").glob("*.yml"):+ for job in (+ (yaml.safe_load(path.read_text(encoding = "utf-8")) or {}).get("jobs", {}).values()+ ):+ runs_on = job.get("runs-on")+ if isinstance(runs_on, list):+ existing.add(tuple(runs_on))+ assert tuple(workflow["jobs"]["gpu-smoke"]["runs-on"]) in existing++ def test_the_build_cannot_outlive_githubs_job_limit(self, workflow):+ """A job that hits the 6 h cap is reported as cancelled with no logs. Both the step's+ own timeout and the job's have to sit below it."""+ assert workflow["jobs"]["build"]["timeout-minutes"] < 360+ for spec in prebuilt_wheels.SPECS.values():+ minutes = int(spec["build_timeout"].removesuffix("m"))+ assert minutes < workflow["jobs"]["build"]["timeout-minutes"]++ def test_the_sign_job_refuses_a_short_matrix(self, workflow):+ """A missing leg publishes a set with a hole in it, which downstream reads as "no wheel"+ and sends the user into a source build."""+ body = json.dumps(workflow["jobs"]["sign"]["steps"])+ assert "expected $EXPECTED wheels" in body++ def test_concurrency_queues_rather_than_cancels(self, workflow):+ assert workflow["concurrency"]["cancel-in-progress"] is False