Skip to content

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.

Condense comments added since the last cleanup: installers, scripts and CI (#16112)

Daniel Han54a932c0c959
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index c731b988f0c..a5838a59751 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -2,9 +2,8 @@
version: 2
updates:
- package-ecosystem: "github-actions"
- # "/" only scans .github/workflows. The composite actions under
- # .github/actions pin the same actions (setup-node, cache) and must
- # move in the same PR, or two SHAs of one action end up in the tree.
+ # The "/" directory only scans .github/workflows; composite actions under .github/actions pin
+ # the same actions and must move in the same PR, or one action ends up with two SHAs.
directories:
- "/"
- "/.github/actions/*"
@@ -44,18 +43,16 @@ updates:
directory: "/"
schedule:
interval: "weekly"
- # pyproject.toml is a hand-kept matrix: many packages are split by Python version or
- # accelerator (typer / fastapi / uvicorn / gguf for 3.9, triton / flash-attn wheel URLs),
- # and a version update rewrites every copy of a requirement at once. Version-update PRs
- # stay off, as for /studio/frontend; security PRs have their own limit and still open.
+ # pyproject.toml is a hand-kept matrix split by Python version or accelerator, and one version
+ # update rewrites every copy at once; version PRs stay off as for /studio/frontend, security PRs
+ # still open.
open-pull-requests-limit: 0
cooldown:
default-days: 7
- # pyproject.toml pins these by hand: torch / torchvision per CUDA extra (with the
- # matching +cuXXX tag and xformers wheel), and transformers / datasets / bitsandbytes
- # to tested windows with `!=` exclusions. Dependabot rewrites each whole specifier
- # (#13833, #14469 collapsed every cuXXX-torchYYY extra to plain torch==2.14.1), so
- # these move with the version matrix by hand. Advisories still show as alerts.
+ # pyproject.toml pins torch and torchvision per CUDA extra and transformers, datasets and
+ # bitsandbytes via != exclusions; Dependabot rewrites whole specifiers (#13833 and 14469
+ # collapsed every cuXXX-torchYYY extra to torch==2.14.1), so move these by hand; advisories
+ # still show as alerts.
ignore:
- dependency-name: "torch"
- dependency-name: "torchvision"
@@ -93,10 +90,9 @@ updates:
versions: [">= 0.19"]
- dependency-name: "gdk-pixbuf"
versions: [">= 0.19"]
- # Same GTK3 family: the direct cairo-rs dep exists only to turn on the
- # `png` feature of gtk's own cairo-rs 0.18. A second cairo-rs (0.22)
- # leaves gtk's copy without `png` and browser_capture.rs stops
- # compiling (`write_to_png` not found), as in #13837.
+ # Same GTK3 family: the direct cairo-rs dep only turns on png for gtk's cairo-rs 0.18; a
+ # second cairo-rs (0.22) leaves gtk without png, so browser_capture.rs stops compiling
+ # (#13837).
- dependency-name: "cairo-rs"
versions: [">= 0.19"]
# gio is only used for the proxy resolver gtk already builds; 0.19+
@@ -108,10 +104,9 @@ updates:
# compiling (E0063). Lift once deep-link builds against 0.21.3.
- dependency-name: "rust-ini"
versions: [">= 0.21.2"]
- # windows-core must match the copy webview2-com and tauri build on
- # (Cargo.toml: "Keep these versions aligned with Tauri's WebView2
- # controller bindings"); a lone windows-core bump puts a second copy
- # next to webview2-com's 0.62. Move it by hand with webview2-com.
+ # windows-core must match the copy that webview2-com and tauri build on (see the Cargo.toml
+ # note); a lone bump adds a second copy beside webview2-com 0.62, so move it with
+ # webview2-com.
- dependency-name: "windows-core"
update-types: ["version-update:semver-major", "version-update:semver-minor"]
groups:
diff --git a/.github/scripts/compare_installer_evidence.py b/.github/scripts/compare_installer_evidence.py
index 41f108acc6f..712833b16be 100644
--- a/.github/scripts/compare_installer_evidence.py
+++ b/.github/scripts/compare_installer_evidence.py
@@ -204,10 +204,8 @@ _SPINNER_FRAMES = frozenset("-\\|/")
# ends on still compares, as does any line with other text on it.
_PARTIAL_PROGRESS_FRAME = re.compile(r"[█▒]*▒[█▒]*\s+(?:<percent>|<size> / <size>)")
-# The full bar itself can also be drawn twice when winget's last redraw lands after the 100% frame:
-# a run of the same uv download left it once on one side and twice in a row on the other. Only a full
-# bar that repeats the line kept right before it is dropped, so a download that never finishes, or a
-# second download (its own "Downloading" line sits between the bars), still compares.
+# A full bar can be drawn twice when winget's last redraw lands after the 100% frame, so only a full
+# bar repeating the line just before it is dropped; unfinished or second downloads still compare.
_FULL_PROGRESS_FRAME = re.compile(r"█+\s+(?:<percent>|<size> / <size>)")
_CONTROL = re.compile(r"\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07")
diff --git a/.github/scripts/kaggle_studio_ci/build_kernel.py b/.github/scripts/kaggle_studio_ci/build_kernel.py
index 6bd0118d2a9..052a6c263c0 100644
--- a/.github/scripts/kaggle_studio_ci/build_kernel.py
+++ b/.github/scripts/kaggle_studio_ci/build_kernel.py
@@ -123,14 +123,9 @@ def _prefetch_builder():
def _models_from(payload_args: str) -> list[str]:
- """The repos this payload will load, read off its own argv.
-
- NOT a second copy of the defaults. ``--chat-model`` and ``--train-model``
- are dispatch inputs, so a hardcoded pair here would prefetch the wrong
- models the moment anyone used them -- and prefetching the wrong repo is
- invisible: it downloads happily, warms a cache nobody reads, and reports
- success.
- """
+ """Reads the repos from the payload argv, not a second copy of the defaults: --chat-model and
+ --train-model are dispatch inputs, so a wrong prefetch looks like success while warming a
+ cache nobody reads."""
tokens = payload_args.split()
picked = {}
for flag, default in (
diff --git a/.github/scripts/kaggle_studio_ci/collect_evidence.py b/.github/scripts/kaggle_studio_ci/collect_evidence.py
index 24985b9b652..32e3d15e676 100644
--- a/.github/scripts/kaggle_studio_ci/collect_evidence.py
+++ b/.github/scripts/kaggle_studio_ci/collect_evidence.py
@@ -83,17 +83,8 @@ def iter_text(path: Path):
def collect_chunks(streams) -> tuple[dict[int, str], int]:
- """{index: chunk} and the declared total, from any number of streams.
-
- The same chunk arrives twice, because the executed notebook and Kaggle's
- kernel log are two copies of one stdout. Either copy can be cut off mid
- line, and a cut only ever shortens: the survivor is a prefix of the whole
- chunk, and it still parses as ``i/n <payload>``. Overwriting on every
- sighting therefore let a truncated second copy replace a complete first
- one, and the reassembled bundle then failed base64 or tar validation with
- every chunk index present -- evidence lost with the complete source on
- disk. So a later sighting is taken only when it EXTENDS what is held.
- """
+ """Returns {index: chunk} and the declared total; a repeated chunk replaces the held one only
+ when it extends it, since a cut copy is always a prefix of the whole chunk."""
chunks: dict[int, str] = {}
total = 0
for text in streams:
diff --git a/.github/scripts/kaggle_t4_ci/build_kernel.py b/.github/scripts/kaggle_t4_ci/build_kernel.py
index 4bdb4fb467d..219087af3c3 100644
--- a/.github/scripts/kaggle_t4_ci/build_kernel.py
+++ b/.github/scripts/kaggle_t4_ci/build_kernel.py
@@ -145,11 +145,8 @@ def build_payload_notebook(
extra_args: tuple[str, ...] = (),
reference: str | None = None,
) -> dict:
- """A notebook that installs one leg's stack and runs it.
-
- One GPU for every leg but the `all_cards` one, which is unpinned so that
- unsloth's DEVICE_COUNT > 1 code path is reachable at all.
- """
+ """Builds a notebook that installs one leg's stack and runs it; one GPU per leg except
+ all_cards, which is unpinned so unsloth's DEVICE_COUNT > 1 path is reachable at all."""
root = _kernel_root(leg)
expected_visible = 2 if leg.all_cards else 1
wanted = list(leg.files)
@@ -1646,19 +1643,8 @@ def build_kernel(
def _shared_vcs_specs(leg_groups: dict[str, list[list[str]]]) -> tuple[str, ...]:
- """VCS requirements that EVERY leg installs identically.
-
- Derived rather than declared. The two SHAs already live in the install
- groups, and a second copy here would be a second thing to keep in step --
- one that drifts silently, because a wheel built from the wrong ref installs
- perfectly and fails nothing.
-
- "Every leg" is the point of the intersection. A spec only one leg carries is
- part of what that leg is testing and must keep its own resolution; building
- it once and sharing it would quietly make the legs agree about something
- they exist to disagree about. Two legs pinning the SAME package to
- DIFFERENT refs therefore yields nothing shared, which is the safe answer.
- """
+ """VCS requirements every leg installs identically, derived by intersection; a spec only one leg
+ carries, or one package pinned to different refs by two legs, is never shared."""
if not leg_groups:
return ()
sets = []
diff --git a/.github/scripts/kaggle_t4_ci/collect.py b/.github/scripts/kaggle_t4_ci/collect.py
index 24221bab7f2..f65a576d0be 100644
--- a/.github/scripts/kaggle_t4_ci/collect.py
+++ b/.github/scripts/kaggle_t4_ci/collect.py
@@ -96,12 +96,8 @@ def _out(key: str, value: str) -> None:
def kernel_age_hours(kernel, now: datetime) -> float | None:
- """How long ago this kernel last started, or None if Kaggle did not say.
-
- For an UNFINISHED kernel ``last_run_time`` is when the run started, which is
- what the reap ceiling measures against. None rather than a default, treated
- as too young to reap: guessing old deletes a live session.
- """
+ """Hours since an unfinished kernel's last_run_time, or None if Kaggle did not say; None counts
+ as too young to reap, since guessing old would delete a live session."""
last_run = _as_naive_utc(getattr(kernel, "last_run_time", None))
if last_run is None:
return None
@@ -166,12 +162,8 @@ def find_ours(
def _status_of(api, slug: str) -> str:
- """The kernel's state, with a deleted kernel distinguished from an unknown one.
-
- A kernel deleted moments ago still lists but 404s its status call:
- definitively not running, not unreadable. Conflating the two makes the
- reaper attack gone kernels and read a genuine outage as idle.
- """
+ """A just-deleted kernel still lists but 404s its status call, meaning not running rather than
+ unreadable; conflating the two makes the reaper attack gone kernels and read outages as idle."""
try:
raw = str(getattr(api.kernels_status(slug), "status", ""))
except Exception as exc: # noqa: BLE001
@@ -185,11 +177,8 @@ def _status_of(api, slug: str) -> str:
def verdict_of(reports: list[dict], expect: int) -> tuple[str, str]:
- """Turn the payload reports into a verdict, exactly as launch.py does inline.
-
- Kept identical so a dispatched run and a waited-on run reach the same
- conclusion from the same evidence.
- """
+ """Turns payload reports into a verdict exactly as launch.py does inline; kept identical so
+ dispatched and waited-on runs reach the same conclusion from the same evidence."""
if not reports:
return "infra", (
"the kernel finished but produced no payload report; "
@@ -211,12 +200,8 @@ def verdict_of(reports: list[dict], expect: int) -> tuple[str, str]:
def _gone(exc: BaseException) -> bool:
- """Did this failure say the kernel is no longer there?
-
- Three unserialised collectors run, so another can delete a kernel between
- this pass seeing it terminal and downloading it. Not an infra failure: a
- result somebody else already posted.
- """
+ """True when the error says the kernel is gone: another unserialised collector may have deleted
+ it, so it is a result already posted by someone else, not an infra failure."""
text = f"{exc}".lower()
return any(m in text for m in GONE_MARKERS)
@@ -252,12 +237,8 @@ def expected_reports(
default: int,
kind: str = "",
) -> int | None:
- """How many payload reports this kernel was built to produce.
-
- Read off the kernel's own evidence, the only record that survives dispatch.
- A kernel predating the sentinel, or a Studio kernel (always one report),
- answers ``default``.
- """
+ """Payload report count read from the kernel's own evidence, the only record surviving dispatch;
+ kernels predating the sentinel and Studio kernels (always one) answer default."""
for line in _evidence_lines(dest):
if not line.startswith(EXPECT_SENTINEL):
continue
@@ -293,11 +274,8 @@ def collect_one(
delete: bool = True,
deadline: float | None = None,
) -> dict:
- """Read one kernel to a conclusion. Returns the record for the result file.
-
- ``deadline`` is the whole pass's; the evidence download gets its own budget
- clamped to what is left, so the last kernel cannot overrun the job.
- """
+ """Reads one kernel to a conclusion and returns its result record; deadline covers the whole
+ pass, while the evidence download gets its own budget clamped to what is left."""
slug = entry["slug"]
state = _status_of(api, slug)
record = {
@@ -468,13 +446,9 @@ RELEASE_BUDGET_SEC = 600
def delete_collected(result_path: Path, posted_path: Path | None) -> int:
- """Release the kernels a ``--no-delete`` pass judged, now that their
- statuses are posted.
-
- ``posted.json`` names the slugs delivered, refused, and whose commit is
- gone. A refused post KEEPS its kernel, the only retry there is. A gone
- commit releases it; holding it only bills.
- """
+ """Releases kernels a --no-delete pass judged, once posted.json has them as delivered, refused
+ or gone; a refused post keeps its kernel as the only retry, and a gone commit releases it,
+ since holding it only bills."""
data = json.loads(result_path.read_text(encoding = "utf-8"))
posted = (
json.loads(posted_path.read_text(encoding = "utf-8"))
diff --git a/.github/scripts/kaggle_t4_ci/post_statuses.py b/.github/scripts/kaggle_t4_ci/post_statuses.py
index fdc55d7e012..6bbc21f2c08 100644
--- a/.github/scripts/kaggle_t4_ci/post_statuses.py
+++ b/.github/scripts/kaggle_t4_ci/post_statuses.py
@@ -83,11 +83,8 @@ def post_one(repo: str, full_sha: str, status: dict) -> bool:
def valid(status: dict) -> str | None:
- """Why this record must not be posted, or None if it is well formed.
-
- Checked here because this is the process holding the token: a state outside
- the API's four, or a context not ours, is a record we must not sign.
- """
+ """Reason a status must not be posted, or None if well formed; checked here because this process
+ holds the token, so no state outside the API or foreign context gets signed."""
if status.get("state") not in STATES:
return f"state {status.get('state')!r} is not one of {STATES}"
if status.get("context") not in STATUS_CONTEXTS.values():
@@ -98,12 +95,9 @@ def valid(status: dict) -> str | None:
def merge_by_commit(resolved: list[tuple[str, dict]]) -> list[tuple[str, dict]]:
- """One status per (full sha, context), failure winning, every slug named.
-
- Merged HERE and not in the collector, because only a resolved sha says
- whether two slugs name one commit: an 8 and a 12 character slug for one
- commit resolve alike, two commits sharing 8 characters do not.
- """
+ """One status per (full sha, context), failure winning, every slug named; merging waits for
+ resolved full shas, since an 8 and a 12 character slug of one commit match but two commits
+ can share 8 characters."""
out: dict[tuple[str, str], dict] = {}
for full, status in resolved:
key = (full, status["context"])
diff --git a/.github/scripts/prebuilt_wheels.py b/.github/scripts/prebuilt_wheels.py
index 4984ef4ed3d..b27844c226b 100644
--- a/.github/scripts/prebuilt_wheels.py
+++ b/.github/scripts/prebuilt_wheels.py
@@ -86,17 +86,14 @@ def cuda_archs(package: str, platform: str) -> str:
return SSM_SASS_BY_PLATFORM.get(platform, SSM_SASS)
-# The Linux tag. 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.
+# Wheel tagged linux_x86_64 rather than manylinux like upstream, so pip accepts any glibc; the
+# practical floor is the runner glibc, hence ubuntu-22.04 (glibc 2.35), not ubuntu-latest.
PLATFORM_TAG = "linux_x86_64"
-# Keyed by the wheel's pip platform tag. No upstream release has ever shipped a Windows wheel.
-# `abi` is torch._C._GLIBCXX_USE_CXX11_ABI, which upstream setup.py copies into the name; the
-# Windows cu130 torch reports True too, and the build asserts it. `pytorch_nvcc` goes into
-# build.ninja unquoted and is the only way to cache nvcc on Windows (_wrap_compiler is a no-op
-# there), hence the space-free paths.
+# Keyed by pip platform tag, and no upstream release ships a Windows wheel; abi is
+# torch._C._GLIBCXX_USE_CXX11_ABI (asserted, Windows cu130 torch reports True too); pytorch_nvcc
+# goes unquoted into build.ninja, the only way to cache nvcc on Windows, so its paths must have no
+# spaces.
PLATFORMS = {
"linux_x86_64": {
"os": "linux",
@@ -282,10 +279,9 @@ ALLOWED_TORCH = tuple(
)
)
-# 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.
+# cp313 is the default because each extra interpreter is a whole flash-attn build; 3.11 and 3.12 can
+# be added as separate cells; 3.14 is absent since torch has 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)
@@ -798,11 +794,9 @@ def _cmd_size_gate(args: argparse.Namespace) -> int:
return 0
-# A fatbin container: magic, version 1, a 16-byte header and the size of the entries after it.
-# Each entry's header starts with kind (1 PTX, 2 ELF), its own header size, the payload size,
-# and the target arch at byte 28. Read straight from the file rather than through cuobjdump,
-# which only reads its host's object format (a Linux cuobjdump says a Windows .pyd "does not
-# contain device code") and names PTX entries sm_XX.ptx, easy to miss with a pattern.
+# Fatbin container: magic, version 1, a 16-byte header, then entries with kind (1 PTX, 2 ELF) and
+# target arch at byte 28; read directly because cuobjdump only reads its host object format and
+# names PTX entries sm_XX.ptx.
_FATBIN_MAGIC = (0xBA55ED50).to_bytes(4, "little")
_FATBIN_PTX, _FATBIN_ELF = 1, 2
diff --git a/.github/scripts/resolve-desktop-release.py b/.github/scripts/resolve-desktop-release.py
index 18b4d401aca..c2c0ab1077f 100644
--- a/.github/scripts/resolve-desktop-release.py
+++ b/.github/scripts/resolve-desktop-release.py
@@ -59,12 +59,9 @@ def fetch_assets(tag: str, repo: str) -> Any:
def resolve_newest(releases: Any, asset_suffix: str, fetch) -> str | None:
- """Newest SemVer release carrying the asset, hydrating one release at a time.
-
- Newest first and stop on the first match: hydrating every entry cost one
- subprocess per release per matrix leg, and let a transient lookup on an
- irrelevant historical release fail a leg whose answer was the newest one.
- """
+ """Returns the newest SemVer release carrying the asset, hydrating newest first and stopping at
+ the first match; hydrating every entry cost a subprocess per release per leg and let a
+ transient lookup on an old release fail a leg."""
if not isinstance(releases, list):
raise ValueError("release listing must be a JSON array")
diff --git a/.github/scripts/studio_smoke/multi_turn_chat.py b/.github/scripts/studio_smoke/multi_turn_chat.py
index 14a48d5bb5b..27de64fbc3b 100644
--- a/.github/scripts/studio_smoke/multi_turn_chat.py
+++ b/.github/scripts/studio_smoke/multi_turn_chat.py
@@ -58,9 +58,8 @@ PROMPTS = [
def _server() -> tuple[str, str]:
- """Where to talk and what to send. The only thing that differs per caller: each
- workflow boots its server on its own port. Read here rather than at import, so the
- checking half of this file can be exercised without a server or the SDKs."""
+ """Returns (BASE_URL, TOKEN) from the environment, since each workflow boots its server on its
+ own port; read at call time, not import, so the checks run without a server or SDKs."""
return os.environ["BASE_URL"], os.environ["TOKEN"]
diff --git a/.github/workflows/cache-janitor.yml b/.github/workflows/cache-janitor.yml
index 42294cd944a..47fec815cad 100644
--- a/.github/workflows/cache-janitor.yml
+++ b/.github/workflows/cache-janitor.yml
@@ -133,12 +133,9 @@ permissions:
jobs:
prune:
name: Prune superseded caches
- # Not ubuntu-latest: that label's queue is what merge bursts fill, and on 2026-10-13/14 this
- # sweep waited 0.6 to 3.5 hours for it (one run took 6h15m end to end) while CodeQL kept
- # writing overlay bases, so the budget it guards ran out between sweeps. The arm label
- # started jobs in a median 1.3 minutes over the same window. The sweep is API-only (gh,
- # GNU date/awk/sed/sort), all present on the arm image. The account-wide job cap still
- # applies; this only stops the sweep waiting behind hundreds of ubuntu-latest jobs.
+ # Arm label, not ubuntu-latest, since merge bursts fill that queue and stalled this sweep for
+ # hours; the sweep is API-only (gh, GNU date, awk, sed, sort), and the account job cap still
+ # applies.
runs-on: ubuntu-24.04-arm
timeout-minutes: 20
permissions:
@@ -269,10 +266,9 @@ jobs:
: > "$grouped"
while IFS=$'\t' read -r id created size ref ver key accessed; do
[ -z "${id:-}" ] && continue
- # Per-family keep. `keep` (the input) is for families where an older
- # generation can still answer a restore nothing newer can. CodeQL,
- # pip-v2, uv and rust-cache all restore by prefix and take the newest,
- # so their second copy answers only an exact revert (see the header).
+ # The keep input applies only where an older generation can answer a restore that
+ # nothing newer can; prefix-restored CodeQL, pip-v2, uv and rust-cache keep one copy,
+ # since a second copy answers only an exact revert.
fkeep="$KEEP"
case "$key" in
codeql-overlay-base-database-*)
@@ -280,20 +276,14 @@ jobs:
codeql-trap-*)
pre=$(printf '%s' "$key" | sed -E 's/-[0-9a-f]{40}$//'); fkeep=1 ;;
v0-rust-*)
- # rust-cache's restore-key is the key minus the trailing lockfile
- # hash, i.e. exactly this prefix, so a lockfile bump still starts
- # from the surviving generation.
+ # rust-cache restore-key is the key minus its trailing lockfile hash, exactly this
+ # prefix, so a lockfile bump still starts from the surviving generation.
pre=$(printf '%s' "$key" | sed -E 's/-[0-9a-f]{8,}$//'); fkeep=1 ;;
pip-v2-*|uv-*|fe-dist-*)
- # Strip only the trailing dependency hash. Everything before it --
- # the job name for pip-v2, the OS for uv and fe-dist -- stays in the
- # prefix on purpose: those are separate keys that never substitute
- # for one another, and folding them into one group would rank live
- # caches as generations of each other and delete all but one.
- #
- # A retired prefix (notebooks-colab -> notebooks-colab-cpu, see its
- # `name` in notebooks-ci.yml) is its own family here, so keep=1
- # drains it to one entry and the 7-day idle timer takes the last.
+ # Strip only the trailing dependency hash, so the job name (pip-v2) or OS (uv,
+ # fe-dist) stays in the prefix and separate keys are not ranked as generations; a
+ # retired notebooks-colab prefix is drained to one entry by keep=1, then aged out by
+ # the 7-day idle timer.
pre=$(printf '%s' "$key" | sed -E 's/-[0-9a-f]{64}$//')
# fe-dist has no restore-keys: an older generation is the only
# thing an exact revert of the frontend can hit, so it keeps `keep`.
diff --git a/.github/workflows/cancel-closed-pr-runs.yml b/.github/workflows/cancel-closed-pr-runs.yml
index 47fb66275b2..e33365749a4 100644
--- a/.github/workflows/cancel-closed-pr-runs.yml
+++ b/.github/workflows/cancel-closed-pr-runs.yml
@@ -1,31 +1,9 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-# When a pull request closes (merged or not), cancel its pull_request runs that
-# are still queued or running. Nobody reads them any more, and while the queue
-# is hours deep they hold slots the open PRs are waiting for: on 2026-10-14,
-# 121 of 498 queued pull_request runs belonged to PRs that were already merged
-# or closed.
-#
-# Trigger: `pull_request` (types: closed), not `pull_request_target`, which this
-# repo bans (scripts/lint_workflow_triggers.py). The cost is fork PRs: their
-# GITHUB_TOKEN is read-only whatever `permissions:` says, so for them the cancel
-# calls are refused and the job only reports what it would have cancelled. Same-
-# repository branches, where most of the stale runs come from (104 of the 121),
-# get the write token and are cleaned up.
-#
-# Nothing from the PR is checked out or executed. The head branch name is
-# untrusted text, so it reaches the shell only through env and is passed to
-# `gh api` as an argument, never interpolated into a command line.
-#
-# Which runs: event pull_request, status queued / waiting / pending / requested
-# / in_progress, and
-# - the run lists this PR number in pull_requests[], or
-# - pull_requests[] is empty (fork PRs) and the run's head branch AND head
-# repository match this PR's, and no other OPEN PR has that same head.
-# Never a push, schedule or dispatch run, never another fork's same-named
-# branch, never this workflow's own runs. /cancel only, never /force-cancel:
-# force-cancel skips `always()` steps, where workflows keep their cleanup.
+# Cancels queued or running pull_request runs of a closed PR, never push, schedule, dispatch or runs
+# of this workflow; not the banned pull_request_target; untrusted branch names reach the shell only
+# via env; fork tokens read-only so forks only report; /cancel, never /force-cancel (skips always())
name: Cancel closed PR runs
@@ -68,9 +46,8 @@ jobs:
[ -n "${HEAD_REPO:-}" ] || HEAD_REPO="-"
self_path="${SELF_WORKFLOW#*/*/}"; self_path="${self_path%@*}"
- # Another OPEN PR with the same head (repo + branch) shares its runs'
- # head_branch; for runs with empty pull_requests we cannot tell them
- # apart, so leave those alone.
+ # Another open PR with the same head (repo and branch) shares those runs' head_branch;
+ # runs with empty pull_requests cannot be told apart, so they are left alone.
shared=0
if [ "$HEAD_REPO" != "-" ]; then
owner="${HEAD_REPO%%/*}"
diff --git a/.github/workflows/ci-capacity.yml b/.github/workflows/ci-capacity.yml
index cfddba72e8d..0354e918976 100644
--- a/.github/workflows/ci-capacity.yml
+++ b/.github/workflows/ci-capacity.yml
@@ -117,13 +117,8 @@ jobs:
# ---------------------------------------------------------------------------
guard:
name: Re-enable anything left disabled
- # The complement of the condition on `sweep` below, so each trigger starts
- # only the job it asked for. Without it every ci-pause dispatch also took a
- # second runner out of the pool the sweep in the same run is
- # trying to free, and ran an enable loop on the one event that is asking for
- # the opposite. The floor under a pause is the cron, not this job appearing
- # on unrelated triggers; a manual restore is `mode=resume`, which enables the
- # whole allowlist rather than only what is past the cutoff.
+ # Complement of the sweep condition so each trigger starts only its own job; the cron, not this
+ # job, is the floor under a pause; manual restore is mode=resume, enabling the whole allowlist.
if: ${{ github.event_name == 'schedule' }}
runs-on: ubuntu-24.04-arm
steps:
diff --git a/.github/workflows/clean-machine-install-ci.yml b/.github/workflows/clean-machine-install-ci.yml
index 3fb601d77ec..f3ebbd90c5c 100644
--- a/.github/workflows/clean-machine-install-ci.yml
+++ b/.github/workflows/clean-machine-install-ci.yml
@@ -99,9 +99,8 @@ on:
default: tree
concurrency:
- # The event is in the group so a scheduled run and a push to main, which share a ref,
- # cannot coalesce: only one run stays pending per group, and cancel-in-progress protects
- # the running run, never the pending one, so a merge burst would drop the nightly.
+ # The event name stops a scheduled run and a push to main, which share a ref, from replacing each
+ # other as the one pending run, so a merge burst cannot drop the nightly.
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
# Latest-only on a PR branch. On main, cancel-in-progress is false so a RUNNING run is
# never killed, and a newer push replaces only the PENDING one: a merge burst runs the
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index 3806f3eb797..1d9a95f3594 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -1,11 +1,6 @@
-# CodeQL code scanning (advanced setup; replaces the repository's default setup).
-#
-# Coverage matches default setup: the same four languages, the default query suite and the
-# remote threat model. It runs weekly and on manual dispatch only, not on pull requests or
-# pushes to main. On pull requests it queued twice per push (a language picker, then up to four
-# analyses) behind the shared runner queue, and on main every merge built and cached a new
-# overlay-base database. A weekly analysis of main keeps the alerts current at a fraction of the
-# runner slots; dispatch it by hand to check a change sooner.
+# CodeQL advanced setup (replaces default setup) with the same four languages, query suite and
+# threat model; weekly and manual runs only, since each PR push queued twice and each main merge
+# cached a new overlay base.
name: CodeQL
on:
@@ -48,21 +43,10 @@ jobs:
with:
category: "/language:${{ matrix.language }}"
- # Keep one overlay-base database per language on main, at the moment a new one is written.
- #
- # On main, analyze saves the database it just built as a new cache entry keyed
- # codeql-overlay-base-database-<v>-<hash>-<language>-<codeql version>-<sha>-<run id>-<attempt>.
- # The save happens inside the analyze step itself, not in its post step
- # (cleanupAndUploadOverlayBaseDatabaseToCache in codeql-action src/analyze-action.ts, awaited
- # before the action returns), so by the time this job starts the new entry exists. Restores
- # match by the prefix up to the CodeQL version and take the newest entry, so every older
- # generation under the same prefix answers nothing and only holds budget.
- #
- # cache-janitor.yml applies the same keep-1 rule on its own schedule. When CodeQL analysed
- # every push to main, each one added about 1.3 GB and the janitor fell behind, which is what
- # pushed the repo to its 50 GiB ceiling. Pruning here bounds the family at write time; the
- # janitor stays as the backstop. A separate job so actions: write is
- # granted to this one shell step and never to the CodeQL action.
+ # Keeps one overlay-base database per language on main (per-push saves of about 1.3 GB pushed the
+ # repo to its 50 GiB ceiling); restores take the newest per prefix; the save lands inside analyze,
+ # so the entry exists before this job runs; a separate job keeps actions: write off the CodeQL
+ # action.
prune-overlay-bases:
name: Prune superseded CodeQL overlay bases
needs: analyze
diff --git a/.github/workflows/desktop-app-clean-machine-ci.yml b/.github/workflows/desktop-app-clean-machine-ci.yml
index e38b51f387c..708ca81cff8 100644
--- a/.github/workflows/desktop-app-clean-machine-ci.yml
+++ b/.github/workflows/desktop-app-clean-machine-ci.yml
@@ -86,9 +86,8 @@ env:
jobs:
# ── macOS: .dmg, Apple Silicon ────────────────────────────────────────────
macos:
- # A fork PR's token is read-only whatever this workflow declares, so it cannot list
- # review drafts. Skip rather than fail: a
- # property of the trigger, not a broken release.
+ # Fork PR tokens are read-only whatever the workflow declares, so they cannot list review
+ # drafts; skip rather than fail, since that is a property of the trigger, not a broken release.
if: (github.event.pull_request.head.repo.fork != true) && (github.event_name != 'pull_request' || !github.event.pull_request.draft)
name: desktop macOS ${{ matrix.os }}
runs-on: ${{ matrix.os }}
diff --git a/.github/workflows/lint-ci.yml b/.github/workflows/lint-ci.yml
index 67bf34e2e54..88fd27f9291 100644
--- a/.github/workflows/lint-ci.yml
+++ b/.github/workflows/lint-ci.yml
@@ -99,20 +99,13 @@ jobs:
bash .github/scripts/retry-with-apt-lock.sh sudo sh -c \
'apt-get install -y --no-install-recommends shellcheck || { apt-get update -qq && apt-get install -y --no-install-recommends shellcheck; }'
- # Every check below is read-only against the checkout and independent of the
- # others, so they run as one parallel group: the job waits for all of them at
- # the end of the group and fails if any one failed (an informational step keeps
- # its continue-on-error). They used to run one after another, about 150 s of
- # the job, and a failure in an early one hid every result after it.
- #
- # The two PR-only diff checks are NOT in the group: both run `git fetch` into
- # this shallow clone, and two concurrent fetches race on .git/shallow.lock.
+ # Read-only independent checks run as one parallel group that fails if any fails
+ # (informational steps keep continue-on-error); the two PR-only diff checks stay out, since
+ # concurrent git fetch calls race on .git/shallow.lock.
- parallel:
- name: Python AST/syntax check (every committed .py must compile)
- # python -m compileall uses the same parser the interpreter
- # uses, so anything broken here would also crash at
- # `import X` on a user's machine. Sub-second across 350+
- # files. Hard gate.
+ # python -m compileall uses the interpreter's own parser, so anything it rejects would
+ # also crash at import on a user's machine; sub-second across 350+ files; hard gate.
run: |
python -m compileall -q -j 0 \
unsloth unsloth_cli studio tests cli.py unsloth-cli.py
@@ -139,10 +132,9 @@ jobs:
run: python scripts/lint_risky_loaders.py
- name: Python ruff check (whole repo)
- # The narrow rule set in pyproject.toml [tool.ruff.lint]
- # selects E9 / F63 / F7 / F82 -- syntax errors, broken
- # comparisons, undefined names. The whole repo passes today,
- # so this is a hard gate.
+ # The narrow ruff rule set in pyproject.toml [tool.ruff.lint] selects E9, F63, F7 and
+ # F82 (syntax errors, broken comparisons, undefined names); the whole repo passes, so it
+ # is a hard gate.
run: |
ruff check unsloth unsloth_cli studio tests cli.py unsloth-cli.py
@@ -162,14 +154,9 @@ jobs:
python scripts/verify_import_hoist.py --self-test
- name: Duplicate-definition verifier self-test
- # scripts/lint_duplicate_definitions.py refuses a name bound twice in one
- # scope: two top-level copies of a def / class / constant, or a name
- # imported twice. That is what a bad merge resolution leaves behind, and
- # every other check here passes it -- compileall parses both copies, the
- # ruff rule set (E9 / F63 / F7 / F82) has no F811, and the two copies
- # usually differ only in their comments.
- # Runs the tool's self-test cases, positive and negative, so a regression in the
- # rule fails before we trust it on a diff. Stdlib-only, sub-second.
+ # lint_duplicate_definitions.py rejects names bound twice in one scope, which bad merges
+ # leave and compileall and the ruff set (no F811) both pass; its self-test runs first;
+ # stdlib only.
run: |
python scripts/lint_duplicate_definitions.py --self-test
@@ -190,11 +177,8 @@ jobs:
python scripts/lint_no_parallel_clamp.py
- name: No duplicate TypeScript import bindings
- # #8470 duplicated an import line in model-selector.tsx; tsc rejects it
- # with TS2300 and every job that builds the frontend goes red behind
- # it. eslint is not run in CI, so nothing saw it until tsc did, inside
- # the slowest job in the matrix. Self-test first, so a regression in
- # the rule fails before we trust it.
+ # A duplicated import in model-selector.tsx (#8470) made tsc fail with TS2300 and red
+ # every frontend build job, since CI does not run eslint; the self-test runs first.
run: |
python scripts/lint_no_duplicate_ts_imports.py --self-test
python scripts/lint_no_duplicate_ts_imports.py
@@ -339,10 +323,8 @@ jobs:
echo "$n shell scripts parse cleanly"
- name: YAML files parse cleanly (yaml.safe_load)
- # Catches truncated workflow files, broken indents in
- # dependabot.yml / pre-commit configs, etc. Includes
- # .github/workflows/*.yml so a typo in the file we just
- # added shows up immediately.
+ # Catches truncated workflow files and broken indents in dependabot.yml and pre-commit
+ # configs; includes .github/workflows YAML so a typo in a new workflow shows up at once.
run: |
python <<'PY'
import os, pathlib, subprocess
@@ -503,23 +485,9 @@ jobs:
--before "$MERGE_BASE" --after "$HEAD_SHA" "${CHANGED[@]}"
- name: Duplicate definitions (changed Python files)
- # Same merge-base reasoning as the import-hoist step above: diff the merge
- # base against the PR head SHA so the range is the PR's own commits and
- # not every base commit since the branch point.
- #
- # --diff-filter=ACMRT, not M: a bad resolution can just as easily land in a
- # file the PR adds, and a rename that also edits the file is reported as R
- # (R093 and so on), which an ACM filter would drop. T is there because a path
- # that changes TYPE -- a symlink replaced by a regular .py file -- is reported
- # as neither M nor A, so the newly active source reached the verifier as no
- # path at all and the step passed having checked nothing.
- #
- # The verifier scans BOTH revisions and compares findings by identity, so a
- # duplicate that was already in the file is printed and ignored while one
- # this PR introduced fails. Comparing added LINES instead would miss the
- # case where the new copy is inserted ABOVE the old one, since the finding
- # is reported at the second, unchanged definition. The whole-tree step below
- # catches pre-existing ones.
+ # Diffs the merge base to the PR head with --diff-filter=ACMRT, not M, so added files,
+ # renames and type changes are checked; findings compare by identity, so a duplicate
+ # inserted above the old copy is caught; pre-existing ones go to the whole-tree step.
if: github.event_name == 'pull_request'
env:
GH_TOKEN: ${{ github.token }}
diff --git a/.github/workflows/lockfile-audit.yml b/.github/workflows/lockfile-audit.yml
index be99101c287..2090d62a40a 100644
--- a/.github/workflows/lockfile-audit.yml
+++ b/.github/workflows/lockfile-audit.yml
@@ -13,10 +13,9 @@ on:
workflow_dispatch:
concurrency:
- # The event is part of the group so a scheduled run and a push to main cannot
- # coalesce. Both resolve to refs/heads/main, and the default queue: single keeps
- # only one pending run, so without this a merge burst silently drops the nightly:
- # cancel-in-progress protects the running run, never the pending one.
+ # The event name is in the group so a scheduled run and a push to main cannot coalesce (both
+ # resolve to refs/heads/main); queue: single keeps one pending run, so a merge burst would drop
+ # the nightly; cancel-in-progress only protects the running run.
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
# Latest-only on a PR branch. On main, cancel-in-progress is false so a RUNNING run is
# never killed, and a newer push replaces only the PENDING one: a merge burst runs the
diff --git a/.github/workflows/prebuilt-cuda-wheels.yml b/.github/workflows/prebuilt-cuda-wheels.yml
index 23b344f8cfe..b4622e36d51 100644
--- a/.github/workflows/prebuilt-cuda-wheels.yml
+++ b/.github/workflows/prebuilt-cuda-wheels.yml
@@ -381,9 +381,8 @@ jobs:
Get-CimInstance Win32_PageFileUsage | Format-Table Name, AllocatedBaseSize, CurrentUsage -AutoSize
Get-PSDrive -PSProvider FileSystem | Format-Table Name, @{n = 'FreeGB'; e = { [math]::Round($_.Free / 1GB, 1) } }, @{n = 'UsedGB'; e = { [math]::Round($_.Used / 1GB, 1) } } -AutoSize
- # 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.
+ # 10 GB of swap: nvcc's peak RSS on the sm_100 flash-attn kernels is why MAX_JOBS is 1, and
+ # swap keeps a job briefly over the runner's 16 GB from being OOM-killed hours in.
- name: Set up swap space
if: runner.os == 'Linux'
run: |
@@ -883,9 +882,8 @@ jobs:
echo "NVCC_APPEND_FLAGS=$NVCC_APPEND_FLAGS"
if [ -z "$FATBIN_FLAGS" ]; then echo "::error::FATBIN_FLAGS is empty"; exit 1; fi
if [ "$RUNNER_OS" = "Windows" ]; then
- # Git Bash puts /usr/bin first, and its coreutils `link.exe` (hard links) shadows MSVC's
- # linker: setuptools found it on PATH and every object compiled, then the final link
- # failed. MSVC's own bin goes back in front for this step.
+ # Git Bash puts /usr/bin first, so its coreutils link.exe (hard links) shadows MSVC's
+ # linker and the final link fails; MSVC's own bin is put back in front for this step.
host="Hostx64\\x64"
if [ "$WHEEL_PLATFORM" = "win_arm64" ]; then host="Hostarm64\\arm64"; fi
PATH="$(cygpath -u "${VCToolsInstallDir}bin\\${host}"):$PATH"
diff --git a/.github/workflows/studio-mac-ui-smoke.yml b/.github/workflows/studio-mac-ui-smoke.yml
index 19c33147e46..b34e22bba6c 100644
--- a/.github/workflows/studio-mac-ui-smoke.yml
+++ b/.github/workflows/studio-mac-ui-smoke.yml
@@ -160,10 +160,9 @@ jobs:
enableCrossOsArchive: true
- name: Install Playwright browsers
- # A background step, like the two cache restores after it: all three only
- # fetch into their own directories, so they run while Install Unsloth does.
- # The `wait-all` after the llama.cpp check settles them before any step reads
- # their outputs.
+ # Background step like the two cache restores after it: all three only fetch into their own
+ # directories, so they overlap Install Unsloth; wait-all after the llama.cpp check settles
+ # them before any step reads their outputs.
id: pw_install
background: true
# No --with-deps on Mac: that flag installs Linux apt packages.
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.yml
index 6968024291f..d640e232085 100644
--- a/.github/workflows/studio-ui-smoke.yml
+++ b/.github/workflows/studio-ui-smoke.yml
@@ -81,16 +81,9 @@ concurrency:
# Per workflow, ref and event: a merge burst runs the executing commit plus the tip.
# See studio-backend-ci.yml for the trade, and the note below.
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
- # On a PR branch: latest-only, which is what cancel-in-progress buys.
- #
- # On main it buys less than it looks like. GitHub cancels any PENDING run in a
- # concurrency group as soon as a newer one is queued, and cancel-in-progress
- # governs only runs that are already EXECUTING ("any existing pending job or
- # workflow in the same concurrency group will be canceled", workflow-syntax docs).
- # So a burst of merges leaves only the tip's run alive: on 2026-08-17 four merges
- # in 37 minutes cancelled three consecutive main runs of this workflow and none
- # completed. Detection survives on the tip, since the tree is cumulative;
- # per-commit attribution does not.
+ # On PR branches it gives latest-only; on main cancel-in-progress is off, and GitHub cancels every
+ # pending run once a newer one queues, so a merge burst leaves only the tip running; detection
+ # survives there, per-commit attribution does not.
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
permissions:
@@ -124,11 +117,9 @@ jobs:
GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
STUDIO_PORT: '18892'
HF_HOME: ${{ github.workspace }}/hf-cache
- # A llama.cpp, whisper.cpp or audio.cpp release published while this job runs leaves the prebuilt it
- # just installed one behind, and Studio then puts an update card in the bottom-right overlay rail, over
- # the composer the scripts click. Seen on main eb0617b6: audio.cpp v0.9.2 was published six minutes
- # after the job installed v0.9.1, and the IME script timed out on a click the card intercepted. These
- # scripts test chat, not live update checks; the update banner scripts stub the update routes.
+ # A llama.cpp, whisper.cpp or audio.cpp release published mid-run leaves the installed
+ # prebuilt behind and puts an update card over the composer the scripts click, so
+ # UNSLOTH_DISABLE_UPDATE_CHECK is set; update banner scripts stub the update routes.
UNSLOTH_DISABLE_UPDATE_CHECK: '1'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -226,38 +217,10 @@ jobs:
# for the dpkg lock. Its outcome, which the cache saves read, is settled by the
# `wait: pw-install` step after the install.
background: true
- # --with-deps stays unconditional: the apt side installs system libraries OUTSIDE
- # the cached directory, so a restored cache without it gives browsers that cannot
- # start. Only the download is skipped, which is the part that costs.
- #
- # Bounded and retried, because this step stalls. Three times in one day it sat in
- # apt's download loop until the job's 30-minute timeout killed it: the shards that
- # hit it took 30 minutes to report nothing, while their siblings finished the whole
- # job in 4 to 9. GitHub scores that as "cancelled" rather than a failure, prints no
- # reason, and skips every step after it, so an infrastructure hiccup costs a shard's
- # entire surface and reads like a mystery.
- #
- # A per-attempt `timeout` makes the stall a failure instead of a silent wait, and
- # the retry is what actually recovers -- both observed stalls cleared on a plain
- # re-run of the same commit. The healthy time is about 2 minutes, so 8 is 4x
- # headroom and a merely slow mirror will not trip it. timeout-minutes bounds the
- # pair in case `timeout` itself is outlived by an unkillable child.
- # Bounded and retried through the shared helper, which is where the dpkg
- # lock wait and the exit-code reporting live. This was eight lines of
- # inline loop and it shipped a bug that made the retry dead: GitHub runs
- # `run:` as `bash -e`, so `timeout ...; rc=$?` aborted the step on the
- # first stall and the second attempt never ran. The step exited 124 having
- # printed nothing at all, which looked exactly like the unbounded stall it
- # was supposed to replace. One definition, tested, instead of copies.
- #
- # Two attempts at 7 minutes, against a healthy ~2: worst case 14 plus the
- # lock wait, which still leaves the job's 30 room for the work it exists to
- # do. Three attempts here would not.
- # Two helper calls now, not one: the CDN download and the apt transaction
- # are separated, and each carries its own retry budget. 2 x 300s plus a lock
- # wait, twice over, is 24m of worst case against the job's 30 -- which is
- # why the per-attempt cap comes down from 420. Healthy is ~2 minutes for the
- # download and seconds for the probe, so 300 is still 2.5x headroom.
+ # --with-deps stays unconditional: apt installs libraries outside the cache, so a restored
+ # cache without it gives browsers that cannot start; retries go through the shared helper,
+ # not inline (bash -e killed the inline retry); 2 x 300 s attempts; apt stalled 3x in one
+ # day past the 30-minute timeout
timeout-minutes: 25
env:
RETRY_ATTEMPTS: '2'
diff --git a/.github/workflows/studio-update-smoke.yml b/.github/workflows/studio-update-smoke.yml
index 11cca10c1c7..632a6f870b2 100644
--- a/.github/workflows/studio-update-smoke.yml
+++ b/.github/workflows/studio-update-smoke.yml
@@ -152,9 +152,8 @@ jobs:
bash .github/scripts/retry-with-apt-lock.sh sudo sh -c \
'apt-get install -y --no-install-recommends libcurl4-openssl-dev libssl-dev jq || { apt-get update && apt-get install -y --no-install-recommends libcurl4-openssl-dev libssl-dev jq; }'
- # Node 24 ships npm 11, which meets setup.sh's floor (Node ^20.19 || >=22.12 with
- # npm >= 11): this job takes the system-Node path, the developer one. Node 22
- # ships npm 10 and would take the bundled path, which the other two jobs cover.
+ # Node 24 ships npm 11, which meets setup.sh's floor (Node ^20.19 or >=22.12, with npm >= 11),
+ # so this job takes the system-Node path; Node 22 ships npm 10 and takes the bundled path.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24'
diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index 0519f83a128..66003a3acea 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -101,16 +101,9 @@ jobs:
with:
persist-credentials: false
- # Fast GPU-free gate: parse install.ps1 + setup.ps1 and run the PowerShell
- # unit tests (CUDA-toolkit + torch-flavor helpers) before the heavy GGUF smoke.
- #
- # Background, together with the uninstall test below: about 60 s of pure
- # PowerShell that reads only the checkout, so it overlaps the node/python setup
- # and the ~90 s uv cache restore instead of running ahead of them. Both are
- # collected by the wait step right before Install Unsloth, so a failure still
- # stops the job before the install, as it did when they ran first; they are not
- # overlapped with the install itself, because test_mirror_fallback.ps1 asserts
- # deadlines and transfer speeds that a CPU-bound install next to it could skew.
+ # GPU-free gate: parses install.ps1 and setup.ps1 and runs their PowerShell unit tests in the
+ # background, collected before Install Unsloth; not overlapped with the install, since
+ # test_mirror_fallback.ps1 asserts timings a CPU-bound install could skew.
- name: PowerShell installer unit tests
id: ps-installer-units
background: true
diff --git a/.github/workflows/studio-windows-update-smoke.yml b/.github/workflows/studio-windows-update-smoke.yml
index 3958bddad9a..464515bde11 100644
--- a/.github/workflows/studio-windows-update-smoke.yml
+++ b/.github/workflows/studio-windows-update-smoke.yml
@@ -65,9 +65,8 @@ on:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
- # Latest-only on a PR branch. On main, cancel-in-progress is false so a RUNNING run is
- # never killed, and a newer push replaces only the PENDING one: a merge burst runs the
- # commit already executing plus the tip. See studio-backend-ci.yml for the trade.
+ # cancel-in-progress is PR-only: on main a running run is never killed and a newer push replaces
+ # only the pending one, so a merge burst runs the executing commit plus the tip.
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
permissions:
@@ -91,12 +90,9 @@ jobs:
with:
persist-credentials: false
- # This workflow triggers on uninstall.ps1; neither test really uninstalls.
- #
- # These three unit-test steps run in the background: they read only the
- # checkout, and together take about 20 s that now overlaps the node/python
- # setup and the ~90 s uv cache restore. The wait step right before Install
- # Unsloth collects them, so a failure still stops the job before the install.
+ # The workflow triggers on uninstall.ps1 but neither test uninstalls; the three unit-test
+ # steps run in the background since they only read the checkout, and the wait step before
+ # Install Unsloth collects them, so a failure still stops the job before install.
- name: uninstall.ps1 unit tests (argument guard, dual-install icon preserve)
id: ps-uninstall-units
background: true
diff --git a/.github/workflows/wheel-smoke.yml b/.github/workflows/wheel-smoke.yml
index bca1711f14b..ea2f7ce7397 100644
--- a/.github/workflows/wheel-smoke.yml
+++ b/.github/workflows/wheel-smoke.yml
@@ -32,9 +32,8 @@ on:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
- # Latest-only on a PR branch. On main, cancel-in-progress is false so a RUNNING run is
- # never killed, and a newer push replaces only the PENDING one: a merge burst runs the
- # commit already executing plus the tip. See studio-backend-ci.yml for the trade.
+ # Superseded runs are cancelled off main only; on main a running run is never killed, so a merge
+ # burst runs the executing commit plus the tip (see studio-backend-ci.yml).
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
permissions:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index da05bea81b8..90ccc29543c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -26,31 +26,22 @@ repos:
# half-process files ruff itself skips (which produced churn). vendor/ is
# repeated here because this hook does not read ruff's config.
exclude: '(chat_templates|ollama_template_mappers|_auto_install|mapper)\.py$|^studio/backend/vendor/|^unsloth/_vendor/'
- # ruff-unsloth is ruff 0.6.9 patched to write this repo's style itself:
- # `name = value` kwargs and defaults (measured as `=`, so lines break where
- # stock 0.6.9 breaks them), the def-signature and short-assert magic-comma
- # rules, and no blank line after the imports of a short nested block.
- # Source: https://github.com/unslothai/ruff (branch unsloth-0.6.9, see
- # UNSLOTH.md). Changing one of those rules means a new release there.
- # One wheel per platform, picked by the marker and checked by its sha256.
- # No marker tells musl from glibc, so on Alpine pip rejects the manylinux
- # wheel; the release also has a musllinux one to install by hand. Other
- # platforms install nothing and the script refuses with an install hint.
+ # ruff-unsloth is ruff 0.6.9 patched for this repo's style (name = value kwargs,
+ # def-signature and short-assert magic commas, nested-import blank lines); rule changes need
+ # a new release; sha256-checked per-platform wheels; Alpine needs the musllinux wheel by
+ # hand (no marker tells musl from glibc).
additional_dependencies:
- "ruff-unsloth @ https://github.com/unslothai/ruff/releases/download/v0.6.9-unsloth.1/ruff_unsloth-0.6.9.post1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl#sha256=866eb6575a00bc6ddeb37dc67ed4cd469e7250a3d118c2e4533b1d99be48fb9a ; sys_platform == 'linux' and platform_machine == 'x86_64'"
- "ruff-unsloth @ https://github.com/unslothai/ruff/releases/download/v0.6.9-unsloth.1/ruff_unsloth-0.6.9.post1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl#sha256=b375c841533dc0a5f8974915995970cb101ed9ce7af414c672a17c183310e3cc ; sys_platform == 'linux' and platform_machine == 'aarch64'"
- "ruff-unsloth @ https://github.com/unslothai/ruff/releases/download/v0.6.9-unsloth.1/ruff_unsloth-0.6.9.post1-py3-none-macosx_11_0_arm64.whl#sha256=5de72e6a4a22007a4d831785dabd6c362e30ec5ab90304e43d8831ae72770776 ; sys_platform == 'darwin' and platform_machine == 'arm64'"
- "ruff-unsloth @ https://github.com/unslothai/ruff/releases/download/v0.6.9-unsloth.1/ruff_unsloth-0.6.9.post1-py3-none-macosx_10_12_x86_64.whl#sha256=bd14fc7bc056a45804675b408480f0b42f8dfd4dc127213e9eb53fa42b5d7d33 ; sys_platform == 'darwin' and platform_machine == 'x86_64'"
- "ruff-unsloth @ https://github.com/unslothai/ruff/releases/download/v0.6.9-unsloth.1/ruff_unsloth-0.6.9.post1-py3-none-win_amd64.whl#sha256=0847fc1afffa899c918e162b93d04ff985fba4bf8fc7c5577608068d1fd95ebd ; sys_platform == 'win32' and platform_machine == 'AMD64'"
- # Serial: pre-commit used to start a partition per CPU, each with its own
- # multithreaded ruff, nproc x nproc threads on pre-commit.ci (#14174). A
- # long file list is still split into calls that run one after another;
- # each runs one ruff, and the script spreads the Python pass after it
- # over a bounded pool.
+ # Serial because per-CPU partitions each ran a multithreaded ruff, giving nproc x nproc
+ # threads on pre-commit.ci (issue 14174); long file lists run as sequential calls, each with
+ # one ruff, and the Python pass uses a bounded pool.
require_serial: true
- # Re-pins allowScripts entries after dependency bumps. pre-commit.ci
- # pushes the fix to PR branches, Dependabot's included, so stale pins
- # heal without a human in the loop.
+ # Re-pins allowScripts entries after dependency bumps; pre-commit.ci pushes the fix to PR
+ # branches, Dependabot's included, so stale pins heal without a human.
- id: sync-allow-scripts-pins
name: Sync allowScripts pins with the frontend lockfile
# `python <script>`, not a direct exec: autofix commits can drop the executable bit.
diff --git a/docker/jupyter/unsloth_labext/src/cellNav.ts b/docker/jupyter/unsloth_labext/src/cellNav.ts
index c7d867b638f..928ef7591bc 100644
--- a/docker/jupyter/unsloth_labext/src/cellNav.ts
+++ b/docker/jupyter/unsloth_labext/src/cellNav.ts
@@ -9,9 +9,8 @@ import { CodeMirrorEditor } from '@jupyterlab/codemirror';
import { INotebookTracker } from '@jupyterlab/notebook';
/**
- * Colab-style cell navigation: at a cell boundary, move to the next cell and align
- * its TOP to the viewport. JupyterLab centers tall cells instead, dropping the view
- * mid-output, and no setting changes that.
+ * Colab-style navigation: at a cell boundary, move to the next cell and align its top to the
+ * viewport, since JupyterLab centers tall cells and no setting changes that.
*/
const cellNavPlugin: JupyterFrontEndPlugin<void> = {
id: 'unsloth-jupyterlab:cell-nav',
diff --git a/docker/unsloth_nb_compat.py b/docker/unsloth_nb_compat.py
index 646df4b9b50..c8e38486013 100644
--- a/docker/unsloth_nb_compat.py
+++ b/docker/unsloth_nb_compat.py
@@ -107,10 +107,9 @@ def tier_for_model(model_name: str):
def sidecar_for(version: str):
- """FLOOR then CEILING: a sidecar the baked vLLM cannot import is never eligible
- whatever the notebook pinned, so a request below the floor clamps UP; among the
- eligible ones take the smallest >= the request, since a model added in X needs at
- least X. Above every eligible sidecar returns None, i.e. the base venv."""
+ """Sidecars the baked vLLM cannot import are never eligible and a request below the floor clamps
+ up; the smallest eligible one >= the request wins (a model added in X needs at least X), else
+ None."""
if not version:
return None
rows = _eligible()
@@ -258,12 +257,9 @@ def _install_lines(src):
def pin_in_cell(source):
- """transformers version pinned by an install command IN this cell, else None.
-
- Same scan unsloth_run runs over a whole notebook, applied to one cell. Anything
- that installs nothing has to lose: once transformers is imported the sidecar
- choice is frozen for the life of the kernel, so a wrong guess is unrecoverable
- while no guess merely leaves the base venv."""
+ """Returns the transformers version pinned by an install in this cell (same scan as
+ unsloth_run), else None; a wrong guess is unrecoverable since transformers freezes the
+ sidecar choice on import, while no guess just uses the base venv."""
if not source:
return None
return pin_from(_live_source(source))
diff --git a/docker/unsloth_nb_strip_colab.py b/docker/unsloth_nb_strip_colab.py
index 283ddeeff8e..d1dbafdb47d 100644
--- a/docker/unsloth_nb_strip_colab.py
+++ b/docker/unsloth_nb_strip_colab.py
@@ -26,9 +26,8 @@ _WIDGET_VIEW_MIME = "application/vnd.jupyter.widget-view+json"
def _is_intro_line(line):
- """True for the Colab run announcement, bare or inside a single-line HTML comment.
- Only a comment that OPENS AND CLOSES on one line matches, so dropping it can never
- leave a dangling `<!--` that swallows the rest of the cell."""
+ """True for the Colab run announcement, bare or in a one-line HTML comment; only a comment that
+ opens and closes on one line matches, so no dangling <!-- can swallow the cell."""
stripped = line.strip()
low = stripped.lower()
if low.startswith(_INTRO_PREFIX):
@@ -132,11 +131,9 @@ def _unlink(path):
def _stage_clean(path):
- """(tmp, hash_before, hash_after) for a cleaned copy written beside the notebook but
- NOT published, or None when there was nothing to change or the write failed.
-
- Split out of strip_notebook so migrate can record the new hash before the notebook
- carries it."""
+ """Returns (tmp, hash_before, hash_after) for a cleaned copy staged beside the notebook but not
+ published, or None if nothing changed or the write failed; split out so migrate can record
+ the new hash first."""
try:
before = _sha256(path)
with open(path, "r", encoding = "utf-8") as f:
@@ -176,10 +173,8 @@ def _publish(tmp, path, before):
def _write_state(state_path, lines):
- """Replace the state file durably; False when it could not be written.
-
- fsync before the rename, because a crash between the two makes the rename visible
- with the content unwritten, which strands the notebooks the same way."""
+ """Replaces the state file durably, returning False on failure; fsync runs before the rename,
+ since a crash between them would leave the rename visible with the content unwritten."""
tmp = state_path + ".tmp"
try:
with open(tmp, "w", encoding = "utf-8") as f:
@@ -194,15 +189,9 @@ def _write_state(state_path, lines):
def _resume(path, rec):
- """Finish a publish that was interrupted after its record landed. True if it did.
-
- Recording before publishing closes the window that stranded the whole set at once,
- but it leaves a one-notebook window of its own: a stop between os.replace on the
- state file and os.replace on the notebook leaves `rec` describing the cleaned bytes
- while the file still holds the pristine ones, and every later run reads that
- mismatch as a user edit and carries the stale record forward forever. Cleaning what
- is actually on disk tells the two apart, because only the interrupted case
- reproduces `rec` byte for byte; a real edit cannot, so nothing else is touched."""
+ """Finishes a publish interrupted between the state and notebook renames, True if it did; that
+ stop would otherwise read as a user edit, and only that case reproduces the record byte for
+ byte."""
st = _stage_clean(path)
if st is None:
return False
@@ -236,21 +225,8 @@ def _sha256(path):
def migrate(state_path, dest):
- """Clean every notebook the state file says we own, recording each one BEFORE it is
- published.
-
- Publishing the whole set first and then writing the state once meant that losing
- that single write left every cleaned notebook no longer matching its record. The
- refresh reads a hash mismatch as a user edit and carries the stale record forward,
- so upstream updates stop reaching those notebooks permanently, while this reports
- success. It is not a one-notebook risk either: on the first boot after this ships,
- migrate cleans the entire set in one pass, so a docker stop or an ENOSPC anywhere
- in that window stranded all of them at once.
-
- Ordering it the other way is safe in the direction that matters. If the state write
- fails, nothing has been published and the disk still matches the record, so the next
- start simply tries again. The narrow window that is left, a stop between the two
- renames, is reconciled by _resume rather than mistaken for a user edit."""
+ """Cleans every owned notebook, recording each in the state file before it is published, so one
+ lost state write cannot strand the set; a stop between the renames is reconciled by _resume."""
try:
with open(state_path, "r", encoding = "utf-8") as f:
lines = f.read().splitlines()
diff --git a/docker/unsloth_pip_shim.py b/docker/unsloth_pip_shim.py
index 35b4d8b5203..4c28284cdf0 100644
--- a/docker/unsloth_pip_shim.py
+++ b/docker/unsloth_pip_shim.py
@@ -341,9 +341,8 @@ def _canon(token):
def _local_project_name(token):
- """Name pip/uv would build for a local project dir, falling back to the basename
- only when the dir is an installable project at all. None for a metadata-less dir,
- so ordinary paths pass through."""
+ """Name pip or uv would build for a local project dir, falling back to the basename only for an
+ installable project; None for a metadata-less dir so ordinary paths pass through."""
# Resolve from uv's --directory, not our cwd, or the project is misclassified as unknown.
path = _resolve_read_path(token.split("#", 1)[0])
if not os.path.isdir(path):
@@ -377,11 +376,8 @@ def _local_project_name(token):
def _marker_is_false(token):
- """True when this requirement carries a PEP 508 marker that does not hold here.
-
- Both real tools then skip it entirely, so it pins nothing and must not reach the
- sidecar marker file. packaging is treated as optional, as it is elsewhere: if it
- is missing or the token does not parse, nothing is vetoed."""
+ """True when the PEP 508 marker fails here: pip and uv skip such a requirement, so it must not
+ reach the sidecar marker file; without packaging, or on a parse error, nothing is vetoed."""
try:
from packaging.requirements import Requirement
req = Requirement(token)
@@ -547,10 +543,9 @@ def _uv_working_dir(tool, argv):
def _resolve_read_path(path):
- """Read a relative requirements path from where the real tool will read it.
- Reading it from our cwd instead makes open() miss, and a miss is silent: the
- original relative path is forwarded unfiltered and uv, now chdir'd, installs a
- file we never inspected and never recorded a transformers pin from."""
+ """Resolves a relative requirements path against the real tool's working dir; reading from our
+ cwd would miss silently, forwarding an unfiltered file uv installs without recording its
+ transformers pin."""
if not _WORKING_DIR or os.path.isabs(path):
return path
return os.path.join(_WORKING_DIR, path)
@@ -939,11 +934,10 @@ def _uninstall(tool, argv, i):
def _positionals(argv):
- """(index, token) for every positional, skipping options AND their values.
-
- `--flag=value` carries its own value; a bare value flag eats the next token.
- _VALUE_FLAGS is the same set the tail scanner uses and _selfcheck_value_flags()
- holds it to the real CLIs at build time."""
+ """Returns (index, token) for every positional, skipping options and their values; --flag=value
+ carries its own value while a bare value flag eats the next token; _VALUE_FLAGS is shared
+ with the tail scanner and checked against the real CLIs at build time by
+ _selfcheck_value_flags()."""
out = []
skip = False
for i, tok in enumerate(argv):
@@ -959,12 +953,9 @@ def _positionals(argv):
def _is_uv_pip_sync(argv):
- """`uv pip sync` is an install path we cannot make safe by filtering.
-
- It UNINSTALLS every package absent from the requirements file, so unlike install
- there is nothing to strip: keeping a protected package out of the file is exactly
- what deletes it, and --constraint only bounds versions, never prevents a removal.
- """
+ """uv pip sync cannot be made safe by filtering: it uninstalls every package absent from the
+ requirements file, so keeping a protected package out deletes it, and --constraint never
+ prevents removal."""
return [tok for _, tok in _positionals(argv)][:2] == ["pip", "sync"]
diff --git a/docker/unsloth_run.py b/docker/unsloth_run.py
index bd813981e61..bbd595801c9 100644
--- a/docker/unsloth_run.py
+++ b/docker/unsloth_run.py
@@ -33,11 +33,8 @@ DEFAULT_FETCH_TIMEOUT = int(os.environ.get("UNSLOTH_NOTEBOOK_FETCH_TIMEOUT", "60
def _load(path_or_url, fetch_timeout = None):
- """Parsed notebook. A URL is fetched with a socket timeout: --timeout only ever
- reached nbconvert, so a host that accepted the connection and then went quiet hung
- the run before a single cell had executed. This bounds each blocking socket
- operation, not the total transfer, which is what that failure needs; a server
- trickling bytes forever is a different problem and not one seen here."""
+ """Returns the parsed notebook; URLs use a socket timeout because --timeout only reached
+ nbconvert and a host that went quiet hung the run; total transfer time is not bounded."""
if path_or_url.startswith(("http://", "https://")):
if fetch_timeout is None:
fetch_timeout = DEFAULT_FETCH_TIMEOUT
@@ -103,9 +100,8 @@ def _stage_metadata(
dest,
owner_ids = None,
):
- """Give the staged output the metadata the destination must end up with: mkstemp()
- creates 0600, nbconvert truncates that same inode, and os.replace carries it onto
- the destination. Best effort."""
+ """Gives the staged output the destination's metadata: mkstemp() creates 0600, nbconvert
+ truncates that same inode, and os.replace carries it onto the destination; best effort."""
try:
st = os.stat(dest)
except OSError:
diff --git a/scripts/build_ltx25_te_int8_convrot.py b/scripts/build_ltx25_te_int8_convrot.py
index 3f6ca386ba6..188abf16add 100644
--- a/scripts/build_ltx25_te_int8_convrot.py
+++ b/scripts/build_ltx25_te_int8_convrot.py
@@ -88,9 +88,7 @@ def build(
raise SystemExit(f"expected the at-load build, got {config.get('_te_source')!r}")
quantized = sum(1 for m in model.modules() if isinstance(m, _int8_convrot_linear_class()))
state = model.state_dict()
- # The tied head is the embedding under a second name; the loader re-ties it, so it never gets a key of its own.
- # The dead-tail trim normally drops it already, but a kept head (or a trim that did not engage) must not ship a
- # second 262k-vocab copy.
+ # Tied lm_head is the embedding again: the loader re-ties it, so drop it before shipping.
if _head_is_tied(state):
state.pop("lm_head.weight")
tensors = {k: v.detach().to("cpu").contiguous() for k, v in state.items()}
diff --git a/scripts/build_prequant_checkpoint.py b/scripts/build_prequant_checkpoint.py
index 85ba740b0a7..0199930b69b 100644
--- a/scripts/build_prequant_checkpoint.py
+++ b/scripts/build_prequant_checkpoint.py
@@ -28,12 +28,8 @@ def resolve_build_family(base: str, override: Optional[str] = None) -> Optional[
def convrot_refusal(
group: int, rotatable: Sequence[str], not_divisible: Sequence[str]
) -> Optional[str]:
- """Why a ConvRot build must not be quantised and saved, or None when it is fine.
-
- An empty rotatable set means the group divides no quantized input axis (a group larger than
- every Linear, say). The build would still stamp the v2 tag and an empty fqn list, which
- ``rotation_metadata_error`` refuses at load time, so the only thing it produces is a
- multi-gigabyte artifact nothing can ever open. Refuse before the hours, not after."""
+ """Refuse a ConvRot build with no rotatable Linear before the hours of quantising, not after:
+ its empty fqn list is refused at load time, leaving an unopenable artifact"""
if rotatable:
return None
return (
diff --git a/scripts/build_te_prequant_checkpoint.py b/scripts/build_te_prequant_checkpoint.py
index 329c31a11e0..4cb7b40957c 100644
--- a/scripts/build_te_prequant_checkpoint.py
+++ b/scripts/build_te_prequant_checkpoint.py
@@ -72,8 +72,7 @@ def main(argv = None) -> int:
p.error("--loader ideogram4 reads <base>/text_encoder only")
from core.inference.diffusion_ideogram4 import load_ideogram4_text_encoder
- # The exact module the runtime builds (vendor fp8 dequantized to bf16, rope remapped), so the cast below
- # matches dense-load-then-cast in Studio.
+ # Same module Studio builds, so the cast below matches its dense-load-then-cast.
encoder = load_ideogram4_text_encoder(args.base, torch.bfloat16, hf_token = args.hf_token)
encoder_cls_name = type(encoder).__name__
else:
diff --git a/scripts/clef_train_bench.py b/scripts/clef_train_bench.py
index 5366fc07110..9612989a713 100644
--- a/scripts/clef_train_bench.py
+++ b/scripts/clef_train_bench.py
@@ -93,10 +93,9 @@ def rows(tokenizer, count):
def head_parity(model, batch, amp):
- # Same hidden states into the batched and the per-record head. Each is scored against the
- # per-record head with autocast off (fp32 head, the oracle): under bf16 autocast both heads
- # round their matmuls, so the batched head passes when its error is at most 1.5x the
- # per-record head's plus one bf16 rounding step (kernel_verify_workflow step 2).
+ # Each head is scored against the per-record fp32 oracle with autocast off, since under bf16
+ # autocast both round their matmuls; batched passes if its error is at most 1.5x per-record plus
+ # one bf16 rounding step
backbone = model._backbone()
text_model = getattr(backbone.model, "language_model", backbone.model)
with torch.no_grad():
diff --git a/scripts/enforce_kwargs_spacing.py b/scripts/enforce_kwargs_spacing.py
index a7e4f2885b0..73a1c2a264e 100755
--- a/scripts/enforce_kwargs_spacing.py
+++ b/scripts/enforce_kwargs_spacing.py
@@ -69,9 +69,7 @@ def _atomic_write_text(path: Path, data: str, encoding: str) -> None:
raise
-# The entry points below use a stage-local analysis, never a persistent file or
-# string cache. The _reference_* paths at the end of the file cover malformed
-# input, unusual line separators, and syntax the sparse lexer does not know.
+# Entry points use stage-local analysis, no persistent cache; _reference_* handles edge cases.
def _without_gc(fn):
@@ -96,14 +94,12 @@ def _without_gc(fn):
_ODD_LINES = re.compile(r"[\r\v\f\x1c-\x1e\x85\u2028\u2029]")
-# Anything that could open a 3.14 template string (t"", tr"", rt""), anywhere in the
-# text, strings and comments included: the sparse lexer below knows no t-strings.
+# Any 3.14 t-string prefix (t, tr, rt) anywhere in text: the lexer below knows none of them.
_TSTRING_PREFIX = re.compile(r"(?<![\w])(?:[tT][rR]?|[rR][tT])['\"]")
def _ordinary(text):
- # splitlines() and Python's physical-line numbering disagree on these.
- # Retain even the reference's erroneous indexing for that input.
+ # splitlines() and Python line numbers disagree; keep the reference's erroneous indexing.
if _ODD_LINES.search(text):
return False
return sys.version_info < (3, 14) or not _TSTRING_PREFIX.search(text)
@@ -145,8 +141,7 @@ def _def_edits(lines, nodes):
continue
count, has_default = _def_spec(node)
force = count >= _DEF_MIN_PARAMS_FOR_MULTILINE and has_default
- # Read only the header; the generator is stopped at its closing paren.
- # Including the first body line supports a one-line suite.
+ # Read only the header; include the first body line so one-line suites work.
lo = node.lineno - 1
source = "".join(lines[lo : node.body[0].lineno])
depth = 0
@@ -156,14 +151,12 @@ def _def_edits(lines, nodes):
if not seen_def:
seen_def = tok.type == tokenize.NAME and tok.string == "def"
if seen_def and tok.start[0] != 1:
- # An explicit continuation between async and def gives
- # different keyword rows; the reference misses that def.
+ # Continuation between async and def; the reference misses that def.
break
continue
if not depth:
if tok.type == tokenize.OP and tok.string == "[":
- # PEP 695: the reference searches the first '(', even if it
- # belongs to a type parameter bound. Keep its AST guard.
+ # PEP 695: reference may find a bound's '('; keep its AST guard.
return None
if tok.type != tokenize.OP or tok.string != "(":
continue
@@ -216,12 +209,10 @@ def _assert_edits(lines, nodes):
if node.col_offset != len(first) - len(first.lstrip()) or (
lo > 1 and lines[lo - 2].rstrip("\r\n").endswith("\\")
):
- # Another statement shares the first row, or the row continues the line
- # above: the rows alone would parse as something else (`obj\` + `[1,]`
- # is a subscript in the file but a list here). The whole-file check decides.
+ # Shared first row or a line continued from above can parse differently; whole-file
+ # check decides.
return None
- # Shared physical rows require the reference's sequential whole-file
- # checks. They are uncommon (semicolon suites spanning multiple lines).
+ # Shared physical rows defer to the reference's whole-file checks, as they are rare.
if occupied.intersection(range(lo, hi + 1)):
return None
occupied.update(range(lo, hi + 1))
@@ -235,8 +226,7 @@ def _assert_edits(lines, nodes):
and t.start[0] != t.end[0]
for t in tokens
):
- # Dedenting an isolated statement can alter a multiline string
- # value. Leave this unusual case to the whole-file guard.
+ # Dedenting can alter a multiline string; leave it to the whole-file guard.
return None
significant = [t for t in tokens if t.type not in _STRING_TRIVIA]
positions = [
@@ -302,12 +292,9 @@ def _reference_pre(text, definitions, assertions):
return text, changed
-# A sparse lexer for VALID Python. The AST parser has already validated the
-# input. We only need comments, string literals, and standalone '=' operators.
-# F-strings use the running interpreter's tokenizer, up to their matching END;
-# this deliberately preserves the Python 3.10/3.11 versus 3.12+ distinction.
-# Unrolled (`a*(?:b a*)*`, not `(?:a|b)*`): the alternation kept one backtracking
-# frame per character, about 120 bytes each, so a 10 MB literal took 1.2 GB.
+# Unrolled, not (?:a|b)*: the alternation cost a backtrack frame per char, so 10 MB took 1.2 GB;
+# f-strings use the running interpreter tokenizer up to their matching END, keeping the 3.10/3.11 vs
+# 3.12+ distinction.
_QUOTE = (
r'''(?:"""[^"\\]*(?:(?:\\[\s\S]|"(?!""))[^"\\]*)*"""'''
r"""|\'\'\'[^\'\\]*(?:(?:\\[\s\S]|\'(?!\'\'))[^\'\\]*)*\'\'\'"""
@@ -456,8 +443,7 @@ def _pass_nodes(tree):
node = todo.pop()
for attr in ("body", "orelse", "finalbody"):
suite = getattr(node, attr, None)
- # Deliberately preserve the reference's single-statement-suite
- # recursion bug and its omission of match-case bodies.
+ # Keeps the reference's one-statement-suite recursion bug and its match-case gap.
if not isinstance(suite, list) or len(suite) <= 1:
continue
redundant.extend(s for s in suite if isinstance(s, ast.Pass))
@@ -488,10 +474,8 @@ def _merge_edits(text, lines, starts, strings, insertions, nodes):
previous_end, previous_row = end, lastrow
if len(current) > 1:
runs.append(current)
- # A u prefix anywhere in a concatenation decides the `kind` of the constants an
- # f-fold produces, and the rest of that concatenation can sit outside the run
- # (`(f"" u""` + newline + `"a")`), so no check on the run alone can see it.
- # `u` combines with no other prefix, so a piece's first character tells.
+ # A u prefix anywhere in the concatenation sets the folded constants' kind, even outside the
+ # run.
has_u = any(text[start] in "uU" for _kind, start, _end in strings)
edits = []
for run in runs:
@@ -513,13 +497,8 @@ def _merge_edits(text, lines, starts, strings, insertions, nodes):
continue
original = lines[row - 1][c0:c1]
try:
- # Include parentheses to handle implicit concatenation and use AST
- # dumps only for these small expressions. With u prefixes ruled out
- # above, the pieces outside the run concatenate to the same values
- # either way, so local equality is a sufficient proof; local
- # inequality is NOT proof of file-level inequality (two changes in a
- # larger concatenation may cancel). Defer that case to the
- # reference's all-or-nothing global guard.
+ # Local AST equality proves the merge safe, given u prefixes are ruled out above; local
+ # inequality is not proof and defers to the reference global guard.
before = ast.parse("(" + original + ")", mode = "eval")
after = ast.parse("(" + merged + ")", mode = "eval")
if ast.dump(before) != ast.dump(after):
@@ -545,8 +524,7 @@ def _post(
return _reference_post(text, spacing, blanks, merging, passes)
tree = _tree(text)
if tree is None:
- # enforce_spacing historically tokenizes even invalid syntax and can
- # raise TokenError/IndentationError; the other passes return unchanged.
+ # enforce_spacing can raise on bad syntax; other passes return the text unchanged.
return _reference_post(text, spacing, blanks, merging, passes)
lines = text.splitlines(True)
if not lines:
@@ -556,8 +534,7 @@ def _post(
try:
equals, strings = _lex(text) if spacing or merging else ((), ())
except (tokenize.TokenError, SyntaxError):
- # The f-string scan runs the real tokenizer from mid-file; should it ever
- # disagree with the parser, the reference path decides, as for bad syntax.
+ # If the f-string scan disagrees with the parser, the reference path decides.
return _reference_post(text, spacing, blanks, merging, passes)
original_lines = lines[:]
insertions = _space(lines, starts, equals) if spacing else {}
@@ -566,8 +543,7 @@ def _post(
if edits is None:
return _reference_post(text, spacing, blanks, merging, passes)
redundant = _pass_nodes(tree) if passes and "pass" in text else []
- # Convert insertions/replacements to UTF-8 byte coordinates ONLY for pass
- # nodes. Preserve the reference's byte-column-as-character-column behavior.
+ # Only pass nodes use UTF-8 byte coordinates; the reference's column quirk is kept.
shifts = defaultdict(list)
for node in redundant:
row = node.lineno - 1
@@ -657,8 +633,7 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
return _post(text, spacing = False, blanks = False, merging = False)
-# A closing quote, blanks, then an opening one: every same-line implicit concatenation
-# matches, and so does `" ".join`. The lexer below settles which it is.
+# Quote-blank-quote matches implicit concatenation and " ".join; the lexer decides.
_ADJACENT_QUOTES = re.compile(r"""['"][ \t]+(?:[rRuUbBfF]{1,2})?['"]""")
_PASS_ROW = re.compile(r"^([ \t]*)pass[ \t]*(?:#.*)?$", re.MULTILINE)
@@ -760,8 +735,7 @@ def process_file(
return changed
-# Shared literal policy and exact compatibility paths. These are deliberately
-# retained so exceptional source keeps the reference behavior, including bugs.
+# Reference compatibility paths kept deliberately, including bugs, for exceptional source.
def _reference_enforce_spacing(text: str) -> tuple[str, bool]:
diff --git a/scripts/lockfile_supply_chain_audit.py b/scripts/lockfile_supply_chain_audit.py
index b1a8971e000..3d115fe46c9 100644
--- a/scripts/lockfile_supply_chain_audit.py
+++ b/scripts/lockfile_supply_chain_audit.py
@@ -87,8 +87,7 @@ BLOCKED_NPM_VERSIONS: dict[str, set[str]] = {
"@tanstack/zod-adapter": {"1.166.12", "1.166.15"},
# Mini Shai-Hulud May-12 wave: OpenSearch JS client.
"@opensearch-project/opensearch": {"3.5.3", "3.6.2", "3.7.0", "3.8.0"},
- # Mini Shai-Hulud May-12 wave: @squawk/* (22 packages, 5 versions each;
- # https://safedep.io/mass-npm-supply-chain-attack-tanstack-mistral/).
+ # Mini Shai-Hulud May-12 wave: @squawk/* (22 packages, 5 versions each).
"@squawk/airport-data": {"0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.8"},
"@squawk/airports": {"0.6.2", "0.6.3", "0.6.4", "0.6.5", "0.6.6"},
"@squawk/airspace": {"0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5"},
@@ -111,8 +110,7 @@ BLOCKED_NPM_VERSIONS: dict[str, set[str]] = {
"@squawk/types": {"0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5"},
"@squawk/units": {"0.4.3", "0.4.4", "0.4.5", "0.4.6", "0.4.7"},
"@squawk/weather": {"0.5.6", "0.5.7", "0.5.8", "0.5.9", "0.5.10"},
- # Mini Shai-Hulud May-12 wave: @uipath/* (64 packages, single version each;
- # https://www.aikido.dev/blog/mini-shai-hulud-is-back-tanstack-compromised).
+ # Mini Shai-Hulud May-12 wave: @uipath/* (64 packages, single version each).
"@uipath/apollo-react": {"4.24.5"},
"@uipath/apollo-wind": {"2.16.2"},
"@uipath/cli": {"1.0.1"},
diff --git a/scripts/notebook_validator.py b/scripts/notebook_validator.py
index 2e8a37c80e8..9b465c8ebca 100644
--- a/scripts/notebook_validator.py
+++ b/scripts/notebook_validator.py
@@ -435,10 +435,7 @@ _PRERELEASE_ORDER = {
def _prerelease_key(version: str) -> tuple[int, int]:
- """How a version's prerelease suffix sorts: the release itself is above every one.
-
- Reading the suffix's digits as another component put `0.12.0rc1` above `0.12.0`, so a floor the
- cell upgrades past looked already met."""
+ """Prerelease sorts below its release; its suffix digits must not count as an extra component."""
core, is_pre = _split_prerelease(version)
if not is_pre:
return (len(_PRERELEASE_ORDER) + 1, 0)
@@ -1289,10 +1286,7 @@ def _fold_and_or(assured: list[bool], prev_ops: list[str], piece_is_pip: bool) -
def _fold_status(left: bool | None, op: str, right: bool | None) -> bool | None:
- """The exit status of `left OP right`, or None when it cannot be known.
-
- Left-associative: the left operand of `a || b && c` is the whole `(a || b)` list, and its
- folded status, not the piece nearest the operator, decides whether `c` runs."""
+ """Exit status of left OP right; operators are left-associative, so the folded left list decides."""
if op == "&&":
if left is None:
return False if right is False else None # `? && false` fails either way
@@ -1310,10 +1304,7 @@ def _left_hand_status(
notebook_bang: bool = True,
spoken_for: bool = False,
) -> bool | None:
- """Fold the piece in hand into its level's running status and return the result.
-
- Called at each `&&`/`||` so the operator sees the status of everything to its left, not just
- the piece beside it."""
+ """Folds the piece into the level's running status, so each operator sees everything to its left."""
if spoken_for or not _unwrap_shell_group(pending)[0].strip():
# A group just closed; the level already carries its status.
return models[-1]
@@ -1345,10 +1336,7 @@ def _for_list_is_nonempty(text: str) -> bool:
def _word_may_vanish(word: str) -> bool:
- """Could this loop word expand to something other than itself, nothing included?
-
- Single quotes make every character literal; double quotes still expand `$` and a backquote but
- never a glob. Only what is left unquoted can be a glob."""
+ """Can this word expand, given quotes? Only unquoted text can glob; double quotes still expand $."""
i = 0
while i < len(word):
ch = word[i]
@@ -1368,11 +1356,7 @@ def _word_may_vanish(word: str) -> bool:
def _invoked_name(piece: str) -> str:
- """The word this piece runs, read WITHOUT stripping execution prefixes.
-
- `env f`, `nohup f` and `command f` look for an executable named f, so none reaches a shell
- function and stripping them made every wrapper look like a call. Brackets, a function header
- and the body keywords do come off: they precede the command rather than replace it."""
+ """Word a piece runs, keeping env/nohup/command prefixes: they look up executables, not functions."""
text = piece.lstrip("!").strip()
while text[:1] in ("(", "{"):
text = text[1:].lstrip()
@@ -1394,10 +1378,7 @@ def _invoked_name(piece: str) -> str:
def _behind_keywords(text: str) -> str:
- """`then f(` -> `f(`. The words a compound statement opens with are not the command.
-
- A definition can sit behind them, and `then f` matched no header, so the body was tracked as a
- plain group."""
+ """Strip compound-statement keywords like then so a function definition behind them is still seen."""
text = text.lstrip("!").strip().lstrip("({").lstrip()
while True:
parts = text.split(maxsplit = 1)
@@ -1518,8 +1499,7 @@ def _split_chained(line: str) -> list[tuple[str, bool]]:
buf.append(line[i + 1])
i += 2
elif ch == "`" and quote != "'":
- # Backticks expand inside double quotes as well, so this is checked before the
- # quote branch; only single quotes make them literal.
+ # Backticks expand in double quotes too, so check them before the quote branch.
in_backtick = not in_backtick
buf.append(ch)
i += 1
@@ -2367,9 +2347,7 @@ def _install_cell_lower_bound(
def _compatible_release_ceiling(version: str) -> str | None:
- """The exclusive ceiling `~=version` implies: `~=2.10.0` allows `<2.11`, `~=2.10` `<3`.
-
- PEP 440 drops the last component and increments what is then last."""
+ """Upper bound of ~=version: drop the last component and increment what remains (PEP 440)."""
parts = normalise_version(version).split(".")
if len(parts) < 2:
return None
@@ -2414,10 +2392,7 @@ def _archive_requirement(argument: str) -> tuple[str, str | None] | None:
def cmp_releases(a: str, b: str) -> int:
- """`cmp_versions` with the release segments padded, as PEP 440 compares them.
-
- Stopping at the shorter tuple reads `0.11.0` as above `0.11`, which is harmless for ordering
- and wrong wherever the question is whether two spellings name the same release."""
+ """Pads release segments as PEP 440 does, so 0.11.0 equals 0.11 rather than sorting above it."""
left = [int(part) for part in re.findall(r"\d+", normalise_version(a))]
right = [int(part) for part in re.findall(r"\d+", normalise_version(b))]
width = max(len(left), len(right))
@@ -2427,10 +2402,7 @@ def cmp_releases(a: str, b: str) -> int:
def _exclusion_covers_minor(version: str, exclusion: str) -> bool:
- """True when `!=exclusion` rules out every release in `version`'s minor.
-
- Only a wildcard can: `!=0.11.*` takes the whole 0.11 line, while `!=0.11` and `!=0.11.1.*` each
- remove one release or one patch line and leave the minor reachable."""
+ """Only a wildcard exclusion like !=0.11.* rules out a whole minor; !=0.11 or !=0.11.1.* do not."""
wanted = normalise_version(exclusion).split(".")
if not wanted or wanted[-1] != "*":
return False
@@ -2516,10 +2488,7 @@ def _is_dry_run(inv: "PipInvocation") -> bool:
def _forces_resolution(flags: set[str]) -> bool:
- """True when any flag makes pip re-resolve rather than keep what is installed.
-
- Short options bundle: pip takes `-Uq` and parse_pip_line keeps it as one token, so the letters
- are compared rather than the token."""
+ """Any flag that forces pip to re-resolve; short options bundle (-Uq), so compare letters."""
if flags & _RESOLVE_ANYWAY_LONG:
return True
return any(
diff --git a/scripts/quant_probe.py b/scripts/quant_probe.py
index 7be8119ba14..c7679ae4081 100644
--- a/scripts/quant_probe.py
+++ b/scripts/quant_probe.py
@@ -28,10 +28,9 @@ _LPIPS = {"fn": None}
def _lpips(ref_arr, arr):
- """Perceptual LPIPS (alexnet) vs reference; lower is closer. None if unavailable.
-
- Runs on CPU so the scorer never holds CUDA memory: each row resets peak VRAM, so a
- resident GPU LPIPS module would inflate the reported load/gen VRAM and could even OOM."""
+ """Perceptual LPIPS (alexnet) distance, lower is closer; None if unavailable. Runs on CPU so the
+ scorer never holds CUDA memory: a resident GPU module would inflate per-row peak VRAM and
+ could OOM."""
try:
import torch
import lpips
@@ -108,9 +107,8 @@ def _quant_config(name):
def _make_filter_fn(min_features):
- """Keep only the FLOP-heavy linears: nn.Linear with both in/out >= min_features.
- The int8 dynamic path uses torch._int_mm (needs activation M>16), and the tiny
- timestep/pooled projections (in_features=256) run at M=1 and crash it -- skip them."""
+ """Keep only nn.Linear layers with both in and out >= min_features; torch._int_mm needs
+ activation M>16, so tiny M=1 projections crash it and are skipped."""
import torch.nn as nn
def filter_fn(module, fqn = ""):
diff --git a/scripts/run_ruff_format.py b/scripts/run_ruff_format.py
index d8cc8770444..a99c599f52f 100755
--- a/scripts/run_ruff_format.py
+++ b/scripts/run_ruff_format.py
@@ -15,8 +15,7 @@ CONFIG = HERE.parent / ".pre-commit-config.yaml"
# One-off experiments only: commits made under it get reformatted by the hook.
ANY_VERSION_ENV = "UNSLOTH_RUFF_FORMAT_ANY_VERSION"
USAGE = "usage: run_ruff_format.py FILE [FILE ...] (formats in place; no options)"
-# Worker count for the Python pass after ruff. The hook is require_serial (#14174), so
-# these chunks are the only parallelism; ruff itself runs once.
+# Worker count; the hook is require_serial, so these chunks are the only parallelism.
JOBS_ENV = "UNSLOTH_RUFF_FORMAT_JOBS"
_MAX_JOBS = 8
# Below this many files per worker an extra interpreter costs more than it saves.
@@ -49,17 +48,13 @@ def pinned_ruff_version(config_text: str) -> str | None:
match = _WHEEL_VERSION_RE.search(requirement) or _EXACT_VERSION_RE.match(requirement)
if match:
found.add(match.group(1))
- # Two different pins is not a question this script can answer, and guessing
- # would enforce the wrong one. Every platform's wheel carries the same version.
+ # Conflicting pins cannot be resolved here; guessing would enforce the wrong one.
return found.pop() if len(found) == 1 else None
def installed_ruff_version(python: str = sys.executable) -> str | None:
- """The ruff-unsloth the format below would actually run, or None when it cannot say.
-
- Read from the distribution, not `--version`: the binary reports the ruff it is
- built on (0.6.9), which does not change between ruff-unsloth releases.
- """
+ """Read from the distribution, not --version: the binary reports its base ruff (0.6.9), which
+ does not change across ruff-unsloth releases; None when it cannot say."""
probe = f"from importlib.metadata import version; print(version({DISTRIBUTION!r}))"
try:
out = subprocess.run([python, "-c", probe], capture_output = True, text = True, timeout = 60)
@@ -89,13 +84,7 @@ def ruff_unavailable_reason(python: str = sys.executable) -> str | None:
def version_mismatch(pinned: str | None, installed: str | None) -> bool:
- """Whether running this ruff would produce formatting the hook then undoes.
-
- An unreadable pin or an unreadable version string is not a mismatch:
- refusing on a question we could not ask would break the hook wherever the
- config moves. A ruff that cannot run at all is caught before this, by
- ruff_unavailable_reason.
- """
+ """Unreadable pin or version is not a mismatch; refusing would break the hook."""
return bool(pinned and installed and pinned != installed)
@@ -165,8 +154,7 @@ def chunk_files(files: list[str], jobs: int) -> list[list[str]]:
groups: dict[object, list[int]] = {}
for index, name in enumerate(files):
try:
- # Device and inode: the one identity case-insensitive filesystems and
- # hard links cannot fool. realpath is the fallback for a missing file.
+ # Device and inode, immune to case folding and hard links; realpath fallback.
info = os.stat(name)
key: object = (info.st_dev, info.st_ino)
except OSError:
@@ -191,13 +179,8 @@ def chunk_files(files: list[str], jobs: int) -> list[list[str]]:
def run_chunks(head: list[str], chunks: list[list[str]]) -> int:
- """Run ``head + chunk`` for every chunk side by side; the first failure's code wins.
-
- One chunk runs as before, output straight through. Several write to temporary
- files that are replayed in chunk order, so the log reads the same from run to
- run. Anything that stops this process early (Ctrl+C, a timeout raising in this
- thread) kills the chunks still running instead of waiting for them.
- """
+ """Chunks run in parallel with output replayed in chunk order, first failure code wins; Ctrl+C
+ or a timeout kills the chunks still running instead of waiting."""
if not chunks:
return 0
if len(chunks) == 1:
@@ -220,8 +203,7 @@ def run_chunks(head: list[str], chunks: list[list[str]]) -> int:
sink.seek(0)
data = sink.read()
sink.close()
- # Bytes where the stream has them: a path the locale codec cannot decode
- # would otherwise crash the replay after every file was formatted.
+ # Raw bytes, so an undecodable path does not crash the replay after formatting.
if hasattr(stream, "buffer"):
stream.buffer.write(data)
stream.buffer.flush()
@@ -245,8 +227,7 @@ def main(argv: list[str]) -> int:
f"(pre-commit run ruff-format-with-kwargs --files ...)"
)
- # Both checks are made before anything is rewritten. The override below is
- # deliberately not honoured here: no ruff-unsloth formats nothing.
+ # Both checks run before any rewrite; the override is deliberately not honoured here.
unavailable = ruff_unavailable_reason()
if unavailable is not None:
print(
@@ -275,8 +256,7 @@ def main(argv: list[str]) -> int:
)
return 1
- # One ruff over every file: it parallelises itself, and one per chunk would
- # stack its thread pools the way pre-commit's partitions did (#14174).
+ # One ruff over all files since it parallelises; per-chunk runs would stack pools.
ruff_proc = subprocess.run([sys.executable, "-m", MODULE, "format", *files])
if ruff_proc.returncode != 0:
return ruff_proc.returncode
diff --git a/scripts/scan_packages.py b/scripts/scan_packages.py
index 9fc732c33fd..41f4980d608 100644
--- a/scripts/scan_packages.py
+++ b/scripts/scan_packages.py
@@ -82,8 +82,7 @@ MEDIUM = "MEDIUM"
SEVERITY_ORDER = {CRITICAL: 0, HIGH: 1, MEDIUM: 2}
-# Hard pin-blocks for confirmed malicious PyPI versions (Socket.dev 2026-05-12 Mini Shai-Hulud wave; earlier
-# Semgrep/Endor reports for `lightning`).
+# Hard blocks on confirmed malicious PyPI versions, from the Mini Shai-Hulud wave and others.
BLOCKED_PYPI_VERSIONS: dict[str, set[str]] = {
"guardrails-ai": {"0.10.1"},
"mistralai": {"2.4.6"},
diff --git a/scripts/sdpa_mask_backend_probe.py b/scripts/sdpa_mask_backend_probe.py
index e60ad6b1ffb..5a511a3ed11 100644
--- a/scripts/sdpa_mask_backend_probe.py
+++ b/scripts/sdpa_mask_backend_probe.py
@@ -36,11 +36,7 @@ def timed(fn, iters = 20):
def _identity(run, reference):
- """Whether ``run``'s dense output is bitwise-identical to the default dispatch's.
-
- "yes" on exactly one backend names the kernel the dispatcher selected. A backend that cannot
- run the dense mask at all reports why instead, so the column never silently reads as a
- mismatch when nothing ran."""
+ """Bitwise match to default dispatch; a backend that cannot run reports why, not a mismatch."""
if reference is None:
return "n/a"
try:
diff --git a/scripts/verify_comment_only_diff.py b/scripts/verify_comment_only_diff.py
index d487d3029a5..7d61dc90775 100644
--- a/scripts/verify_comment_only_diff.py
+++ b/scripts/verify_comment_only_diff.py
@@ -60,8 +60,7 @@ def _normalize_py(src: str) -> str:
def _strip_shell_comments(s: str) -> str:
- """Strip shell comments and collapse blank lines. Heuristic: skips lines
- with an odd quote count (open string)."""
+ """Strip shell comments and blank lines; skip lines with an odd quote count (open string)."""
out = []
for line in s.splitlines():
stripped = line.lstrip()
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index c2e6f76414d..277e59132fe 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -156,11 +156,9 @@ UPSTREAM_WINDOWS_HIP_GFX_TARGETS = frozenset(
}
)
-# install_kinds that really are a Vulkan bundle. A Vulkan request can still end on a CPU
-# bundle (it falls through when the Vulkan archive is missing or fails validation), so check
-# against this to keep the marker honest (#7357).
-# Derived from the shared vocabulary rather than spelled out again: a new Vulkan bundle
-# family added to INSTALL_KIND_BACKENDS must not be missed here.
+# Install kinds that really are a Vulkan bundle, since a Vulkan request can still end on a CPU
+# bundle when its archive is missing or fails validation (issue 7357); derived from
+# INSTALL_KIND_BACKENDS so a new Vulkan family is not missed.
VULKAN_INSTALL_KINDS = frozenset(
kind for kind, kind_backend in INSTALL_KIND_BACKENDS.items() if kind_backend == "vulkan"
)
@@ -278,13 +276,9 @@ _RUN_STAGED_PREBUILT_VALIDATION = False
def prebuilt_needs_functional_validation(choice: "AssetChoice") -> bool:
- """True when a staged prebuilt must run the smoke test before activation.
-
- A release digest proves the bytes are upstream's, not that they load on this host, so
- those archives keep the test they ran while hashless. Only a manifest-approved bundle,
- which Unsloth built and exercised, skips it: that pass costs minutes of cold CUDA JIT
- on Blackwell sm_100, so it stays behind staged_validation_enabled() (#5854).
- """
+ """True when a staged prebuilt must run the smoke test: a digest proves only upstream bytes, so
+ only a manifest-approved bundle skips it, and that pass (minutes of cold CUDA JIT on
+ Blackwell sm_100) stays behind staged_validation_enabled() (issue 5854)."""
if choice.expected_sha256 is None:
return True
if choice.unmanifested_digest:
@@ -353,9 +347,8 @@ _BLACKWELL_SM_MIN_TOOLKIT = {103: (12, 9), 121: (12, 9)}
def _cuda_runtime_lines_for_major(major: int) -> list[str]:
- """Runtime lines a driver of this CUDA major can use, newest major first
- down to the minimum we ship. A driver runs its own major and any older one
- (backward compatibility)."""
+ """Runtime lines a driver of this CUDA major can use, newest first down to the minimum shipped;
+ a driver runs its own major and any older one (backward compatibility)."""
return [f"cuda{m}" for m in range(major, _MIN_CUDA_MAJOR - 1, -1)]
@@ -798,12 +791,9 @@ def _windows_rocm_vulkan_fallback_allowed(host: HostInfo) -> bool:
def windows_cuda_arch_for_host(host: HostInfo) -> str:
- """CUDA prebuilt arch token for a Windows host: arm64 on Windows on ARM, else x64.
-
- ``is_arm64`` is also true for macOS arm64 and Linux aarch64, so the Windows test
- is part of the question rather than the caller's job. Every caller today is already
- inside a Windows branch; this keeps the answer right if one ever is not.
- """
+ """CUDA prebuilt arch token for a Windows host (arm64 on Windows on ARM, else x64); is_arm64 is
+ also true on macOS and Linux aarch64, so the Windows test is part of the answer, not the
+ caller's job."""
return "arm64" if (host.is_windows and host.is_arm64) else "x64"
@@ -859,11 +849,9 @@ def _published_windows_cuda_runtime(
driver: tuple[int, int] | None,
arch: str = "x64",
) -> str | None:
- """Highest cuda-<major>.<minor> published upstream that `driver` can run by
- default CUDA compatibility, i.e. (major, minor) <= driver. None if nothing
- qualifies. Gating on the driver (not just the major) keeps a 13.3 build off
- a driver that only advertises 13.1, where it would otherwise rely on the
- unguaranteed minor-version-compatibility path."""
+ """Highest cuda-major.minor build published upstream that driver can run by default CUDA
+ compatibility, i.e. (major, minor) <= driver, else None; gating on the full version keeps a
+ 13.3 build off a 13.1 driver that would rely on the unguaranteed minor-version path."""
if driver is None:
return None
best: int | None = None
@@ -964,9 +952,8 @@ def commit_source_archive_urls(repo: str, source_commit: str) -> list[str]:
def release_asset_download_url(
repo: str | None, release_tag: str | None, asset_name: str | None
) -> str | None:
- """Direct download URL for a release asset, or None if any part is missing.
- A mix build's merged commit is never pushed, so its source tree is only
- reachable as this asset (codeload would 404 on the merge commit)."""
+ """Direct download URL for a release asset, or None if any part is missing; a mix build's source
+ tree is reachable only as this asset, since codeload would 404 on its unpushed merge commit."""
if not repo or not release_tag or not asset_name:
return None
return (
@@ -1091,12 +1078,9 @@ def release_time_sort_key(release: dict[str, Any]) -> tuple[str, int]:
def release_is_selectable(repo: str, release: dict[str, Any]) -> bool:
- """Whether a listed release may be planned against. A draft never is.
-
- Nor is a prerelease, except an upstream bNNNN build: ggml-org marks every one of
- them prerelease, so the plain rule strands the upstream path hundreds of builds
- back on the newest release that is not one, and those publish no prebuilt at all.
- """
+ """A draft is never selectable, nor a prerelease except an upstream bNNNN build: ggml-org marks
+ all of them prerelease, so the plain rule would strand the upstream path hundreds of builds
+ back on non-prerelease releases that publish no prebuilt at all."""
if release.get("draft"):
return False
if repo == UPSTREAM_REPO:
@@ -1934,12 +1918,9 @@ def _warn_uncovered_cuda_host(
artifacts: list[PublishedLlamaArtifact],
is_arm64: bool = False,
) -> None:
- """Log an uncovered CUDA host once, with cu126 advice only when it can help.
-
- Selection logs cover only viable attempts, so this handles the no-attempt
- path. The explicit pin remains valid when llama.cpp visibility differs from
- the installer's physical inventory.
- """
+ """Log an uncovered CUDA host once, with cu126 advice only when it can help; selection logs
+ cover only viable attempts, and an explicit pin stays valid when llama.cpp visibility differs
+ from the physical inventory."""
# Decided before the dedupe so an unhelpful release cannot swallow the remedy.
advise_cu126 = (
not is_arm64
@@ -2787,12 +2768,9 @@ def run_capture(
def _list_rocm_gfx_targets(out: str) -> list[str]:
- """List gfx targets rocminfo / hipinfo report, one entry per physical GPU.
-
- Both repeat the same gfx token per GPU (Name, ISA, marketing-name), so split on per-GPU
- section headers to keep two entries on a dual same-arch host; flat strings and test stubs
- fall back to insertion-order dedup.
- """
+ """Lists gfx targets from rocminfo or hipinfo, one per physical GPU; both repeat the token per
+ GPU, so split on per-GPU section headers to keep two entries on a dual same-arch host, while
+ flat strings and test stubs fall back to insertion-order dedup."""
_sections = re.split(
r"(?mi)^\s*\*+\s*$\s*agent\s+\d+\s*$|\bdevice\s*#\s*\d+\b",
out,
@@ -3575,12 +3553,10 @@ _blackwell_min_toolkit_for_host = _core.blackwell_min_toolkit_for_host
def _drop_blackwell_incapable_windows_cuda(
host: HostInfo, attempts: list[AssetChoice]
) -> list[AssetChoice]:
- """On a Blackwell host, drop windows CUDA attempts that can't offload
- Blackwell (e.g. cuda-12.4): they load and validate but run a slow non-native
- path (RTX 5090: 7.1 vs 551.2 tok/s on cuda-13.3). Non-cuda attempts pass
- through so the host can still fall back to an honest CPU install. Windows on ARM
- is covered too: every NVIDIA part in that class (GB10 / N1X) is Blackwell, and its
- only CUDA bundles are cuda-13.x, so nothing legitimate is filtered there."""
+ """On Blackwell hosts, drop windows CUDA attempts that cannot offload Blackwell (e.g.
+ cuda-12.4), which load but run a slow non-native path; non-CUDA attempts pass through.
+ Windows on ARM: its NVIDIA parts are Blackwell and ship only cuda-13.x bundles, so nothing
+ legitimate is dropped."""
if not _host_is_blackwell(host):
return attempts
min_toolkit = _blackwell_min_toolkit_for_host(host)
@@ -4766,13 +4742,10 @@ def runtime_patterns_for_install_kind(
def runtime_subdirs_for_choice(choice: AssetChoice) -> list[str]:
- """Subdirectory names within the archive root that must be copied into
- the overlay directory alongside the flat shared libraries.
-
- hipBLASLt and rocBLAS expect their Tensile kernel catalog trees
- (hipblaslt/library/<gfx>/ and rocblas/library/<gfx>/) to sit next to
- their shared libraries at runtime. These trees are multi-level and
- cannot be handled by copy_globs (filename-only matching, flat copy)."""
+ """Archive subdirectories copied into the overlay beside the flat libraries: hipBLASLt and
+ rocBLAS need their Tensile kernel trees (hipblaslt/library/<gfx>, rocblas/library/<gfx>)
+ beside their libraries; copy_globs matches filenames and copies flat, so it cannot carry
+ multi-level trees."""
if choice.install_kind in {"linux-rocm", "windows-rocm", "windows-hip"}:
return ["hipblaslt", "rocblas"]
return []
@@ -5152,20 +5125,9 @@ def move_install_dir_aside(
*,
busy_retry: bool = False,
) -> None:
- """Move an existing install dir to ``dst`` (a unique, non-existent sibling).
-
- os.replace is the fast path, falling back to copy + remove on EXDEV. A busy/in-use
- failure is deliberately NOT copy-faked: the source is a live install and a partial
- copy + rmtree would be worse than failing.
-
- ``busy_retry`` is opt-in per call site: the aside-move of the *live* install is the
- one this installer most needs to survive, while the recovery path's move of an
- already-failed tree has a cheaper answer (drop the tree) than blocking on a scanner.
-
- Callers treat ``dst.exists()`` as proof of a COMPLETE tree, so the copy goes to a
- temp sibling and is published with one atomic rename; a copy that dies halfway
- leaves nothing at ``dst`` and ``src`` untouched.
- """
+ """Moves a tree to a non-existent sibling with os.replace (copy then remove on EXDEV); busy
+ failures are never copy-faked; busy_retry is opt-in for the live aside-move; dst.exists()
+ proves a complete tree, so the copy is staged then atomically renamed."""
try:
if busy_retry:
replace_with_busy_retry(src, dst)
@@ -5770,9 +5732,8 @@ parse_macos_version = _core.parse_macos_version
def host_supports_macos_minos(host: HostInfo, minos: tuple[int, int] | None) -> bool:
- """True if a prebuilt requiring `minos` can load on this host. Unknown host
- version or unknown minos -> True: let runtime validation decide instead of
- rejecting a binary we cannot reason about."""
+ """True if a prebuilt requiring minos can load here; an unknown host version or minos yields
+ True so runtime validation decides instead."""
if minos is None or host.macos_version is None:
return True
return host.macos_version >= minos
@@ -5813,12 +5774,9 @@ def _macho_slice_minos(data: bytes, offset: int) -> tuple[int, int] | None:
def macho_minimum_macos(path: Path, host: HostInfo | None = None) -> tuple[int, int] | None:
- """Minimum macOS (major, minor) a Mach-O binary or dylib requires.
-
- Pure-Python so it works on consumer Macs without the Xcode command line
- tools (otool/vtool). For universal binaries it prefers the host-arch slice,
- else the highest minos found. Returns None for non-Mach-O files or when no
- version load command is present."""
+ """Minimum macOS (major, minor) a Mach-O binary requires, parsed in pure Python so it works
+ without Xcode command line tools (otool/vtool); universal files use the host-arch slice, else
+ the highest minos; None if absent."""
try:
data = path.read_bytes()
except Exception:
@@ -6131,15 +6089,10 @@ def windows_runtime_dirs_for_runtime_line(runtime_line: str | None) -> list[str]
def _wsl_system_rocm_lib_dirs() -> list[str]:
- """System ROCm lib dir(s) for binary_env to load before a prebuilt's HIP.
-
- A prebuilt bundles a bare-metal HIP runtime that can't drive WSL's /dev/dxg
- and segfaults on the first GPU call -> validation fails, install falls back
- to a CPU build. Putting the system ROCm libs first loads the WSL-capable
- HIP (libamdhip64 + librocdxg) while the bundle still supplies libggml-hip /
- librocblas with the gfx1151 kernels. Strict no-op off WSL (needs /dev/dxg, a
- "microsoft" /proc/version, and a librocdxg-providing ROCm).
- """
+ """System ROCm lib dirs go first so binary_env loads the WSL-capable HIP (libamdhip64,
+ librocdxg), since a bundled bare-metal HIP cannot drive WSL and segfaults; the bundle
+ supplies libggml-hip and librocblas. No-op off WSL, which needs /dev/dxg, microsoft in
+ /proc/version and librocdxg."""
try:
if not os.path.exists("/dev/dxg"):
return []
@@ -6549,29 +6502,16 @@ _PR_SET_PDEATHSIG = 1
def _validation_server_leads_group() -> bool:
- """Whether the validation server is started as its own group leader.
-
- Only where the parent-death signal can be armed with it, so the two always
- agree: the kill path may only killpg a group the server actually leads.
- """
+ """Whether the validation server starts as its own group leader; true only on Linux, where the
+ parent-death signal can be armed alongside, so the two always agree and killpg only hits a
+ led group."""
return os.name == "posix" and sys.platform.startswith("linux")
def _validation_server_kwargs() -> "dict[str, Any]":
- """Popen kwargs tying a validation server to this installer's lifetime.
-
- Its own group keeps whatever the server starts reachable through the leader
- alone, but it also takes the server out of the group Unsloth force-kills, so
- the parent-death signal is armed alongside it: an installer that is killed
- mid-validation must not leave a server holding the GPU and the staged files
- until some later startup sweeps the breadcrumb.
-
- macOS has no such signal, and the record only exists once the backend has
- read the announcement that follows the spawn, so a session of its own there
- would leave a window in which nothing can reach the server at all. It stays
- in the inherited group instead, and the termination walk covers whatever it
- starts.
- """
+ """Popen kwargs for the validation server: on Linux it leads its own group with a parent-death
+ signal, so a killed installer cannot leave it holding the GPU; macOS has no such signal and
+ keeps the inherited group, since a session there would leave an unreachable window."""
if not _validation_server_leads_group():
return {}
kwargs: "dict[str, Any]" = {"start_new_session": True}
@@ -6592,11 +6532,8 @@ def _validation_server_kwargs() -> "dict[str, Any]":
def _announce_child(state: str, pid: int) -> None:
- """Tell whoever runs this script about a server it started.
-
- Unsloth adopts the pid so its own sweep can reach it; run by hand the line is
- just noise on stdout.
- """
+ """Prints the UNSLOTH_INSTALLER_CHILD line so Unsloth can adopt the pid for its sweep; run by
+ hand the line is just noise on stdout."""
print(f"UNSLOTH_INSTALLER_CHILD {state} {pid}", flush = True)
@@ -6619,17 +6556,9 @@ def _wait_for_group(pgid: "int | None", grace: float) -> None:
def _terminate_validation_server(process: "subprocess.Popen", grace: float = 5.0) -> bool:
- """Stop the validation server and anything it started. True when it is gone.
-
- Where it leads its own group, signalling the leader alone would leave a
- child of its own behind, and a child that ignores SIGTERM outlives the
- leader's exit. False means something is still in that group, and the caller
- keeps the pid announced so a later sweep can still reach it.
-
- Where it does not lead one it shares this installer's group, and killpg
- would take the installer and Unsloth with it, so only the server itself is
- signalled.
- """
+ """Stops the validation server and any children; True when gone. A group leader's whole group is
+ signalled, as a SIGTERM-ignoring child would outlive it; False keeps the pid announced for a
+ later sweep. Otherwise only the server is signalled, since killpg would hit the installer."""
pgid = None
if _validation_server_leads_group() and hasattr(os, "getpgid"):
try:
@@ -6962,10 +6891,8 @@ def _uncovered_rocm_gpu_takes_vulkan(host: HostInfo) -> bool:
def _linux_published_attempts(host: HostInfo, bundle: PublishedReleaseBundle) -> list[AssetChoice]:
- """Build the install attempts for a fork Linux host from a manifest-described
- bundle: CUDA, per-gfx ROCm, Vulkan, or CPU. Same selection the upstream filename
- path used, just sourced from the manifest instead of reconstructed from asset
- names."""
+ """Builds install attempts for a fork Linux host from a manifest-described bundle (CUDA, per-gfx
+ ROCm, Vulkan or CPU), selecting as the upstream filename path does but from the manifest."""
attempts: list[AssetChoice] = []
if host.has_usable_nvidia:
# Prefer torch's cudart major, else a stray cuda13 runtime outranks the cuda12 torch links.
@@ -7200,12 +7127,9 @@ def _fork_manifest_release_plans(
def persisted_llama_backend(llama_backend: str | None, choice: AssetChoice) -> str | None:
- """The backend to record for an install that actually landed ``choice``.
-
- A Vulkan request can end on a non-Vulkan bundle (no upstream Vulkan archive for Windows
- arm64; x64 falls through to win-cpu-x64 when it is missing or fails validation), and
- recording "vulkan" there would make the updater re-assert a backend that was never
- installed. Mirrors force_cpu: persist the real outcome only."""
+ """Backend to record for an install that landed choice: a Vulkan request can end on a non-Vulkan
+ bundle (no upstream Vulkan archive for Windows arm64; x64 falls to win-cpu-x64), and
+ recording vulkan would make the updater re-assert it; persist the real outcome."""
if llama_backend == "vulkan" and choice.install_kind not in VULKAN_INSTALL_KINDS:
return None
return llama_backend
@@ -7482,12 +7406,9 @@ def _write_marker(marker_path: Path, marker: dict) -> bool:
def recorded_ggml_tree(
approved_checksums: ApprovedReleaseChecksums, choice: AssetChoice
) -> str | None:
- """The ggml tree to record, or None when it does not describe this install.
-
- The tree comes from the fork release's own checkout. A fork plan can install
- an approved ggml-org archive instead (choice.repo differs), built from
- upstream ggml, so the fork tree must not be recorded for it.
- """
+ """The ggml tree to record, or None when it does not describe this install: the tree comes from
+ the fork release's checkout, so an approved ggml-org archive (choice.repo differs) must not
+ record it."""
tree = approved_checksums.ggml_tree
if not isinstance(tree, str) or not tree:
return None
@@ -7762,11 +7683,9 @@ def _release_build_number(tag: str | None) -> int | None:
def _windows_shared_groups(source_label: str | None, tag: str | None = None) -> list[list[str]]:
- """Runtime files every Windows install kind owes, before its backend DLL.
-
- Requiring only ``llama.dll`` let a truncated extract validate then fail at exec.
- Prebuilt sources only: ``setup.ps1`` links statically and ships none of these.
- """
+ """Runtime files every Windows install kind owes before its backend DLL; requiring only
+ llama.dll let a truncated extract validate then fail at exec. Prebuilt sources only:
+ setup.ps1 links statically and ships none of these."""
groups: list[list[str]] = [["llama.dll"]]
if source_label in {"published", "upstream"}:
groups.append(["llama-common.dll"])
@@ -7855,11 +7774,8 @@ def runtime_payload_health_groups(
tag: str | None = None,
install_dir: Path | None = None,
) -> list[list[str]]:
- """Return required runtime file groups for an install kind.
-
- ``install_dir`` is read only where the marker cannot answer on its own, which today
- is the windows-cuda trio a legacy marker does not name.
- """
+ """Required runtime file groups for an install kind; install_dir is read only where the marker
+ cannot answer alone, today the windows-cuda trio a legacy marker does not name."""
if install_kind in {"linux-cpu", "linux-arm64"}:
return [
["libllama-common.so*"],
@@ -8079,21 +7995,9 @@ _PREBUILT_TREE_EVIDENCE = {
def _tree_looks_prebuilt(install_dir: Path, host: HostInfo) -> bool:
- """Whether the runtime tree carries a file only a published bundle ships.
-
- An unparseable marker names no source, and grading such a tree as though it
- might be a source build drops every source-gated group: on Windows that left
- ``llama.dll`` alone standing for the whole payload, so an interrupted marker
- plus a quarantined ``ggml-base.dll`` still answered healthy and the runtime
- launched into the loader error this check exists to pre-empt.
-
- Reading the tree rather than assuming either answer keeps the other half
- honest too: a statically linked source build ships none of these names, and
- requiring a published payload of it would fail health on a tree the setup
- scripts keep, which is the repair loop the docstring above forbids. When
- quarantine has taken the evidence as well, the lenient answer stands, and the
- entrypoint checks below still grade the tree.
- """
+ """Whether the tree holds a file only a published bundle ships: an unparseable marker must not
+ drop the source-gated groups (a quarantined ggml-base.dll would then pass health), and static
+ source builds must stay healthy; with no evidence left the lenient answer stands."""
key = "windows" if host.is_windows else "macos" if host.is_macos else "linux"
runtime_dir = install_runtime_dir(install_dir, host)
return any(
@@ -8316,15 +8220,9 @@ def persist_macos_load_probe(install_dir: Path, host: HostInfo) -> bool:
def _macos_load_record_is_current(marker: "dict[str, Any] | None", host: HostInfo) -> bool:
- """Whether the dyld probe these recorded bytes passed still holds; callers must also
- check _runtime_files_match. A size-only entry misses a same-size rewrite, and an
- unknown macOS version skips the minos check, leaving the probe as the only load check.
-
- Requires POSITIVE evidence that a probe ran and passed (MACOS_LOAD_PROBE_KEY), on
- this exact macOS product version. A marker without it -- every one written before
- this existed, and every install whose probe timed out or could not spawn -- takes
- the probe, which is what happened on every update before the skip existed.
- """
+ """Whether the recorded dyld probe still holds, only with positive MACOS_LOAD_PROBE_KEY evidence
+ of a pass on this exact macOS product version; callers must also check _runtime_files_match,
+ since size-only entries miss same-size rewrites."""
if not host.is_macos or host.macos_version is None or prebuilt_full_check_requested():
return False
marker = marker or {}
@@ -8556,15 +8454,10 @@ def _runtime_preference_moved(marker: "dict[str, Any]", host: HostInfo) -> bool:
def _fallback_runtime_line(host: HostInfo) -> "str | None":
- """The CUDA line the selectors try first when torch states no preference, or None
- when that cannot be told from here.
-
- Mirrors the orderings in linux_cuda_choice_from_release and windows_cuda_attempts
- without a release in hand: Linux takes the detected lines the driver can run, in
- detection order; Windows the driver-compatible lines narrowed to the detected ones,
- or all of them when none is detected. A Blackwell host is routed by its own rule
- ahead of any preference, so nothing about torch moves its choice.
- """
+ """None if undecidable; mirrors linux_cuda_choice_from_release and windows_cuda_attempts without
+ a release (Linux: detected lines the driver can run, in detection order; Windows:
+ driver-compatible lines narrowed to detected, or all if none); Blackwell routes by its own
+ rule before any preference."""
try:
if _host_is_blackwell(host):
return None
@@ -8582,12 +8475,9 @@ def _fallback_runtime_line(host: HostInfo) -> "str | None":
def _torch_runtime_preference_for_marker(host: "HostInfo | None") -> "str | None":
- """The torch CUDA preference an install is being recorded under, or None.
-
- Read only where the selectors read it (a CUDA host on Linux or Windows), so the
- marker says None wherever no preference took part in the choice. Never raises:
- the marker is metadata, not the install.
- """
+ """Returns the torch CUDA preference to record, or None off CUDA Linux or Windows hosts, where
+ the selectors never read it; never raises, since the marker is metadata rather than the
+ install."""
if host is None:
return None
try:
@@ -9262,17 +9152,9 @@ def _existing_install_runs(install_dir: Path, host: HostInfo) -> bool:
def reusable_existing_install(install_dir: Path, host: HostInfo) -> bool:
- """Whether setup.sh may keep this tree instead of building llama.cpp from source.
-
- Only reached once the prebuilt path has failed, so a tree that cannot load a
- model is never worth keeping. The shell test was just "both entrypoints are
- executable", which a quarantine that took a library leaves untouched: the
- rebuild was skipped, the tree came back identical, and an update that repaired
- nothing reported success while preflight kept flagging it.
-
- A tree with no marker is a genuine source build, which ships none of the
- prebuilt payload (setup.ps1 links statically), so it keeps the old test.
- """
+ """Reached only after the prebuilt path failed; the old both-entrypoints-executable test missed
+ a quarantine that removed a library, so a tree that cannot load a model is not kept;
+ markerless source builds, which ship no prebuilt payload, keep the old test."""
if not (install_dir / "UNSLOTH_PREBUILT_INFO.json").is_file():
return True
# #12842: below the floor a CUDA prebuilt still answers --version but loads no kernel.
@@ -9714,11 +9596,9 @@ def persisted_backend_request(install_dir: Path | None) -> str:
def effective_backend_request(
llama_backend: str | None = None, *, install_dir: Path | None = None
) -> tuple[str, bool]:
- """Return (backend, mandatory) using CLI, env, then marker precedence.
-
- Explicit requests are mandatory. A stored choice is advisory: it is dropped
- for detection when the hardware or the published bundles no longer offer it.
- """
+ """Returns (backend, mandatory) by CLI, then env, then marker precedence; explicit requests are
+ mandatory, while a stored choice is advisory and dropped when hardware or published bundles
+ no longer offer it."""
explicit = normalize_backend_request(llama_backend)
if explicit is None:
explicit = environment_backend_override(
@@ -10074,12 +9954,9 @@ def _vulkan_loader_allows(path: str) -> bool:
# Per call, not at import: Path.home() raises with no USERPROFILE.
def _vulkan_icd_search_dirs() -> list[Path]:
- """The icd.d directories the loader would search, in its own order.
-
- From the XDG variables, since the loader falls back to the defaults only when one is
- unset: reading the defaults regardless both misses a custom layout's only AMD manifest
- and counts stale ones the loader would never read.
- """
+ """Lists the icd.d directories the loader searches, in its own order, from the XDG variables
+ (defaults only when one is unset); reading the defaults regardless misses a custom layout's
+ only AMD manifest."""
def _paths(var: str, default: str) -> list[Path]:
value = os.environ.get(var)
@@ -10225,11 +10102,9 @@ def _windows_devnode_is_usable(cfgmgr: Any, ctypes: Any, wintypes: Any, devinst:
def _windows_device_icd_manifest_paths(winreg: Any) -> list[str]:
- """Read Vulkan manifests from present adapters and SoftwareComponents.
-
- A removed device keeps its registration AND its files, so presence decides, and a
- class whose presence is unknown is skipped rather than trusted.
- """
+ """Reads Vulkan manifests only from present adapters and SoftwareComponents: a removed device
+ keeps its registration and files, so presence decides and unknown-presence classes are
+ skipped."""
paths: list[str] = []
for class_key_path in _WINDOWS_VULKAN_DEVICE_CLASS_KEYS:
present = _windows_present_class_instances(class_key_path)
@@ -10257,9 +10132,8 @@ def _windows_device_icd_manifest_paths(winreg: Any) -> list[str]:
def _windows_vulkan_driver_value_paths(winreg: Any, value: Any, kind: Any) -> list[str]:
- """Existing absolute manifest paths from REG_SZ or REG_MULTI_SZ. Relative ones need
- the device's DriverStore directory, which is not reachable here, so they are skipped.
- """
+ """Existing absolute manifest paths from REG_SZ or REG_MULTI_SZ values; relative paths need the
+ device's DriverStore directory, which is unreachable here, so they are skipped."""
if kind == winreg.REG_SZ:
entries = [value]
elif kind == winreg.REG_MULTI_SZ:
@@ -10282,11 +10156,9 @@ def _windows_vulkan_driver_value_paths(winreg: Any, value: Any, kind: Any) -> li
def _amd_vulkan_icd_manifest_paths() -> list[str]:
- """Vulkan ICD manifests this host has registered, by loader search order.
-
- A file list or a registry key, both readable in-process: vulkaninfo is absent on most
- Windows hosts and libvulkan on a headless ROCm box, the case being tested for.
- """
+ """Vulkan ICD manifests registered on this host, in loader search order, read in-process from
+ file lists or registry keys, since vulkaninfo is absent on most Windows hosts and libvulkan
+ on a headless ROCm box."""
# Force lists, not hints; VK_DRIVER_FILES supersedes VK_ICD_FILENAMES rather than joining it.
for env_name in ("VK_DRIVER_FILES", "VK_ICD_FILENAMES"):
value = os.environ.get(env_name)
@@ -10361,11 +10233,8 @@ def _amd_vulkan_icd_usable(path: str) -> bool:
def _amd_vulkan_icd_present() -> bool:
- """Whether an AMD Vulkan driver is installed, so the Vulkan bundle has a device.
-
- What makes the route safe by construction rather than by allowlist alone: no AMD ICD
- keeps ROCm rather than silently running on CPU, and it fails towards the status quo.
- """
+ """Whether an AMD Vulkan driver is installed so the Vulkan bundle has a device; with no AMD ICD,
+ ROCm is kept rather than silently running on CPU, failing towards the status quo."""
def _is_amd_64_bit(name: str) -> bool:
stem = PurePath(name).stem.lower().replace("-", "_")
@@ -10454,14 +10323,9 @@ def _backend_only_attempts(attempts: Iterable[AssetChoice], backend: str) -> lis
def _backend_only_release_plans(
plans: Iterable[InstallReleasePlan], backend: str
) -> list[InstallReleasePlan]:
- """Keep release plans that contain a bundle for ``backend``.
-
- A plan lists its attempts best-first and ends in a generic CPU fallback, which is
- right for detection and wrong for a named request: someone who asked for Vulkan
- because their CUDA build crashes is not served by quietly installing CPU. So a
- request that cannot be met fails here, and the caller decides -- a named one
- surfaces the failure, a stored one falls back to detection.
- """
+ """Keeps plans with a bundle for backend; a named request must not quietly fall back to the
+ generic CPU tail, so unmet requests fail here and the caller surfaces them, or a stored one
+ falls back to detection."""
filtered = []
for plan in plans:
attempts = _backend_only_attempts(plan.attempts, backend)
@@ -10639,10 +10503,9 @@ if hasattr(errno, "EDQUOT"):
def _winerror_of(exc: OSError) -> Any:
- """exc.winerror, defensively. Not getattr(exc, ..., None): urllib's HTTPError
- is an OSError that proxies unknown attributes to a wrapped file object and
- raises KeyError (not AttributeError) on 3.9, which getattr will not swallow.
- A 404 from a mirror must not crash the classifier."""
+ """Reads exc.winerror defensively, not via getattr: on Python 3.9 urllib's HTTPError proxies
+ unknown attributes and raises KeyError, which getattr will not swallow; a mirror's 404 must
+ not crash this."""
try:
return exc.winerror
except Exception:
@@ -10685,10 +10548,9 @@ def _log_disk_space_help() -> None:
@contextmanager
def scratch_dir(prefix: str) -> Iterator[Path]:
- """Temp dir whose cleanup never raises: an rmtree failure on the way out would
- replace the in-flight exception and lose EXIT_NO_SPACE. Not
- TemporaryDirectory(ignore_cleanup_errors = True), which is 3.10+ (setup.sh
- still runs this helper under the host python, and we support 3.9)."""
+ """Temp dir whose cleanup never raises, so an rmtree failure cannot replace EXIT_NO_SPACE; not
+ TemporaryDirectory(ignore_cleanup_errors = True), which needs 3.10+ while setup.sh runs this
+ on the host python and 3.9 is supported."""
path = Path(tempfile.mkdtemp(prefix = prefix))
try:
yield path
@@ -10704,10 +10566,9 @@ def _first_existing_ancestor(path: Path) -> Path:
def _low_disk_warning(install_dir: Path, *, advised_gb: float = 5.0) -> str | None:
- """Advisory only, never fatal. A prebuilt install peaks well under 1 GB (the
- largest published bundle is 0.77 GB, macOS is 0.01 GB), so a fixed threshold
- cannot decide whether this host has room -- a real ENOSPC decides that. The
- number here is the headroom a source-build fallback would want."""
+ """Advisory only, never fatal: prebuilt installs peak under 1 GB, so a fixed threshold cannot
+ decide whether there is room and a real ENOSPC does; advised_gb is the headroom a
+ source-build fallback would want."""
advised = int(advised_gb * (1024**3))
targets = {
"build/download scratch (TMPDIR)": Path(tempfile.gettempdir()),
@@ -11575,12 +11436,8 @@ def resolve_backends_payload(
args: argparse.Namespace,
install_dir: Path | None = None,
) -> dict[str, Any]:
- """Resolve every requestable backend against the installed release.
-
- One metadata snapshot answers all of them: the picker asks about five backends
- at once, and re-listing the same release five times is both slow and a way for
- the five answers to disagree with each other.
- """
+ """Resolves every requestable backend from one metadata snapshot, so the picker's five answers
+ cannot disagree and the release is not re-listed five times."""
host = detect_host()
marker = load_prebuilt_metadata(install_dir) if install_dir is not None else None
installed_repo = (marker or {}).get("published_repo")
diff --git a/studio/install_manifest.py b/studio/install_manifest.py
index 4ed5d00ddc8..6dad642e354 100644
--- a/studio/install_manifest.py
+++ b/studio/install_manifest.py
@@ -129,11 +129,8 @@ def requirement_digests(req_root: Optional[Path] = None) -> Dict[str, str]:
def digest_file(path) -> Optional[str]:
- """sha256 of one file, or None when it is absent or unreadable.
-
- None is never equal to a recorded digest, so an input that cannot be read
- forces the step that consumes it to run. That is the safe direction.
- """
+ """sha256 of one file, or None when absent or unreadable; None never equals a recorded digest,
+ so an unreadable input forces the consuming step to run."""
try:
return _sha256(Path(path))
except (TypeError, ValueError):
@@ -157,13 +154,9 @@ def _canonical(name: str) -> str:
def _metadata_scan_paths() -> List[str]:
- """This interpreter's site-packages roots, excluding inherited sys.path entries.
-
- Deduplicated by real path, not by string: purelib hardcodes `lib` while
- platlib follows sys.platlibdir, so a lib64 build (Fedora, SuSE) names one
- directory twice through venv's lib64 -> lib symlink. Scanning both would
- report every package twice and turn a healthy venv into a conflict.
- """
+ """Site-packages roots minus inherited sys.path entries, deduplicated by real path: purelib
+ hardcodes lib while platlib follows sys.platlibdir, so lib64 builds would list one directory
+ twice."""
import sysconfig
paths: List[str] = []
@@ -360,13 +353,9 @@ def metadata_conflict(versions: Sequence[str]) -> bool:
def _metadata_is_inconsistent(dist_name: str, versions: Optional[List[str]] = None) -> bool:
- """Duplicated, unreadable, or standing on a record pip will not honour.
-
- A sole `~` backup is the case a version count cannot see: one readable
- version, so nothing looks wrong, while pip refuses the directory and the
- package tree is usually renamed away with it. Left unflagged, the fast path
- calls the package up to date and skips the pass that would reinstall it.
- """
+ """Flags duplicated, unreadable or pip-ignored metadata; a sole ~ backup is invisible to a
+ version count yet pip refuses it, and unflagged the fast path would skip the reinstall that
+ repairs it."""
if versions is None:
versions = installed_versions(dist_name)
return bool(metadata_conflict(versions) or pip_backup_metadata_paths(dist_name))
@@ -442,13 +431,9 @@ def _publish_json(
@contextlib.contextmanager
def _manifest_lock(root: Optional[Path] = None):
- """Hold an exclusive lock on LOCK_NAME for the block. Never raises.
-
- Best effort: this module has to run inside a half-built venv, so a filesystem that cannot
- lock (a network mount, a read-only prefix, no fcntl or msvcrt) proceeds unserialised
- rather than failing an install, as it did before this existed. The deadline below bounds
- the retries, not one stalled syscall.
- """
+ """Holds an exclusive lock on LOCK_NAME, best effort and never raising: a filesystem that cannot
+ lock (network mount, read-only prefix, no fcntl or msvcrt) runs unserialised rather than
+ failing; the deadline bounds retries, not one stalled syscall."""
handle = None
locked = False
try:
@@ -813,12 +798,9 @@ def no_torch_marker_path(root: Optional[Path] = None) -> Path:
def set_no_torch_marker(no_torch: bool, root: Optional[Path] = None) -> None:
- """Record the mode outside the completion manifest. Never raises.
-
- Written before the dependency pass so an interrupted install still knows what
- it was building. Removed when torch is wanted, so migrating out of no-torch
- does not leave a stale marker behind.
- """
+ """Records the no-torch mode outside the completion manifest before the dependency pass, so an
+ interrupted install still knows its mode; removed when torch is wanted so no stale marker
+ remains. Never raises."""
path = no_torch_marker_path(root)
try:
if no_torch:
@@ -830,12 +812,9 @@ def set_no_torch_marker(no_torch: bool, root: Optional[Path] = None) -> None:
def recorded_no_torch(root: Optional[Path] = None) -> Optional[bool]:
- """The mode this venv was installed with, or None when unknown.
-
- None means nothing recorded it: no manifest key and no marker. Callers must
- fall back to their own detection on None and never to False, so an install
- made before either existed is not silently switched out of no-torch mode.
- """
+ """Recorded no-torch mode, or None when no manifest key or marker exists; callers must detect
+ for themselves on None and never assume False, so older installs are not silently switched
+ out of no-torch mode."""
manifest = read_manifest(root)
if manifest is not None:
value = manifest.get("no_torch")
@@ -852,18 +831,9 @@ def recorded_no_torch(root: Optional[Path] = None) -> Optional[bool]:
def recorded_torch_flavor(root: Optional[Path] = None) -> Optional[str]:
- """The torch flavor this venv was installed with, or None when unknown.
-
- None means nothing recorded it: no manifest, or one written before the key
- existed. Callers must treat None as "unknown" and fall back to their own
- detection, never as "cpu" -- claiming a flavor nobody selected would let a
- repair reinstall over a deliberate build.
-
- There is no marker companion here (unlike no_torch): the manifest is dropped
- before every dependency pass, so this answers only for the PREVIOUS install,
- which is exactly the question a repair asks. A run whose own setup script
- exported the flavor never reaches this.
- """
+ """Torch flavor recorded by the previous install, or None when unknown; never read None as cpu,
+ or a repair reinstalls over a deliberate build; no marker companion, as the manifest is
+ dropped each pass; a run whose setup script exported the flavor never reaches this."""
manifest = read_manifest(root)
if manifest is None:
return None
@@ -875,15 +845,9 @@ def recorded_torch_flavor(root: Optional[Path] = None) -> Optional[str]:
def recorded_torch_flavor_was_pinned(root: Optional[Path] = None) -> bool:
- """Whether the recorded flavor was NAMED rather than automatically selected.
-
- False when nothing recorded it, including a manifest written before the key
- existed. That is the safe direction here and the opposite of the usual "unknown
- falls back to the old behaviour": treating an unproven CPU record as deliberate is
- what leaves a host that has since gained a GPU with no repair offered at all, which
- is the failure this whole field exists to distinguish. A repair is something the
- user can decline; a silently CPU-only GPU box is not.
- """
+ """Whether the recorded flavor was named rather than auto-selected; False when unrecorded, since
+ an unproven CPU record read as deliberate would leave a host that later gained a GPU with no
+ repair offered."""
manifest = read_manifest(root)
if manifest is None:
return False
@@ -892,11 +856,8 @@ def recorded_torch_flavor_was_pinned(root: Optional[Path] = None) -> bool:
def _parse_requirement_line(line: str) -> Optional[Tuple[str, str, str]]:
- """(distribution name, marker, specifier) for a requirement, or None.
-
- Covers what studio.txt uses: names, specifiers, inline comments, markers.
- pip flags are skipped.
- """
+ """Returns (distribution name, marker, specifier) for a requirement line, or None for blanks and
+ pip flags; covers the names, specifiers, inline comments and markers that studio.txt uses."""
text = line.split("#", 1)[0].strip()
if not text or text.startswith("-"):
return None
@@ -950,14 +911,9 @@ def _version_satisfies(version: str, specifier: str) -> bool:
def missing_requirements(
req_file: Optional[Path] = None, installed: Optional[Dict[str, str]] = None
) -> List[str]:
- """Distribution names that are missing or outside their required versions.
-
- Checked via importlib.metadata, not import names, because studio.txt lists
- PyJWT / python-docx / pymupdf whose import names (jwt, docx, fitz) differ.
-
- `installed` (canonical distribution name -> version) checks a venv other
- than the one running this code, which importlib.metadata cannot see.
- """
+ """Distribution names missing or outside their required versions, checked via importlib.metadata
+ since import names (jwt, docx, fitz) differ; the installed mapping checks another venv, which
+ importlib.metadata cannot see."""
from importlib.metadata import PackageNotFoundError, distribution
path = req_file or (requirements_root() / BOOT_REQUIREMENT_FILE)
@@ -1229,10 +1185,8 @@ def _staged_beside(target) -> bool:
def _within(target: Path, anchor: Path) -> bool:
- """Whether a parent-relative row lands inside the environment.
-
- One outside it belongs to something else, which reinstalling ours cannot fix.
- """
+ """Whether a parent-relative row lands inside the environment; one outside it belongs to
+ something else, which reinstalling ours cannot fix."""
try:
resolved = target.resolve()
except OSError:
@@ -1590,12 +1544,9 @@ def _sidecar_damaged_files(
budget_seconds: float = SIDECAR_SCAN_BUDGET_SECONDS,
required: Sequence[str] = (),
) -> List[str]:
- """RECORD rows under a sidecar that are gone, truncated, or built for another CPython.
-
- Fails open everywhere: the caller's answer to a finding is to delete several hundred
- MB and refetch, so anything unreadable reports nothing rather than guessing. Bounded,
- because no installer wraps this in a timeout and a stalled mount would wedge setup.
- """
+ """Finds RECORD rows under a sidecar that are gone, truncated or built for another CPython;
+ fails open since a finding triggers a large delete, and is bounded by budget_seconds since a
+ stalled mount would wedge setup."""
import csv
import io
import stat
diff --git a/studio/install_node_prebuilt.py b/studio/install_node_prebuilt.py
index 8885e50bdf4..1c0eda622f8 100644
--- a/studio/install_node_prebuilt.py
+++ b/studio/install_node_prebuilt.py
@@ -215,12 +215,9 @@ def _meets_node_floor(version: str) -> bool:
def select_node_version(index: list[dict], *, channel: str, min_major: int) -> str:
- """Pick a concrete Node version from the Node dist index.json.
-
- channel='lts' -> newest LTS release line whose major >= min_major.
- channel='latest' -> newest release overall whose major >= min_major.
- Otherwise the channel is treated as an explicit version string.
- """
+ """Picks a concrete Node version from index.json: channel lts takes the newest LTS line and
+ latest the newest overall, both with major >= min_major; any other channel is an explicit
+ version string."""
if channel not in {"lts", "latest"}:
return channel.lstrip("v")
@@ -778,12 +775,9 @@ _PREBUILT_FULL_CHECK_ENV = "UNSLOTH_PREBUILT_FULL_CHECK"
def prebuilt_full_check_requested() -> bool:
- """The escape hatch for the recorded-runtime shortcut, spelled as llama and whisper spell it.
-
- Defined here rather than imported: this installer bootstraps the managed Node runtime and must
- not depend on the llama module. A user told to set one variable to force a full revalidation
- would otherwise still get Node answered from its marker.
- """
+ """Escape hatch forcing a full Node revalidation past the recorded-runtime shortcut; defined
+ here rather than imported from the llama module so this installer stays independent, spelled
+ as llama and whisper spell it."""
return os.environ.get(_PREBUILT_FULL_CHECK_ENV, "").strip().lower() in (
"1",
"true",
@@ -803,21 +797,9 @@ def _file_record(path: Path) -> dict | None:
def _file_record_matches(path: Path, recorded: object) -> bool:
- """Whether *path* is still the file *recorded* describes.
-
- size and mtime_ns only. The digest is recorded too, and deliberately not compared here:
- this runs on every launch of the installer and node is ~110 MB, so hashing it would cost
- more than the `node -v` spawn the record exists to avoid. The digest is there so a support
- log can say which binary this is.
-
- What that gives up is narrower than it looks, in both directions. A node that no longer
- RUNS is still caught, because npm-cli.js is run BY the node binary and that probe is never
- skipped, so the case an update can actually repair is not the case being skipped. And the
- record was never a tamper defence: it sits in a marker beside the binary, writable by
- anyone who could rewrite the binary in place, so an edit careful enough to restore the
- byte count and the nanosecond timestamp is an edit that can restore the record too. The
- check before this one, `node -v`, could not prove any more than that either.
- """
+ """Compares only size and mtime_ns: hashing the node binary on every launch would cost more than
+ the node -v spawn it avoids; a node that no longer runs is still caught by the npm-cli.js
+ probe, and the record was never a tamper defence."""
if not isinstance(recorded, dict):
return False
try:
@@ -1301,12 +1283,8 @@ def _report_access_denied(exc: OSError, install_dir: Path) -> int:
def _within(path: str, root: Path) -> bool:
- """Whether path is root or sits under it, by spelling alone.
-
- Both sides come from the same --install-dir string, so normalizing without
- resolving links keeps them comparable; resolving would need the very access
- that was just denied.
- """
+ """Whether path is root or under it, by spelling alone; both sides come from the same
+ --install-dir string, and resolving links would need the access that was just denied."""
normalized = os.path.normcase(os.path.abspath(path))
base = os.path.normcase(os.path.abspath(root))
return normalized == base or normalized.startswith(base.rstrip(os.sep) + os.sep)
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index e90a8a751e6..b54a1c59b76 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -480,12 +480,9 @@ _PYTORCH_WHL_BASE = (
def _strip_index_url_credentials(url: str) -> str:
- """Strip userinfo (user:password@) AND query/fragment from a wheel index URL.
-
- An authenticated pin must not leak credentials in printed output; query/fragment
- may hold tokens and aren't part of the PEP 503 index identity. Host/path stay
- exact. MUST match install.sh / setup.ps1 / install.ps1.
- """
+ """Strips userinfo (user:password@), query and fragment from a wheel index URL, since those can
+ hold credentials or tokens and are not part of the PEP 503 identity; host and path stay
+ exact. Must match install.sh, setup.ps1 and install.ps1."""
scheme, sep, rest = url.partition("://")
if not sep:
return url
@@ -502,10 +499,9 @@ _URL_FRAGMENT_RE = re.compile(r"(https?://[^\s`#]+)#[^\s`]+")
def _redact_install_output(output: "bytes | str") -> str:
- """Redact index-URL credentials (userinfo + query values + fragments) from captured
- installer output before printing. uv/pip failure text embeds the failing --index-url
- verbatim, which can carry a user:token@, ?token= or #token= secret. MUST match
- install.sh / setup.ps1 / install.ps1's output sanitizers."""
+ """Redacts index-URL credentials (userinfo, query values, fragments) from captured installer
+ output before printing, since uv and pip failures echo --index-url verbatim; must match the
+ sanitizers in install.sh, setup.ps1 and install.ps1."""
text = output.decode(errors = "replace") if isinstance(output, bytes) else output
text = _URL_USERINFO_RE.sub(r"\1<redacted>@", text)
text = _URL_QUERY_VALUE_RE.sub(r"\1=<redacted>", text)
@@ -767,11 +763,10 @@ class _FreezeNewTorchForCoreUpdate:
return False
-# torchao cpp extensions match one torch and CUDA release; mismatches disable kernels or crash.
-# torch 2.6-2.9 gets 0.15: transformers 5 and diffusers 0.41 refuse TorchAoConfig below 0.15 (#13244),
-# and 0.14 never loads its cpp extensions on torch 2.6-2.8 anyway, so the older pin bought nothing.
-# torchao 0.15 dropped torch <= 2.5, so those keep 0.14.
-# use the resident accelerator index because PyPI follows the latest PyTorch CUDA major.
+# torchao extensions need one torch/CUDA release: torch 2.6-2.9 gets 0.15 (transformers 5 and
+# diffusers 0.41 refuse TorchAoConfig below 0.15, ref 13244; 0.14 never loads extensions on
+# 2.6-2.8), torch 2.5 and older keep 0.14; use the resident accelerator index since PyPI follows the
+# latest CUDA major.
_TORCHAO_DEFAULT_SPEC = "torchao==0.15.0"
_TORCHAO_TORCH_25_SPEC = "torchao==0.14.0"
_TORCHAO_TORCH_29_SPEC = "torchao==0.15.0"
@@ -1072,19 +1067,9 @@ def _torch_accelerator_index_url(
def _torchcodec_index_url(torch_version: "str | None", spec: str = "") -> "str | None":
- """The torchcodec index serving the resident torch's build, or None to stay unpinned.
-
- Upstream's install docs say to pass --index-url and "make sure to install the
- corresponding PyTorch version as well", so a cu126 or cu128 venv that takes PyPI's
- default gets a codec built against a different CUDA and libtorchcodec cannot dlopen.
- docker/Dockerfile already pins cu128 by hand for this reason.
-
- rocm is the one accelerator excluded: every rocm leaf answers 404/403 for torchcodec,
- so a pin there is a guaranteed wasted resolve. xpu is redirected to cpu, for the reason
- beside _TORCHCODEC_INDEX_TAGS. Where a pinned index turns out not to serve the selected
- window (cu129 has no 0.8 or 0.9), the caller's unpinned retry recovers; that is
- deliberate, because no local table of index CONTENTS stays true.
- """
+ """Returns the torchcodec index for the resident torch's build, or None to stay unpinned: PyPI's
+ default codec may target another CUDA and fail to dlopen, rocm leaves answer 404/403, xpu
+ maps to cpu, and an unserved pin falls back to the caller's unpinned retry."""
local = str(torch_version or "").partition("+")[2].strip().lower()
if local.startswith("rocm"):
return None
@@ -1149,12 +1134,9 @@ def _torchcodec_spec_bounds(spec: str) -> "tuple[tuple[int, ...], tuple[int, ...
def _torchcodec_spec_is_installable(spec: str) -> bool:
- """Does this host have a wheel for any release the spec admits?
-
- Asked before the install rather than discovered by it, because the install step exits on
- failure. Answering no means the audio extra is skipped, which is what a host with no wheel
- got before this step existed.
- """
+ """Whether this host has a wheel for any release the spec admits, asked before install since the
+ install step exits on failure; a no skips the audio extra, as hosts with no wheel got before
+ this step existed."""
host_floor = _torchcodec_platform_floor()
if host_floor is None:
return False
@@ -1171,12 +1153,9 @@ def _torchcodec_spec_is_installable(spec: str) -> bool:
def _codec_spec_is_satisfied(spec: str, installed: str) -> bool:
- """Whether the resident torchcodec already sits inside the pin's window.
-
- The local tag is deliberately ignored here -- the caller has already decided the
- provenance question through _codec_rebuild, and a `+cu130` suffix makes the version
- fall outside a PyPI-shaped specifier that it in fact satisfies.
- """
+ """Whether the resident torchcodec sits inside the pin's window, ignoring the local tag:
+ provenance is decided by _codec_rebuild, and a +cu130 suffix would otherwise fall outside a
+ PyPI-shaped specifier that it satisfies."""
if not installed:
return False
base = installed.partition("+")[0]
@@ -1483,9 +1462,8 @@ _BNB_ROCM_PYPI_FALLBACK = "bitsandbytes>=0.50.0"
def _bnb_rocm_prerelease_url() -> str | None:
- """Return the continuous-release_main bnb wheel URL for the current arch,
- or None when no pre-release wheel is available.
- """
+ """Returns the continuous-release_main bnb wheel URL for the current arch, or None when no
+ pre-release wheel is available."""
arch = platform.machine().lower()
arch = {"amd64": "x86_64", "arm64": "aarch64"}.get(arch, arch)
return _BNB_ROCM_PRERELEASE_URLS.get(arch)
@@ -1523,13 +1501,9 @@ def _installed_direct_url(dist_name: str) -> "str | None":
def _bnb_asset_identity(url: str) -> "str | None":
- """What is published at *url* right now, as an opaque string, or None if unreachable.
-
- The preferred ROCm wheel comes from bitsandbytes' continuous-release_main release, whose
- asset PATH never changes while its bytes do, so the URL pip recorded says where the wheel
- came from, not which one. One HEAD follows the redirect and reads the ETag and size of the
- current bytes; the pass records that beside the provenance and the next one compares.
- """
+ """Opaque ETag and size of the bytes now at url (one HEAD following redirects), or None if
+ unreachable; the continuous-release_main asset path never changes, so the URL alone cannot
+ identify the wheel; recorded beside provenance and compared next pass."""
import urllib.request
try:
@@ -1559,13 +1533,8 @@ def _bnb_wheel_version(url: str) -> "str | None":
def _installed_bnb_provenance() -> "str | None":
- """What the resident bitsandbytes IS, or None when there is nothing to keep.
-
- An opaque string compared only against another produced the same way: the URL pip
- recorded, or the version when nothing did. It says nothing about whether that is the RIGHT
- build, which is the caller's question; keeping the two apart lets a recorded provenance be
- checked against both what is on disk and what this run would install.
- """
+ """Opaque provenance of the resident bitsandbytes (the URL pip recorded, else the version), or
+ None; it says nothing about whether that build is the right one, which the caller decides."""
installed = _installed_distribution_version("bitsandbytes")
if not installed:
return None
@@ -1676,11 +1645,9 @@ def _spec_is_satisfied(spec: str, installed: str) -> bool:
def _bnb_rocm_arch_has_binary() -> bool:
- """False on aarch64: bitsandbytes ships no ROCm kernels there at any version.
- The PyPI 0.50.0 and continuous-release_main aarch64 wheels both carry only
- libbitsandbytes_cpu.so plus CUDA variants, so neither install path gives
- aarch64 a 4-bit backend and neither message may claim one.
- """
+ """False on aarch64, where bitsandbytes ships no ROCm kernels at any version: the PyPI 0.50.0
+ and continuous-release_main wheels carry only libbitsandbytes_cpu.so plus CUDA, so no message
+ may claim a 4-bit backend."""
arch = platform.machine().lower()
return {"amd64": "x86_64", "arm64": "aarch64"}.get(arch, arch) != "aarch64"
@@ -2218,10 +2185,9 @@ def _detect_windows_gfx_arch() -> str | None:
f" [WARN] '{_names[_sel]}' is {_unsupported}, which Unsloth's ROCm "
f"PyTorch wheels do not cover, {_tail}"
)
- # Torch ends here, llama.cpp does not: Vulkan drives these cards
- # (#8458 ran an RX 580 through it). PowerShell syntax because this
- # branch is Windows-only: a pasted VAR=value parses there as a
- # command name and sets nothing.
+ # Torch ends here, llama.cpp does not: Vulkan drives these cards (ref 8458 ran
+ # an RX 580 through it); PowerShell syntax since this branch is Windows-only, as
+ # a pasted VAR=value parses there as a command name and sets nothing.
_safe_print(
" [INFO] GGUF chat can still run on this GPU through Vulkan: set "
'$env:UNSLOTH_LLAMA_CPP_BACKEND = "vulkan" and re-run the installer. '
@@ -2286,10 +2252,8 @@ _UNSUPPORTED_GPU_NAME_ARCH_TABLE: "list[tuple[str, str]]" = [
def _unsupported_gfx_arch_from_gpu_name(name: str) -> "str | None":
- """Name the gfx arch of a GPU whose generation Unsloth has no ROCm wheels for.
-
- Messaging only. Callers must not feed the result into index selection.
- """
+ """Names the gfx arch of a GPU whose generation has no Unsloth ROCm wheels; messaging only, so
+ callers must not feed the result into index selection."""
if not name:
return None
for _pat, _arch in _UNSUPPORTED_GPU_NAME_ARCH_TABLE:
@@ -2355,12 +2319,9 @@ def _lspci_nn_stdout() -> "str | None":
def _linux_amd_gfx_from_lspci(beside_krackan2: bool = False) -> "str | None":
- """First AMD display-class lspci line mapping to a known gfx arch. A non-AMD
- controller can enumerate first (Intel/ASPEED before an AMD dGPU), so scan
- them all. The vendor guard is case-SENSITIVE: a -i "ATI" would match
- "CorporATIon" on every Intel/NVIDIA line. Whole-line matching also survives
- the 0000: PCI domain prefix. beside_krackan2 skips that APU's own iGPU line, so only a
- discrete peer answers."""
+ """First AMD display-class lspci line mapping to a known gfx arch, scanning all lines since
+ non-AMD controllers can enumerate first; the vendor guard is case-sensitive, since a
+ case-insensitive ATI would match CorporATIon; beside_krackan2 skips the APU's own iGPU line."""
stdout = _lspci_nn_stdout()
if stdout is None:
return None
@@ -2706,9 +2667,8 @@ _GFX906_BNB_ABSENT_BEFORE_BASE = False
def _bitsandbytes_installed() -> bool:
- """True if bitsandbytes is importable in the target venv. Runs a fresh
- subprocess so a package installed earlier this run is seen; only checks the
- spec (does NOT import bitsandbytes)."""
+ """True if bitsandbytes is installed in the target venv, checked by a fresh subprocess so
+ earlier installs this run are seen; only the spec is checked, bitsandbytes is never imported."""
try:
return (
subprocess.run(
@@ -2810,14 +2770,9 @@ def _rocm_torch_explicitly_requested() -> bool:
def _has_rocm_gpu() -> bool:
- """Return True only if an actual AMD GPU is visible (not just ROCm tools installed).
-
- Returns False when an NVIDIA GPU is present -- NVIDIA takes priority on mixed
- hosts and prevents every detection path below (rocminfo, amd-smi, KFD sysfs) from
- producing a false positive even if ROCm tools are installed alongside the NVIDIA
- driver -- unless this run explicitly asked for ROCm, which is the one case where
- the AMD card is the point.
- """
+ """True only if an AMD GPU is visible, not merely ROCm tools; an NVIDIA GPU makes it False,
+ since NVIDIA wins on mixed hosts, unless this run explicitly requested ROCm, where the AMD
+ card is the point."""
if _has_usable_nvidia_gpu() and not _rocm_torch_explicitly_requested():
return False
for cmd, check_fn in (
@@ -3075,14 +3030,9 @@ _MIXED_HOST_UNROUTABLE: "frozenset[str]" = frozenset({"gfx906"})
def _gfx_route_on_host(gfx: "str | None", host_codes: "list[str] | None" = None) -> bool:
- """Whether an index can serve ``gfx`` ON THIS HOST, not on some host.
-
- _gfx_has_a_wheel_route asks it in the abstract, and gfx906 answers yes on the generic
- union while its only usable route -- the rocm6.3 legacy tag -- opens solely when gfx906
- is the one arch on the machine. ``host_codes`` is that machine BEFORE the ROCr layer, to
- match _runtime_target_is_gfx906's unfiltered probe: judging by the survivors would call
- a masked gfx906 alone, demote, then be refused the tag by a function seeing both cards.
- """
+ """Whether an index can serve gfx on this host; gfx906 has a wheel only via the rocm6.3 legacy
+ tag, which needs it as the sole arch, so host_codes must be the unfiltered pre-ROCr machine
+ list, not the survivors."""
return _gfx_has_a_wheel_route(gfx) and not (
gfx in _MIXED_HOST_UNROUTABLE and len(set(host_codes or ())) > 1
)
@@ -3108,14 +3058,9 @@ def _amd_hardware_is_corroborated() -> bool:
def _forced_rocm_route_is_viable() -> bool:
- """Whether the request has something to swap TO on this host.
-
- The bar is _gfx_has_a_wheel_route's: an arch no index can serve must never depose a card
- that can. Presence is not it (gfx1010 is present with no route). Runtime visibility is
- not it either: a runtime-less but inferable AMD card is deliberately served per-arch
- wheels on a pure-AMD host, so requiring rocminfo would answer differently for the same
- silicon by whether an NVIDIA card sits beside it.
- """
+ """Whether a forced ROCm swap has a wheel route here; the bar is _gfx_has_a_wheel_route, not
+ presence or rocminfo, since a runtime-less AMD card gets per-arch wheels on pure-AMD hosts
+ and rocminfo would answer differently beside NVIDIA."""
# ROCm wheels are x86_64 only; elsewhere standing CUDA repair down would leave torch broken.
if platform.machine().lower() not in {"x86_64", "amd64"}:
return False
@@ -3182,12 +3127,9 @@ def _forced_rocm_route_is_viable() -> bool:
def _gfx_has_a_wheel_route(gfx: "str | None") -> bool:
- """Whether ANY index this installer can pick carries kernels for ``gfx``.
-
- Either the generic pytorch.org wheel serves it or AMD publishes a per-arch index. An arch
- in neither (gfx1010 / RDNA 1) cannot be fixed by picking a different index, so it must
- never depose a card that can.
- """
+ """Whether any index this installer can pick has kernels for gfx (the generic pytorch.org wheel
+ or an AMD per-arch index); an arch in neither, like gfx1010, must never depose a card that
+ can."""
return bool(gfx) and (gfx in _GENERIC_ROCM_WHEEL_GFX or gfx in _GFX_TO_AMD_INDEX_ARCH)
@@ -3222,13 +3164,9 @@ def _linux_host_only_uncovered_amd(*arch_lists: "list[str]") -> "str | None":
return ", ".join(_archs)
-# _GENERIC_ROCM_WHEEL_GFX was measured on the tags the pins resolve (rocm7.0 and up), but
-# _ROCM_TORCH_INDEX also maps ROCm 6.0-6.4, whose wheels predate some of these arches. A host
-# can resolve an old tag while the KERNEL names a new card (a current amdgpu beside a stale
-# /opt/rocm), leaving that wheel with no kernels for it. AMD's matrices put production
-# gfx1200/gfx1201 at ROCm 6.4. gfx1150/gfx1151 need an entry despite the Strix reroute, which
-# is gated on a ROCm VERSION and so inactive on a bundled-runtime host reading 0.0; rocm7.0
-# is the oldest tag measured to carry them.
+# Per-arch minimum ROCm: the generic arch list was measured on rocm7.0 and up, but ROCm 6.0-6.4 tags
+# predate some arches, and a stale /opt/rocm can resolve one beside a new card; gfx1150 and gfx1151
+# need an entry at rocm7.0, the oldest measured tag, despite the Strix reroute.
_GENERIC_WHEEL_GFX_MIN_ROCM: "dict[str, tuple[int, int]]" = {
# gfx950 has no _GFX_TO_AMD_INDEX_ARCH entry; this only steers the generic tag choice.
"gfx950": (7, 0),
@@ -3244,13 +3182,9 @@ _GENERIC_WHEEL_GFX_MIN_ROCM: "dict[str, tuple[int, int]]" = {
def _generic_rocm_wheel_lacks_kernels(
gfx: "str | None", ver: "tuple[int, int] | None" = None
) -> bool:
- """Whether only an available AMD per-arch index carries kernels for ``gfx``.
-
- ``ver`` is the host ROCm version, when the caller has read one. Support belongs to the
- wheel a version resolves to, not to the generic index as a whole, so passing it lets an
- arch the OLD tags predate be rerouted rather than installed without kernels. Omitting it
- keeps the union reading, for callers with no version to key on.
- """
+ """Whether only an AMD per-arch index carries kernels for gfx; ver, the host ROCm version when
+ known, keys support to the wheel that version resolves to so old tags get rerouted, and
+ omitting it keeps the union reading."""
if not gfx or gfx not in _GFX_TO_AMD_INDEX_ARCH:
return False
if gfx not in _GENERIC_ROCM_WHEEL_GFX:
@@ -3581,11 +3515,9 @@ def _hsa_spoofed_physical_gfx(
)
def _confirm(physical: "list[str]", source: str) -> "str | None":
- """Decisive only when the source names the product arch and nothing else: a
- second arch means the single-arch premise was wrong (a mixed host whose
- second GPU the spoofed probe collapsed away), so decline. install.sh
- compares the same two strings, hence the verbatim KFD list and deduplicated
- re-probe."""
+ """Decisive only when the source names the product arch and nothing else; a second arch
+ means a mixed host the spoofed probe collapsed, so decline; the KFD list and re-probe are
+ verbatim and deduplicated to match install.sh."""
if physical == [inferred_gfx]:
_safe_print(
f" {source} reports {inferred_gfx} -- {probed} is a spoof of the physical arch.\n"
@@ -3666,17 +3598,9 @@ _INDEX_PROBE_LEN = 1 << 20
def _hip_layer_mask_names_a_device(device_count: int) -> bool:
- """Whether the HIP-layer mask, if set, names a device index this host has.
-
- _pick_visible_index answers 0 for a mask it cannot resolve, because for arch SELECTION a
- first-GPU guess beats no answer. Deciding whether to REPLACE a working CUDA stack is the
- opposite question: HIP exposes no device, so the ROCm wheels would land where the runtime
- hands torch nothing. install.sh fails closed on the same input.
-
- First-set-wins between the two spellings, as _pick_visible_index documents, against the
- list the HIP layer indexes (the ROCr survivors, which the caller has applied). True when
- no HIP-layer mask is set, which is not the same as failing to resolve one.
- """
+ """True when no HIP-layer mask is set, or the first one set names a device among the ROCr
+ survivors; an unresolvable mask fails closed, unlike _pick_visible_index's 0, as install.sh
+ does."""
for _env in _HIP_LAYER_MASKS:
_val = os.environ.get(_env)
if _val is None:
@@ -3899,12 +3823,9 @@ def _nvidia_smi_candidates() -> "list[str]":
def _nvidia_smi_lists_a_gpu(exe: str) -> bool:
- """Whether this nvidia-smi actually enumerates a GPU.
-
- The predicate both probes have to agree on. A stale copy can exit 0 and print a
- perfectly parseable "CUDA Version:" banner while `-L` lists nothing, which is the
- state setup.ps1's Test-NvidiaSmiHasGpu rejects.
- """
+ """Whether this nvidia-smi actually lists a GPU via -L, the predicate both probes must share; a
+ stale copy can exit 0 with a CUDA Version banner yet list nothing, as setup.ps1's
+ Test-NvidiaSmiHasGpu rejects."""
try:
result = subprocess.run(
[exe, "-L"],
@@ -3978,11 +3899,8 @@ _CU126_SM_RANGE = (50, 90)
def _cuda_family_sm_range(family: str, torch_release: str = "") -> "tuple[int, int] | None":
- """Return the supported SM span for a CUDA wheel family.
-
- cu128 and cu129 include sm_70 only for torch 2.8 through 2.10.
- An empty release models a fresh torch 2.11 installation.
- """
+ """Supported SM span for a CUDA wheel family; cu128 and cu129 include sm_70 only for torch 2.8
+ through 2.10, and an empty torch release models a fresh torch 2.11 install."""
if not _is_cuda_family_leaf(family):
return None
number = int(family[len("cu") :])
@@ -4354,13 +4272,9 @@ def _explicit_cuda_torch_index_url() -> "str | None":
def _explicit_unknown_family_torch_index_url() -> "str | None":
- """The pinned index URL when its leaf names NO known torch family, else None.
-
- Known = rocm* / gfx* / cpu / cuXXX. Anything else (a private mirror /simple,
- /current) is UNKNOWN: version-tag heuristics can't judge it, so the family
- repair helpers must leave it alone (the install applied it verbatim).
- Matches install.sh / setup.ps1 / install.ps1.
- """
+ """The pinned index URL when its leaf is no known torch family (a rocm or gfx leaf, cpu, or
+ cuXXX), else None; such unknown mirrors are left alone by family repair since the install
+ applies them verbatim. Matches install.sh, setup.ps1 and install.ps1."""
leaf = _explicit_torch_index_family()
if leaf is None:
return None
@@ -4371,9 +4285,8 @@ def _explicit_unknown_family_torch_index_url() -> "str | None":
def _deliberate_cpu_torch() -> bool:
- """Someone chose CPU torch: an explicit CPU index pin, or a manifest that recorded cpu
- as NAMED rather than selected and nothing in this run names a GPU family instead.
- An unproven cpu record is not a choice."""
+ """Someone chose CPU torch: an explicit CPU index pin, or a manifest recording cpu as named (not
+ auto-selected) when this run names no GPU family; an unproven cpu record is not a choice."""
return _explicit_cpu_torch_index_pin() or _expected_torch_flavor_was_pinned("cpu")
@@ -4717,11 +4630,7 @@ def _xpu_wheel_supported_on_disk() -> bool:
def _ensure_venv_pip() -> bool:
- """Make `python -m pip` work in the target venv, bootstrapping it if needed.
-
- `uv venv` is created without --seed, so a fresh venv has no pip at all. Mirrors the
- bootstrap install.sh already does before its pre-release bitsandbytes wheel.
- """
+ """uv venv runs without --seed, so a fresh venv has no pip; bootstrap it as install.sh does."""
def _has_pip() -> bool:
try:
@@ -4890,12 +4799,7 @@ def _ensure_xpu_triton() -> None:
def _installed_torch_label_on_disk() -> str:
- """torch.__version__ read from torch/version.py, launching no interpreter.
-
- `import torch` loads the SYCL runtime and can block indefinitely on a wedged Intel driver
- -- which is the host an explicit pin is meant to rescue, so the classifier cannot depend
- on the import succeeding. find_spec locates the package without importing it.
- """
+ """Reads torch/version.py via find_spec; importing torch can hang on a wedged Intel driver."""
try:
spec = importlib.util.find_spec("torch")
if spec is None or not spec.origin:
@@ -5025,14 +4929,7 @@ def _torch_flavor_tag(version: str) -> str:
def _gpu_family_from_runtime_markers(hip: str, cuda: str) -> str:
- """Which GPU family an untagged wheel's runtime markers name.
-
- torch.version.xpu alongside .hip and .cuda, for the reason _torch_build_is_gpu already
- reads all three: an untagged source, conda or private-index XPU build carries its
- runtime only there. Omitting it let an explicit /cpu pin over such a wheel compare
- equal, return success without replacing anything, and then record a PINNED cpu flavor
- for an environment that still holds an XPU build.
- """
+ """Must check torch.version.xpu too: omitting it let a /cpu pin falsely succeed over an XPU build."""
if hip:
return "rocm"
if cuda:
@@ -5308,12 +5205,8 @@ def _expected_torch_index_url(tag: str) -> "str | None":
def _explicit_cpu_torch_index_pin() -> bool:
- """Whether this run was pinned to a CPU wheel index, by URL or by family.
-
- Only a pin counts. setup.ps1's published tag also reads "cpu" for a host whose
- nvidia-smi probe simply returned nothing, and treating that as an instruction would
- let a wedged driver downgrade a healthy CUDA venv.
- """
+ """Only a pin counts: setup.ps1's cpu tag also appears when nvidia-smi returns nothing, and
+ acting on it would let a wedged driver downgrade a healthy CUDA venv."""
return _explicit_torch_index_family() == "cpu"
@@ -5404,8 +5297,7 @@ def _warn_still_cpu(expected: str) -> bool:
def _uninstall_distribution(name: str) -> bool:
- """Remove one distribution from the venv this script targets. True iff it is gone.
- Output is swallowed; the caller reports."""
+ """True iff the distribution is gone; output is swallowed, so the caller reports the outcome."""
cmd = uninstall_command(
name, use_uv = USE_UV and bool(shutil.which("uv")), uv_needs_system = UV_NEEDS_SYSTEM
)
@@ -5690,11 +5582,7 @@ def _ensure_expected_torch_flavor(expected: "str | None" = None) -> bool:
def _missing_torch_needs_dependency_pass() -> bool:
- """Missing torch that the dependency pass can actually reinstall, read from metadata.
-
- Gated on a live core requirement, so Apple Silicon (unsloth-zoo's torch marker is
- false there) does not run a useless pass on every update.
- """
+ """Gated on a live core requirement, since unsloth-zoo's torch marker is false on Apple Silicon."""
if NO_TORCH or _installed_distribution_version("torch") is not None:
return False
try:
@@ -5720,14 +5608,9 @@ def _missing_torch_needs_dependency_pass() -> bool:
def _cuda_torch_needs_dependency_pass() -> bool:
- """Return True when only the dependency pass can put CUDA torch back on this host.
-
- The repair lives inside that pass, so an install whose GPU was hidden (or whose driver
- was broken) at install time keeps its CPU wheel on every "up to date" update until the
- package version happens to move. Answered by the repair in probe mode, so the two can
- never disagree; Windows heals this at setup.ps1's stale-venv check and macOS has no
- CUDA, and the repair already excludes both. Never installs, and fails closed.
- """
+ """True when only the dependency pass can restore CUDA torch (a GPU hidden or a broken driver at
+ install time leaves a CPU wheel); answered by the probe-mode repair; never installs; fails
+ closed."""
try:
return bool(_ensure_cuda_torch(probe_only = True))
except Exception: # noqa: BLE001 - a probe that cannot answer keeps the fast path
@@ -5747,12 +5630,7 @@ def _xpu_torch_needs_dependency_pass() -> bool:
def _amd_torch_needs_dependency_pass() -> bool:
- """Return True when setup must run the dependency pass to repair non-ROCm torch.
-
- Scope is the wheel family, not the ROCm family: any ROCm marker keeps the fast path
- even when the repair would reroute it. Fails closed on an uncertain host or torch,
- and never installs.
- """
+ """Scoped to the wheel family, so any ROCm marker keeps the fast path; fails closed, never installs."""
if NO_TORCH or not IS_LINUX:
return False
if platform.machine().lower() not in {"x86_64", "amd64"}:
@@ -5798,9 +5676,8 @@ def _amd_torch_needs_dependency_pass() -> bool:
and _linux_host_only_uncovered_amd(_selected_codes, _selected_host)
):
return False
- # The compatibility reroutes have no version floor either, so a host whose ROCm
- # version will not read must not be turned away before they are asked. Only with a
- # torch that reads back: an unreadable one is not evidence its wheels are wrong.
+ # Reroutes lack a version floor, so unreadable ROCm must not block them; torch must read
+ # back.
if _pre_torch and _rocm_compat_reroute_pending(
_selected_gfx, _detect_rocm_version() or (0, 0), _pre_torch
):
@@ -5840,23 +5717,16 @@ def _amd_torch_needs_dependency_pass() -> bool:
# Strix below the AMD floor and gfx906 above rocm6.3 also need the pass on update.
if _rocm_compat_reroute_pending(_tail_gfx, _tail_ver, _version.lower()):
return True
- # The generic bitsandbytes wheel is built for the rocm6.4 ABI. An automatic host therefore
- # needs a torch reinstall when its existing generic wheel still names an older ABI;
- # explicit pins, per-arch wheels, and gfx906 are excluded by the helper so their
- # established routing remains authoritative.
+ # Generic bnb wheel is rocm6.4 ABI: an older one needs a torch reinstall, except pins and
+ # gfx906.
if _generic_rocm_bnb_floor_pending(_tail_gfx, _detect_rocm_version(), _version.lower()):
return True
return _rocm_torch_family_needs_repair(_tail_gfx, _detect_rocm_version(), _tail_host)
def _already_on_amd_arch_leaf(leaf: "str | None", installed_ver: str) -> bool:
- """True when the installed torch already IS the AMD per-arch build for ``leaf``.
-
- The family is the direct reading. A family that will not read back is not evidence of the
- wrong wheels, so the local tag is accepted too: only the AMD index ships a rocm tag at or
- above the arch floor, and re-downloading a multi-GB stack each update to re-establish what
- the tag already says is the cost this guard avoids.
- """
+ """Accepts the local rocm tag when the family will not read, to avoid a multi-GB AMD stack
+ redownload."""
if _torch_below_211(installed_ver):
return False
_family = _installed_rocm_wheel_family() if _torch_requires_rocm_sdk() else None
@@ -5993,16 +5863,7 @@ def _windows_rocm_device_packs_need_dependency_pass() -> bool:
def _ensure_rocm_torch() -> "bool | None":
- """Reinstall torch with ROCm wheels when the venv received CPU-only torch.
-
- On Linux x86_64: uses pytorch.org ROCm wheel index tags.
- On Windows: uses AMD's repo.amd.com arch-specific pip index.
- No-op on macOS, non-x86_64 Linux, NVIDIA-primary hosts, or when torch
- already links against HIP.
- Uses pip_install() to respect uv, constraints, and --python targeting.
- False: a Linux repair is required but the mirror cannot express its index; the caller
- aborts.
- """
+ """False when a Linux repair is needed but the mirror cannot express its index; the caller aborts."""
global _rocm_windows_torch_installed
# install.sh's resolved backend is authoritative; avoids re-detecting in a different env.
if _TORCH_BACKEND in ("cuda", "cpu", "xpu"):
@@ -6217,20 +6078,15 @@ def _ensure_rocm_torch() -> "bool | None":
and not has_hip_torch
and not _rocm_pinned
and (_gfx_override_env or not _has_rocm_gpu())
- # This branch installs for the inferred arch without asking the mask layers, so an
- # ordinal the guess cannot account for reaches the wheel the preflight already
- # declines. An explicit arch is exempt above, and no ordinal contradicts it.
+ # Inferred-arch install skips mask layers, so an unexplained ordinal could reach a declined
+ # wheel.
and (
_gfx_override_env
or (_inferred_target := _runtime_gfx_target(_inferred_linux_gfx)[0]) is not None
)
):
- # The discrete card a leading Strix deferred to. One served only by the generic index
- # (gfx942) skips this per-arch install: the generic route below installs for it, since
- # the deferral already required a readable ROCm version.
- # Only to a card something installs for (a per-arch index, a generic tag, or a known
- # minimum generic tag the fallback below picks without a version, e.g. gfx950): a target
- # moved by KFD order on a versionless host with none of these would leave CPU torch.
+ # Defer only to a card some index installs for; otherwise a versionless host can end up on
+ # CPU torch.
if (
not _gfx_override_env
and _inferred_target != _inferred_linux_gfx
@@ -6492,10 +6348,9 @@ def _ensure_rocm_torch() -> "bool | None":
# gfx906 detection for the bnb skip holds even under a torch-index pin, so a source-built bnb is not
# overwritten; the pin only suppresses the torch reroute.
_runtime_is_gfx906 = _runtime_target_is_gfx906()
- # The generic bitsandbytes ROCm wheel targets the rocm6.4 ABI. Re-run the automatic
- # generic torch selection when an existing generic wheel below that ABI would otherwise
- # be paired with it. This is intentionally after the per-arch/missing-kernel routing and
- # excludes explicit pins and gfx906's legacy path.
+ # Intentionally after per-arch and missing-kernel routing: reruns generic torch selection if an
+ # older-ABI generic bnb wheel (below the rocm6.4 ABI) would pair with it; not for pins or the
+ # gfx906 legacy path.
if (
rocm_torch_ready
and _rocm_pin is None
@@ -6509,10 +6364,8 @@ def _ensure_rocm_torch() -> "bool | None":
"-- reinstalling from the compatible generic index."
)
rocm_torch_ready = False
- # Reroute torch to the last gfx906-capable wheel family (rocm6.3) only when the
- # host ROCm version would otherwise pick a newer, kernel-less index -- and never
- # over an explicit pin or an active Strix reroute (the pin/Strix path installs
- # its own index; only the bnb skip must still apply on those paths).
+ # Reroute to rocm6.3 (last gfx906 wheels) only if ROCm would pick a kernel-less index; never
+ # over an explicit pin or Strix reroute, though the bnb skip must still apply on those paths.
_gfx906_override = (
_runtime_is_gfx906
and _gfx906_needs_legacy_index(ver)
@@ -6582,12 +6435,8 @@ def _ensure_rocm_torch() -> "bool | None":
elif _rocm_pin_unusable:
tag = _pin_family
else:
- # Automatic generic installs must use the ABI floor required by the
- # generic bitsandbytes wheel, but only for a target known NOT to be gfx906:
- # gfx906 keeps its legacy rocm6.0-6.3 path (rocm6.4 has no gfx906 BLAS
- # kernels), and an unreadable arch might be one, so it keeps the literal
- # resolver as before. _runtime_gfx also carries a KFD-only reading that
- # _runtime_is_gfx906 does not see. Same gfx906 exclusion as the repair above.
+ # ABI floor applies only to targets known not to be gfx906, since rocm6.4 has no gfx906
+ # BLAS kernels.
_bnb_floor_target = (
bool(_runtime_gfx) and _runtime_gfx.lower() != "gfx906" and not _runtime_is_gfx906
)
@@ -6865,12 +6714,8 @@ _UNICODE_TO_ASCII: dict[str, str] = {
def _safe_print(*args: object, **kwargs: object) -> None:
- """Drop-in print() replacement that survives non-UTF-8 consoles and detached stdout.
-
- Closes an open progress bar line first: _progress() leaves the cursor mid-line,
- so centralising it here (nothing calls print() directly -- see
- test_no_bare_print_calls) keeps every message off the bar.
- """
+ """Print that survives non-UTF-8 consoles and detached stdout; closes the progress line
+ _progress leaves open; test_no_bare_print_calls forbids direct print()."""
_end_progress_line()
try:
print(*args, **kwargs)
@@ -7108,17 +6953,9 @@ WOA_OVERRIDES_HEADER = "# Generated by install.ps1 for Windows on ARM"
def _woa_overrides_are_load_bearing() -> bool:
- """Is this a native win_arm64 resolve whose correctness depends on UV_OVERRIDE?
-
- install.ps1 writes those overrides to lift the released torch cap -- no win_arm64 CUDA
- wheel satisfies it -- and to drop the packages with no win_arm64 build. pip has no
- override mechanism at all: constraints only narrow a requirement, they cannot replace
- one, so there is nothing to translate them into. Falling back to pip on this stack does
- not recover, it silently resolves the wrong thing.
-
- Judged by the generated file, not by the variable: a caller's own override on a run that
- never configured the stack (--no-torch, a direct run) keeps the fallback every host has.
- """
+ """Native win_arm64 resolve needing the UV_OVERRIDE that install.ps1 generates (pip cannot apply
+ overrides, so falling back silently mis-resolves); judged by that generated file, not the
+ variable, so a caller's own override keeps the fallback."""
if not _is_win_arm64_interpreter():
return False
for path in os.environ.get("UV_OVERRIDE", "").split():
@@ -7205,17 +7042,8 @@ WINDOWS_ARM64_SKIP_PACKAGES = {
def _wheel_matches_interpreter(filename: str) -> bool:
- """Can THIS interpreter install the wheel named ``filename``?
-
- A wheelhouse is not built for one interpreter: install.ps1 stages every win_arm64
- wheel it finds, cp311 through cp314, as the wheelhouse published them. So a filename
- is not proof on its own -- a cp311 tiktoken is invisible to a cp313 resolver, and
- counting it as available drops the skip and sends the resolve to an sdist that cannot
- build here. PEP 425: a wheel is installable when one of its (python, abi, platform)
- triples is one the interpreter supports, and each filename field may be a
- "."-separated set expanded as their cartesian product. Unparseable means not
- installable, which only leaves the conservative skip in place.
- """
+ """Can this interpreter install the wheel? PEP 425 tag match, since the wheelhouse stages cp311
+ to cp314 alike; unparseable means not installable, keeping the conservative skip in place."""
stem = filename[:-4] if filename.lower().endswith(".whl") else filename
parts = stem.split("-")
if len(parts) < 5:
@@ -7372,13 +7200,8 @@ def _version_satisfies(version: str, specifier: str) -> "bool | None":
def _marker_is_active(marker: str) -> "bool | None":
- """Does ``marker`` hold for THIS interpreter? None when it cannot be decided.
-
- packaging is what pip and uv evaluate markers with, so borrowing it keeps the answer
- identical to the resolver's; pip vendors a copy, which is the fallback for a venv
- where packaging is not installed in its own right. Neither available means the
- caller keeps every clause instead of picking one.
- """
+ """Evaluates with packaging as pip and uv do, else pip's vendored copy; None if neither is
+ importable."""
if not marker:
return True
for module_name in ("packaging.markers", "pip._vendor.packaging.markers"):
@@ -7456,11 +7279,7 @@ def _wheelhouse_hosts(name: str) -> bool:
def _wheelhouse_best_version(name: str, floor: str) -> "str | None":
- """The newest hosted version that clears ``floor``, or None if none does.
-
- An unreadable comparison keeps the answer it would have had before this floor
- existed, matching _windows_arm64_skip_packages: an exotic version is no worse off.
- """
+ """Unreadable version comparisons keep the pre-floor answer, matching _windows_arm64_skip_packages."""
hosted = _find_links_wheel_versions().get(_canonical_dist_name(name)) or ()
usable = [
version
@@ -7477,11 +7296,8 @@ def _wheelhouse_best_version(name: str, floor: str) -> "str | None":
def _wheelhouse_torchcodec_version(torch_version: "str | None") -> "str | None":
- """The hosted torchcodec inside the window this torch selects, or None.
-
- win_arm64 only: elsewhere the platform's own wheel decides. An unknown torch has no
- window, so it gets no answer either.
- """
+ """win_arm64 only, elsewhere the platform wheel decides; an unknown torch has no window and gets
+ None."""
if not _is_win_arm64_interpreter() or not torch_version:
return None
spec = _select_torchcodec_spec(torch_version)
@@ -7491,15 +7307,7 @@ def _wheelhouse_torchcodec_version(torch_version: "str | None") -> "str | None":
def _install_wheelhouse_optionals() -> None:
- """Install the hosted optionals the metadata cannot ask for. Best effort.
-
- --no-deps: the graph is already resolved and installed by the time this runs, and
- xformers names torch, so resolving here could walk the win_arm64 CUDA build off to
- whatever PyPI offers. A failure leaves the feature off, which is where it was.
-
- Pinned to the selected version rather than installed by bare name, so the floor
- checked here is the version that actually lands.
- """
+ """Best effort; --no-deps stops xformers pulling torch off its CUDA build; pins the checked version."""
if not _is_win_arm64_interpreter():
return
for name, floor in WINDOWS_ARM64_WHEELHOUSE_OPTIONALS.items():
@@ -7542,12 +7350,9 @@ def _torch_build_family(label: str) -> str:
def _evict_xformers_built_for_another_torch(
scope: str = "windows on arm", family_only: bool = False
) -> bool:
- """Remove a resident xFormers whose extension was built against another torch. True iff removed.
-
- xFormers links its extension against ONE (torch, CUDA) pair; beside any other it is mute,
- and a package install never uninstalls what an earlier run left behind. family_only keeps one
- of the same family and CUDA major (stable ABI since 0.0.34; _C.so links libcudart.so.<major>).
- """
+ """Evicts a resident xFormers built for another torch, since a package install never uninstalls
+ what an earlier run left behind; family_only keeps the same CUDA major (stable ABI since
+ 0.0.34); True iff removed."""
built_for = _resident_xformers_build_torch()
resident = str(_probe_installed_torch_version() or "")
if not (built_for and resident and built_for != resident):
@@ -8006,11 +7811,9 @@ SDIST_ONLY_PACKAGES = (
def _sdist_only_build_args(*names: str) -> list[str]:
- """``--no-binary`` for each named wheel-less requirement, for uv and pip alike.
-
- Naming a package that the resolution never reaches is harmless (verified), so this
- is safe next to the NO_TORCH / Windows requirement filtering.
- """
+ """Emits --no-binary NAME for each named wheel-less requirement, for uv and pip alike; naming a
+ package the resolution never reaches is harmless, so it is safe beside NO_TORCH and Windows
+ filtering."""
args: list[str] = []
for name in names:
args += ["--no-binary", name]
@@ -8049,12 +7852,7 @@ _FLASH_ATTN_IMPORT_PROBE_TIMEOUT = 300
def _flash_attn_importable() -> bool:
- """Whether flash_attn imports, checked out of process.
-
- A wrong-arch/ABI wheel installs fine and raises on import, so a zero pip exit code is
- not proof the install is usable. In a child, so a half-loaded native extension cannot
- poison the installer, and bounded, since initialisation can hang rather than fail.
- """
+ """Runs in a bounded child: a wrong-arch wheel installs with exit 0 yet fails on import, or hangs."""
try:
result = subprocess.run(
[sys.executable, "-c", _rocm_flash_attn.IMPORT_PROBE],
@@ -8090,8 +7888,7 @@ def _remove_stale_flash_attn() -> None:
def _flash_attn_gpu_below_floor() -> bool:
- """A visible CUDA GPU below sm80 (a T4), where Unsloth leaves FlashAttention 2 off. No visible
- GPU is False: an image build installs ahead of the GPU it will run on."""
+ """Visible CUDA GPU below sm80 (a T4); no visible GPU is False, since image builds install first."""
return gpu_below_flash_attn_floor()
@@ -8400,8 +8197,7 @@ def _bootstrap_uv() -> bool:
return True
-# CA trust floor. certifi 2026.10.19 drops the distrusted emSign ECC Root CA - G3. pip before 26.2.2
-# always verifies TLS with its own vendored certifi (pip dropped Python 3.9 before that release).
+# certifi 2026.10.19 drops distrusted emSign G3 root; pip before 26.2.2 uses its vendored certifi.
_TRUST_FLOOR_CERTIFI = "certifi>=2026.10.19"
_TRUST_FLOOR_PIP = "pip>=26.2.2"
@@ -8432,14 +8228,7 @@ def _ensure_trust_floor() -> None:
def _venv_pip_is_usable() -> bool:
- """Whether this interpreter already has a pip new enough for the pass.
-
- Read from metadata rather than by spawning it: the bootstrap below reinstalls pip from the
- index on every run, a download and a resolve for a package nothing changed. 23.0 is the
- floor because the constraint and override handling the pass relies on predates it
- comfortably; a fresh uv venv has no pip at all and still bootstraps. On Python 3.10+ the
- floor is the trust floor's pip, since an older pip verifies TLS with its own vendored certifi.
- """
+ """Checks pip metadata, not a spawn: floor is 23.0, or the trust-floor pip on Python 3.10 and up."""
try:
if importlib.util.find_spec("pip") is None:
return False
@@ -8459,8 +8248,7 @@ def _venv_pip_is_usable() -> bool:
and _version_satisfies(installed, _TRUST_FLOOR_PIP[3:]) is not True
):
return False
- # Metadata survives a truncated pip, and everything without uv is `python -m pip`: one bounded
- # launch settles it.
+ # Metadata survives a truncated pip, so one bounded python -m pip --version launch settles it.
try:
probe = subprocess.run(
[sys.executable, "-m", "pip", "--version"],
@@ -8542,12 +8330,8 @@ def _overlay_local_core_package(
*,
strict: bool = True,
) -> bool:
- """Install one core package from the source selected by --local.
-
- strict=False reports a failed install instead of exiting, which the metadata
- repair needs: by the time it installs, it has already removed the records it
- is replacing, so it has to say so rather than die mid-way.
- """
+ """strict=False reports failure instead of exiting, since metadata repair already removed its
+ records."""
canonical = re.sub(r"[-_.]+", "-", name).lower()
if canonical == "unsloth":
step_label = f"overlaying local repo (editable): {local_repo}"
@@ -8594,11 +8378,7 @@ def _is_overlayable_core_package(name: str) -> bool:
def _overlay_source_spec(name: str, local_repo: str) -> str:
- """What pip would be asked to build for this overlay.
-
- unsloth-zoo comes from git, so an overlay is a network fetch just as much as
- an index install is: it has to be staged before anything is uninstalled.
- """
+ """Overlay is a git fetch for unsloth-zoo, so it must be staged before anything is uninstalled."""
canonical = re.sub(r"[-_.]+", "-", name).lower()
if canonical == "unsloth":
return local_repo
@@ -8608,15 +8388,7 @@ def _overlay_source_spec(name: str, local_repo: str) -> str:
def _rewrite_minimal_metadata(path: str, name: str) -> bool:
- """Replace an unparseable METADATA with the least pip needs to uninstall by RECORD.
-
- Returns False when there is no RECORD to uninstall from, the one case that has
- to fail closed: without it neither pip nor this installer knows which files
- belong to the package, and laying a replacement over them would leave whatever
- the new release no longer ships behind, still importable. The version is taken
- from the directory name, where importlib's own fallback reads it from when
- METADATA cannot be parsed.
- """
+ """False without a RECORD (fails closed: stale files would stay importable); version from dir name."""
path = os.fspath(path)
if not os.path.isfile(os.path.join(path, "RECORD")):
return False
@@ -8653,18 +8425,8 @@ class _QuarantinedMetadata:
return self._holding
def back_up(self, path) -> bool:
- """Keep a copy of a file that is about to be rewritten in place.
-
- The rewrite has to happen before staging, and staging can still fail. Without
- this the original is gone and what remains is a synthetic record that parses:
- the next run would see one readable record, decide nothing is wrong, and never
- attempt the payload repair that is still owed.
-
- An absent METADATA is nothing to back up rather than a failure. Recording it
- as absent still lets the rewrite proceed, so pip can uninstall that record by
- its RECORD; restore() then deletes the synthetic file instead of reinstating
- one that never existed.
- """
+ """Backs up before rewriting in place, so failed staging can't leave a parseable record
+ hiding repair."""
path = os.fspath(path)
if not os.path.exists(path):
self._copied.append((path, None))
@@ -8690,14 +8452,7 @@ class _QuarantinedMetadata:
return True
def forget_copies(self) -> None:
- """Drop the backed-up METADATA copies, keeping the moved directories.
-
- Called once a staged reinstall has put the package back: the wheel's own
- metadata is authoritative, so copying the original over it would re-break the
- package the rollback just repaired, and deleting it (where the original was
- absent) would strip a record pip just wrote. The moved entries stay, because a
- record pip cannot consume still has to go back as found.
- """
+ """Drops the backups after a staged reinstall, since wheel metadata wins; moved entries are kept."""
self._copied.clear()
def restore(self) -> None:
@@ -8732,12 +8487,7 @@ def _restore_from_staged(
removed_any: bool,
quarantine: "_QuarantinedMetadata | None" = None,
) -> None:
- """Put the payload back when the uninstall loop stops part way through.
-
- An earlier successful uninstall has already deleted the package tree, so
- returning here without this leaves a surviving dist-info claiming an
- installed core package whose files are gone.
- """
+ """Restores the payload if uninstall stops midway, else dist-info claims files that are gone."""
if not (removed_any and staged):
return
if pip_install_try(
@@ -8764,12 +8514,8 @@ def _restore_from_staged(
def _requirement_args(requirement: str, staging: str) -> "list[str]":
- """How to hand pip the requirement, as a file when it carries hashes.
-
- pip only accepts --hash entries from a requirements file, and the hashes are what
- stop it accepting a different artifact of the same version from a source uv never
- considered. The file lives in the staging directory, so it is removed with it.
- """
+ """pip accepts --hash only from a requirements file, which blocks other artifacts of the same
+ version."""
if "--hash=" not in requirement:
return [requirement]
path = os.path.join(staging, "requirement.txt")
@@ -8779,20 +8525,8 @@ def _requirement_args(requirement: str, staging: str) -> "list[str]":
def _stage_replacement(name: str):
- """Build the wheel that will replace a package, before it is removed.
-
- Returns a directory to install from, or None when the package cannot be
- obtained, which must abort the repair while the existing install is still
- intact.
-
- pip wheel, not pip download: a source-only index leaves an sdist, and the
- install that follows runs --no-index, so its isolated build could not fetch
- setuptools and the package would stay uninstalled. Building here, while the
- index is still reachable, keeps that install offline-safe. pip and not uv
- because uv has no `wheel` subcommand, so uv's own index variables and upload
- cutoff have to be handed across explicitly to keep the provenance and the
- reproducibility policy the other installs run under.
- """
+ """Builds the wheel via pip while the index is reachable (uv lacks wheel); None aborts before
+ removal."""
requirement, overrides, build_options = name, {}, []
offline_local = USE_UV and _uv_is_offline() and _is_local_source(name)
if offline_local:
@@ -9238,11 +8972,8 @@ def _build_uv_cmd(args: tuple[str, ...]) -> list[str]:
def _pinned_cmd_and_env(cmd: "list[str]") -> "tuple[list[str], dict[str, str] | None]":
- """A command with its pinned binary-policy arguments, and the env it runs with, from ONE read.
-
- A failed read is not memoised, so a second one can succeed: the policy would then reach
- the environment but not the argv that carries it (uv) or exempts from it (both).
- """
+ """Reads the policy once: a second read could succeed and split the env from the argv that
+ carries it."""
env = _install_env_for_cmd(cmd)
return cmd + _pinned_binary_policy_args(cmd, env), env
@@ -9350,11 +9081,7 @@ def _relaxed_pip_policy_env(cmd: "list[str]") -> "dict[str, str]":
def _executable_stem(path: str) -> str:
- """argv[0] as a bare program name, on either platform's spelling.
-
- Both separators, because os.path.basename does not split a backslash off-Windows and
- the same argv reaches here from a Windows host, a test, or WSL interop.
- """
+ """Splits on forward and back slashes, since os.path.basename misses backslashes off Windows."""
leaf = re.split(r"[\\/]", path)[-1]
return leaf.split(".")[0].lower()
@@ -9630,14 +9357,7 @@ def _is_local_source(requirement: str) -> bool:
def _is_direct_reference(requirement: str) -> bool:
- """True when the requirement already names the source to build from.
-
- The overlay paths hand staging a git URL or a local checkout rather than a bare
- name, and such a requirement carries its own provenance: no index was consulted
- to choose it, so there is nothing for uv to have decided and nothing to preserve.
- Asking uv to resolve it would also compare a bare spec against uv's output, which
- appends the resolved commit and so could never match.
- """
+ """Git URLs and local paths carry their own provenance; uv's output appends a commit to git URLs."""
return "://" in requirement or _is_local_source(requirement)
@@ -9757,14 +9477,7 @@ def _pip_subcommand_of(cmd: "list[str]") -> str:
def _pinned_pip_config_overrides(
subcommand: str = _PINNED_PIP_CONFIG_DEFAULT_SECTION,
) -> "dict[str, str]":
- """pip's configured transport and binary policy, as PIP_ environment variables.
-
- ONLY a successful read is memoised, or a transient miss would cost the operator their
- cert and proxy for the rest of the run, and a venv with no pip yet could never answer
- once it has one. A HANG is budgeted instead, so a wedged pip costs the run one timeout
- budget rather than one per pinned command. Empty when pip cannot answer, the normal
- case early in a fresh venv. `:env:` rows are skipped: the child inherits those.
- """
+ """Memoises only successful reads, budgets a hang once, and skips :env: rows the child inherits."""
global _PINNED_PIP_CONFIG_LISTING, _PINNED_PIP_CONFIG_ATTEMPTS
if _PINNED_PIP_CONFIG_LISTING is not None:
return _parse_pinned_pip_config(_PINNED_PIP_CONFIG_LISTING, subcommand)
@@ -10168,8 +9881,7 @@ def _desktop_unsloth_spec(package_name: str) -> "tuple[str, str]":
available = newest(f"unsloth<={zoo}") if zoo else None
if available is None:
return spec, zoo_spec
- # A newer unsloth whose zoo floor the index still meets beats that bound (unsloth patch
- # releases often ship without a zoo release).
+ # Newer unsloth beats the zoo bound when the index meets its floor, as patches often lack a zoo.
pair = resolve(f"unsloth>={available}", zoo_spec, deps = True) or {}
if pair.get("unsloth") and pair.get("unsloth-zoo"):
available, zoo = pair["unsloth"], pair["unsloth-zoo"]
@@ -10452,10 +10164,9 @@ _MLX_NAMES: tuple[str, ...] = tuple(spec.partition("==")[0] for spec in _MLX_PIN
"mlx-lm",
"mlx-vlm",
)
-# mflux goes in --no-deps: its declared torch / transformers floors would move the MLX pins, and Z-Image
-# needs only the deps below. Best-effort: a failure must never mark the MLX stack broken.
-# Pillow is capped: mflux imports PIL._typing, which in Pillow 13.0.0 needs numbers._IntegralLike,
-# absent on CPython 3.11 - 3.14, so every mflux import fails with it.
+# mflux is --no-deps so its torch and transformers floors cannot move the MLX pins; best-effort, and
+# a failure must never mark the MLX stack broken; Pillow is capped below 13 since 13.0.0 breaks
+# mflux on CPython 3.11-3.14.
_MLX_DIFFUSION_PINS: tuple[str, ...] = ("mflux==0.22.0",)
_MLX_DIFFUSION_DEPS: tuple[str, ...] = (
"pillow>=12.3.0,<13",
@@ -10543,12 +10254,7 @@ def _mlx_spec_for_installed_zoo(spec: str) -> str:
def _mlx_stack_is_current() -> bool:
- """Whether the exact pins and the mlx-lm and mlx-vlm ranges are all already satisfied.
-
- Without this the step ran `--upgrade` on every update and fetched ~60 MB of wheels
- it then discarded, because the pins were already exact and the upgrade only moved
- mlx-vlm inside a range it was already in.
- """
+ """Skips --upgrade when exact pins and ranges already hold, avoiding a wheel refetch on every update."""
if not all(_exact_distribution_spec_is_installed(spec) for spec in _MLX_PINS):
return False
installed, installed_lm = (
@@ -10563,9 +10269,8 @@ def _mlx_stack_is_current() -> bool:
prereleases = True,
):
return False
- # The narrowed spec, not the static one: with an older zoo beside an already-installed
- # 0.7.1 the static range reads as satisfied and the step skips the very install that
- # would put mlx-vlm back where the zoo can drive it.
+ # Checks the narrowed spec: the static range reads installed 0.7.1 as satisfied beside an
+ # older zoo.
if not Requirement(_mlx_vlm_spec_for_installed_zoo()).specifier.contains(
installed,
prereleases = True,
@@ -10673,13 +10378,7 @@ def _mlx_health_fingerprint() -> dict:
def _mlx_payload_present() -> bool:
- """The MLX stack's payload is on disk as its RECORDs describe it, without importing it.
-
- The recorded verdict below is keyed on pins and interpreter, which a payload deleted or
- truncated after the pass leaves unchanged, and find_spec sees only the top-level
- directory. So every file each RECORD names is checked for presence and size (bytecode
- excepted, it is regenerated): a few hundred stats, well under the import the probe pays.
- """
+ """Checks each RECORD file for presence and size without importing; cached verdicts miss deletions."""
try:
import importlib.metadata
import importlib.util
@@ -10703,13 +10402,8 @@ def _mlx_payload_present() -> bool:
def _recorded_payload_damaged(dist_name: str) -> "bool | None":
- """Whether a file the distribution's RECORD names is gone or has another size.
-
- None when the distribution has no readable RECORD, which is not evidence of an intact
- payload. Read from RECORD rows, not Distribution.files: CPython 3.13 drops paths that no
- longer exist from `files`, so a deleted file is never found through it. Bytecode is left
- out (recompiled after install); rows without a size say nothing.
- """
+ """Reads RECORD, not Distribution.files: CPython 3.13 drops missing paths from it; None if
+ unreadable."""
import csv
import io
@@ -10733,17 +10427,9 @@ def _recorded_payload_damaged(dist_name: str) -> "bool | None":
def _report_mlx_stack_health(skipped: bool = False) -> None:
- """Name what would keep Train off on this Apple Silicon host, if anything.
-
- Advisory only: the install has succeeded, chat still works and the self-heal gets another
- go at startup. It just must not be silent, which is the whole of "Train is blacked out
- after an update".
-
- Run out of process, since a half-installed mlx can abort rather than raise. That costs a
- full torch and mlx import, so the recorded verdict stands when the MLX step was skipped,
- nothing else installed anything, and the last run recorded a healthy stack for these exact
- pins and this interpreter. Anything else runs the probe.
- """
+ """Advisory only, and must not be silent: names what keeps Train off on Apple Silicon; runs out
+ of process since a half-installed mlx can abort; recorded verdict stands only if MLX was
+ skipped, nothing installed, and the last run was healthy."""
fingerprint = _mlx_health_fingerprint()
recorded = (_PASS_EVIDENCE or {}).get("mlx_health")
if (
@@ -11024,12 +10710,7 @@ def _plan_pass(package_name: str, local_repo: str, ci_source_overlay: str) -> "d
def _effective_requirements(req: Path) -> "tuple[Path, list[Path]]":
- """The file pip_install will really install from, plus temp copies to unlink.
-
- Shared with pip_install so the skip gate audits exactly what the install would do.
- extras.txt names torchcodec and three platforms filter it out; auditing the raw file
- would report it missing on every one of them and never skip anything again.
- """
+ """Filtered file pip_install installs; raw extras.txt names torchcodec, dropped on three platforms."""
temps: list[Path] = []
actual = req
if IS_WINDOWS and WINDOWS_SKIP_PACKAGES:
@@ -11060,12 +10741,7 @@ def _pass_input_key(path: Path) -> "str | None":
def _violated_constraints() -> "list[str]":
- """Constrained distributions currently outside their pin.
-
- Recomputed whenever something was installed: a constraint the last step satisfied
- must not keep the next one running, and one it broke must not be missed. Cached
- otherwise, because every gated step asks.
- """
+ """Recomputed after any install so a satisfied or broken constraint is never stale; cached otherwise."""
global _CONSTRAINTS_CACHE
if _CONSTRAINTS_CACHE is None or _CONSTRAINTS_CACHE[0] != _INSTALL_ACTIONS:
try:
@@ -11080,8 +10756,7 @@ _CLOSURE_INDEX_CACHE: "tuple[int, dict | None] | None" = None
def _installed_index_digest() -> "str | None":
- """One sha256 over (name, version) of everything installed: what a recorded conflict
- is evidence about. None when the index cannot be read, which matches no record."""
+ """sha256 of all installed (name, version); None when unreadable, which matches no recorded conflict."""
import hashlib
index = _installed_index()
@@ -11148,11 +10823,7 @@ _INCLUDE_FLAGS = ("-r", "--requirement", "-c", "--constraint")
def _includes_another_requirements_file(req: Path) -> bool:
- """Whether *req* pulls in a second file the pass_inputs digests do not cover.
-
- Unreadable counts as "yes": a file this cannot read is one whose contents the gate cannot
- stand behind either, and the step running is the safe answer.
- """
+ """True if req includes a file the pass_inputs digests miss; unreadable counts as True, failing safe."""
try:
text = req.read_text(encoding = "utf-8-sig")
except (OSError, ValueError, UnicodeDecodeError):
@@ -11418,8 +11089,7 @@ def _direct_reference_is_installed(req: Path, dist_name: str) -> bool:
def _payload_recorded_intact(dist_name: str) -> bool:
- """True only when the distribution has a RECORD and every file it names is there
- at its recorded size; a missing distribution or RECORD is not intact."""
+ """True only if its RECORD exists and every file it names is present at its recorded size."""
try:
return _recorded_payload_damaged(dist_name) is False
except Exception: # noqa: BLE001 - not installed, or unreadable, is not intact
@@ -11470,9 +11140,8 @@ def _triton_kernels_step() -> None:
DIFFUSERS_MAIN_ENV = "UNSLOTH_DIFFUSERS_MAIN"
-# Diffusers main declares requires-python >= 3.11 (huggingface/diffusers#15030) while the release
-# pin covers 3.10 (0.41.0) and 3.9 (0.36.0), so both are supported installs this step can never
-# satisfy. They keep the release and only a model that needs the main build is unavailable.
+# Diffusers main needs Python 3.11+ (huggingface/diffusers 15030); 3.10 keeps release pin 0.41.0 and
+# 3.9 keeps 0.36.0, so only a model needing the main build is unavailable there.
DIFFUSERS_MAIN_MIN_PYTHON = (3, 11)
@@ -11597,16 +11266,9 @@ def _diffusers_main_archive(req: Path) -> "str | None":
def _diffusers_main_needs_dependency_pass() -> bool:
- """For the setup fast path: is the resident Diffusers the wrong one for the requested mode?
-
- The fast path skips this script whenever the core package is current, so without this an
- install that never ran 11c (updated by an installer that predates it, or opted back in) stays
- on the release until the next version bump. The same gates as 11c decide whether the pass
- could install the build at all, so a host with neither git nor the zip route keeps its fast
- path. A pass that tried
- and failed records "failed" and also keeps it: without that, a host that cannot reach
- github.com would repeat the whole dependency pass on every update.
- """
+ """Is the resident Diffusers the wrong build for the mode? Hosts with neither git nor the zip
+ route keep the fast path, and a recorded failure also keeps it, so an unreachable github.com
+ does not retry each update."""
req = REQ_ROOT / "diffusers-main.txt"
if not req.is_file() or not _diffusers_main_active(req):
# Not same-version damage: 11b's version check would skip it and force the pass on every update.
@@ -11678,11 +11340,8 @@ def _repair_diffusers_release() -> int:
def _repair_diffusers_main() -> int:
- """11c on its own, for the backend's startup self-heal: 0 installed, 1 nothing to do, 2 failed.
-
- An update from a release that predates 11c runs that release's installer, which never installs
- the build; the backend that starts afterwards is the first new code such a host runs.
- """
+ """Startup self-heal running 11c alone: 0 installed, 1 nothing to do, 2 failed; old installers
+ skip it."""
import time
global USE_UV, _STEP, _TOTAL
@@ -11813,10 +11472,8 @@ def _diffusers_main_step() -> None:
_progress("diffusers main (opted out, skipped)")
return
if sys.version_info < DIFFUSERS_MAIN_MIN_PYTHON:
- # Diffusers main needs 3.11, and the release pin covers 3.10 and 3.9, so those are supported
- # paths this can never satisfy. Unmarked, pip would clone the repository and only then reject
- # its requires-python, and since the build can never become resident that clone repeats on
- # every install and update forever.
+ # Below 3.11 pip would clone diffusers main, then reject it, repeating the clone on every
+ # update.
_progress("diffusers main (skipped, needs python 3.11)")
return
req = REQ_ROOT / "diffusers-main.txt"
@@ -11957,11 +11614,8 @@ def _uv_version() -> "str | None":
def _installer_python_tag() -> str:
- """The interpreter's ABI tag, free-threaded builds included.
-
- Recorded beside `python`, which carries only the version: a GIL and a free-threaded
- 3.14 install the same version string and cannot load each other's extensions.
- """
+ """ABI tag with the t suffix for free-threaded builds, since the plain version cannot tell them
+ apart."""
return "{}{}{}".format(
sys.version_info.major,
sys.version_info.minor,
@@ -11970,12 +11624,7 @@ def _installer_python_tag() -> str:
def _patch_metadata_is_pending() -> bool:
- """Whether any METADATA the single-env patch owns still matches a pattern it rewrites.
-
- The patch is idempotent, so re-running it on a settled install rewrites nothing and costs
- a subprocess plus a metadata walk. Asking first is the same walk without the interpreter
- start; on a fresh venv, where the data-designer steps just ran, the caller does not ask.
- """
+ """Asks if the idempotent patch has rewrites left, without its subprocess; fresh venvs skip the ask."""
try:
sys.path.insert(0, str(SINGLE_ENV))
try:
@@ -12043,11 +11692,7 @@ def _is_plugin_build_artifact(relative: Path) -> bool:
def _local_plugin_digest(plugin_dir: Path) -> "str | None":
- """One sha256 over a local plugin tree, so an edited seed plugin reinstalls.
-
- Sorted (relpath, bytes): a directory listing has no order, and a digest that
- depended on one would differ between two byte-identical trees.
- """
+ """sha256 over the plugin tree sorted by (relpath, bytes), so byte-identical trees digest the same."""
import hashlib
if not plugin_dir.is_dir():
@@ -12098,13 +11743,9 @@ def _installer_replaced() -> bool:
def _rerun_replaced_installer() -> int:
- """Finish the pass with the installer the update just installed.
-
- Without this every step a release adds is skipped by the update that installs it: the old
- process upgrades the package in step 3 and completes its own step list. A subprocess rather
- than an exec, because on Windows os.exec* returns to the caller while the child runs. It starts
- after the pass lock is released, so the rerun does not read its parent as a contending peer.
- """
+ """Reruns the new installer as a subprocess (os.exec returns early on Windows) after the pass
+ lock is released, so the rerun is not read as a contending peer; otherwise steps a release
+ adds are skipped."""
_note("the update replaced this installer; finishing with the new version")
try:
# The child shares the descriptors, so flush first or our buffered output lands after its output.
@@ -12269,9 +11910,8 @@ def install_python_stack() -> int:
# guarantees an installer, not a current trust store.
_ensure_trust_floor()
- # A superseded dist-info makes version() and every RECORD consumer choose
- # an arbitrary package version. Repair it before any fast package operation,
- # including installer handoffs that set skip_base after their own upgrade.
+ # Superseded dist-info makes version() arbitrary; repair before any fast op, even skip_base
+ # handoffs.
if not _repair_duplicate_core_metadata(
(package_name, "unsloth-zoo"),
local_repo = local_repo,
diff --git a/studio/install_whisper_prebuilt.py b/studio/install_whisper_prebuilt.py
index bffea569318..8f8e3be316e 100644
--- a/studio/install_whisper_prebuilt.py
+++ b/studio/install_whisper_prebuilt.py
@@ -303,15 +303,9 @@ _PUBLISHED_GGML_TREE_CACHE: dict[tuple[str, str], str | None] = {}
def published_llama_ggml_tree(tag: Any, repo: Any = None) -> str | None:
- """ggml tree id recorded in the published llama release for ``tag``.
-
- An install made before ggml_tree was recorded has no tree locally, and
- nothing can backfill one without reinstalling llama. The release manifest
- carries it, so read that instead of falling back to the "-mix-" suffix,
- which does not track ggml. Failures return None: the caller then uses the
- old fallback rather than refusing an otherwise valid install, so this
- fetches once with no retries -- the retry policy exists for downloads we
- need, and an unreachable host would otherwise stall every uncached tag."""
+ """Reads the ggml tree from the published release manifest, not the -mix- suffix; fetches once
+ with no retries, since an unreachable host would stall every tag; failures return None so the
+ caller falls back rather than refusing a valid install."""
if not isinstance(tag, str) or not tag:
return None
if not (isinstance(repo, str) and repo):
@@ -335,12 +329,7 @@ def published_llama_ggml_tree(tag: Any, repo: Any = None) -> str | None:
def installed_llama_tree_repo() -> str | None:
- """Repo whose published ggml tree describes the installed llama binaries.
-
- None when there is nothing to read, or when the binaries came from a repo
- other than the one that published the release: recorded_ggml_tree() leaves
- the marker's tree unset in that case precisely because the fork tree does
- not describe an upstream-built libggml, so it must not be inferred either."""
+ """Repo that published the installed llama binaries, or None; a fork tree is never inferred."""
metadata = llama.load_prebuilt_metadata(llama.default_managed_llama_dir())
if metadata is None:
return None
@@ -412,14 +401,7 @@ def _is_linux_libomp_soname(name: str) -> bool:
def _ggml_stack_imports_libomp(llama_bin_dir: Path, backend: str) -> bool | None:
- """Whether the ggml libraries whisper will load actually import LLVM's libomp.
-
- True on the first import found; False only once every relevant library was inspected
- and none imported it; None when any could not be inspected.
-
- The selected backend module is inspected alongside the core: it is dlopen'd after
- startup, so a dependency living only there is invisible to a --help smoke test.
- """
+ """Whether ggml libs or the late-dlopen'd backend import libomp; None if any could not be inspected."""
patterns = ["libggml-base.so*", "libggml.so*"]
module_glob = SLIM_BACKEND_MODULE_GLOBS.get(backend, {}).get("linux")
if module_glob:
@@ -444,9 +426,7 @@ def _ggml_stack_imports_libomp(llama_bin_dir: Path, backend: str) -> bool | None
def slim_pairing_for_artifact(
artifact: dict[str, Any], host: HostInfo, backend: str
) -> tuple[Path, str] | None:
- """(llama bin dir, llama release tag) when the installed llama runtime can
- back this slim artifact, else None. Each failed gate logs why; the caller
- then retries via CPU or reports the prebuilt unavailable."""
+ """Returns (llama bin dir, release tag) if the installed runtime can back this artifact; else None."""
asset = artifact.get("asset")
runtime = installed_llama_runtime()
if runtime is None:
@@ -505,12 +485,9 @@ def slim_pairing_for_artifact(
def select_slim_artifact(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> dict[str, Any] | None:
- """The paired slim artifact for any backend (cpu and metal included), or None.
- Slim assets carry backend "slim" so the CPU escape hatch's fat os/arch/backend
- matching never sees them. When the release ships slim candidates but none
- pair, log the actionable reason: on a slim-only release nothing else selects,
- setup reports the prebuilt unavailable, and local dictation stays on
- Transformers STT."""
+ """Paired slim artifact for any backend, or None; slim assets skip fat matching; when slim
+ candidates exist but none pair, log the actionable reason: setup then reports the prebuilt
+ unavailable and dictation stays on Transformers STT."""
if backend not in SLIM_ELIGIBLE_BACKENDS:
return None
os_token, arch_token = host_platform_tokens(host)
@@ -535,10 +512,7 @@ def select_slim_artifact(
def select_artifact(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> dict[str, Any] | None:
- """Slim-only: every backend resolves to the paired slim artifact. The one
- legacy shape still honored is the published fat CPU bundle of a pinned pre-slim
- release, reached by a GPU-backend miss through the core's CPU fallback retry.
- No other fat artifact is ever selected."""
+ """Slim-only, except a pinned pre-slim release's fat CPU bundle, reached via the CPU fallback retry."""
slim = select_slim_artifact(manifest, host, backend)
if slim is not None:
return slim
@@ -591,12 +565,9 @@ def _installed_llama_is_ahead(manifest: dict[str, Any], host: HostInfo) -> bool:
def _slim_release_incompatibility(manifest: dict[str, Any], host: HostInfo) -> str | None:
- """Explain a valid platform slim release that this runtime cannot pair.
-
- This intentionally excludes missing files, malformed manifests, checksum
- failures, and unsupported platforms. Those are operational errors and must
- never be converted into the update path's kept-existing-runtime success.
- """
+ """Explains only a valid slim release this runtime cannot pair; missing files, bad manifests,
+ checksum failures and unsupported platforms are excluded and must never count as
+ kept-existing success."""
os_token, arch_token = host_platform_tokens(host)
candidates = [
artifact
@@ -763,12 +734,8 @@ def locate_server_in_tree(root: Path, host: HostInfo) -> Path:
def _assemble_install_tree(bundle_root: Path, staged_root: Path, host: HostInfo) -> Path:
- """Lay out staged_root as a full install: build/bin/<server + libs>.
-
- Everything beside the server in the archive (shared libs, backend kernel
- subdirs, license/build-info) is co-located into the canonical bin dir so the
- server's RUNPATH=$ORIGIN resolves its libs.
- """
+ """Lay out staged_root as a full install in build/bin: co-locate everything beside the server
+ (shared libs, backend kernel subdirs, license) so RUNPATH=$ORIGIN resolves its libs."""
bin_dir = runtime_bin_dir(staged_root, host)
bin_dir.mkdir(parents = True, exist_ok = True)
for entry in sorted(bundle_root.iterdir()):
@@ -917,15 +884,9 @@ def link_ggml_runtime(
*,
backend: str | None = None,
) -> list[str]:
- """Hardlink every ggml library from the llama runtime into the whisper bin
- dir; returns the wired filenames (sorted) for the marker / sidecar launch guard.
-
- Hardlinks (not symlinks) on purpose: when the llama updater atomically swaps
- its install dir, the old inodes stay alive under these links, so a
- not-yet-updated whisper keeps running the exact ggml build it was installed
- against. Falls back to a copy where linking is unsupported or crosses devices.
- Re-run on every install/update so the links track the current pairing.
- """
+ """Hardlinks (not symlinks) to the llama ggml libraries keep the paired build alive across an
+ atomic swap of its install dir; copy only where linking is unsupported or crosses devices;
+ re-run on each install or update to track the pairing; returns sorted names."""
sources = _runtime_library_sources(llama_bin_dir, backend)
if not any(source.name.startswith(("libggml", "ggml")) for source in sources):
raise PrebuiltFallback(
@@ -966,10 +927,8 @@ def link_runtime_directories(
def prepare_runtime_payload(staged_root: Path, host: HostInfo, selection: Any) -> Any:
- """Slim installs wire the paired llama ggml runtime into the staged bin dir
- before validation so the activated tree is self-contained; the returned
- selection carries the wired filenames for the marker. Fat installs need
- nothing (the archive carries its ggml) and return None."""
+ """Slim installs link the paired llama ggml runtime into the staged bin dir before validation
+ and the returned selection records the wired filenames; fat installs return None."""
if getattr(selection, "install_kind", None) != "slim" or not selection.linked_from:
return None
source = Path(selection.linked_from)
@@ -1083,11 +1042,9 @@ def _runtime_file_records(
def runtime_file_records(install_dir: Path, selection: Any) -> "dict[str, dict[str, Any]]":
- """prebuilt_core.write_prebuilt_metadata's hook: the record for the tree just staged.
-
- Slim bundles pass their wired ggml filenames through, so the marker describes the
- hardlinks it is about to claim as well as the server it shipped.
- """
+ """Hook for prebuilt_core.write_prebuilt_metadata that records the staged tree; slim bundles
+ pass their wired ggml filenames so the marker describes the hardlinks it claims as well as
+ the server."""
is_slim = getattr(selection, "install_kind", None) == "slim"
linked = selection.linked_libraries if is_slim else None
runtime_dirs = getattr(selection, "linked_runtime_directories", None) if is_slim else None
@@ -1204,11 +1161,9 @@ def load_prebuilt_metadata(install_dir: Path) -> dict[str, Any] | None:
def existing_install_matches(
install_dir: Path, host: HostInfo, selection: InstallSelection
) -> bool:
- """Core fingerprint match, hardened for repairability: a marker-matching
- install is only "current" when the server is executable (the sidecar refuses
- non-executable binaries, so setup must repair not skip) and, for slim
- installs, every wired ggml library is still present (else a deleted/moved
- llama dir leaves dictation broken while update reports up to date)."""
+ """A marker match counts as current only if the server is executable (the sidecar refuses
+ non-executable binaries) and slim wired ggml libraries all exist, since a deleted or moved
+ llama dir breaks dictation while update reports up to date."""
if not core.existing_install_matches(_OPS, install_dir, host, selection):
return False
return installed_tree_is_intact(install_dir, host)
@@ -1244,25 +1199,9 @@ def settle_kept_install(install_dir: Path) -> None:
def _backfill_runtime_file_records(install_dir: Path) -> None:
- """Record the payload's sizes and digests on a marker written before that key existed.
-
- An install made by an older Unsloth Studio carries no runtime_files, and
- existing_install_current_without_plan demands one: without this backfill every such
- install would take the full path on EVERY update -- fetching the release, its
- manifest and its checksum index each time -- instead of once. Nothing here re-downloads
- anything: the comparison in installed_tree_is_intact accepts an absent record precisely
- so that an upgrade never costs 200-400 MB for a tree that is fine.
-
- Added, never corrected: a marker that already carries a record was written by a run
- that hashed the bytes it installed, and overwriting it would re-bless bytes this run
- did not choose. What this writes is what is on disk NOW, which is the only thing an
- offline run can honestly say -- a legacy install already damaged before this ran is
- recorded as damaged. That is the inherent limit of a record introduced after the fact;
- from the moment it is written the bytes are pinned.
-
- Never raises -- the install is already valid, and a read-only marker must not fail
- setup over a metadata refresh.
- """
+ """Backfills runtime_files on markers from older installs, which would otherwise refetch the
+ release, manifest and checksums on every update; records what is on disk now, never
+ overwrites, never downloads, never raises."""
marker = load_prebuilt_metadata(install_dir)
if not marker or marker.get("runtime_files"):
return
diff --git a/studio/prebuilt_core.py b/studio/prebuilt_core.py
index 20dbf638248..57a83d0c74c 100644
--- a/studio/prebuilt_core.py
+++ b/studio/prebuilt_core.py
@@ -415,11 +415,8 @@ def is_retryable_url_error(exc: Exception) -> bool:
def _http_error_retry_delay(exc: Exception) -> float | None:
- """Recommended wait from rate-limit headers on a 403/429.
-
- None when no header is present or the wait exceeds
- _RATE_LIMIT_WAIT_CAP_SECONDS (the source-build fallback is faster).
- """
+ """Recommended wait from rate-limit headers on a 403 or 429; None when no header is present or
+ the wait exceeds _RATE_LIMIT_WAIT_CAP_SECONDS, since the source build fallback is faster."""
if not isinstance(exc, urllib.error.HTTPError):
return None
headers = getattr(exc, "headers", None)
@@ -491,14 +488,8 @@ def atomic_replace_from_tempfile(
*,
attempts: int = 8,
) -> None:
- """os.replace, retried against transient Windows sharing violations.
-
- Rename-over needs DELETE access on the destination, so a scanner or the indexer holding the
- marker open fails the swap outright -- where the in-place write this replaced would only
- have contended for write access. Handles clear in a second or two, so a bounded backoff
- turns the failure into a pause; anything else raises at once rather than stalling on a real
- problem. A no-op off Windows, where the rename does not care about open handles.
- """
+ """Retries os.replace on transient Windows sharing violations: rename-over needs DELETE access
+ that a scanner or indexer holding the marker open denies; other errors raise at once."""
destination.parent.mkdir(parents = True, exist_ok = True)
delay = 0.25
for attempt in range(attempts):
@@ -753,15 +744,9 @@ def copy_response_body(
progress: "DownloadProgress | None" = None,
chunk_size: int = 1024 * 1024,
) -> int:
- """Stream ``response`` into ``write`` and return the byte count. Raises StalledDownload when a
- window passes with too few bytes, and TruncatedDownload when the body ends short of
- ``total_bytes``; both are retryable, so the caller's loop reconnects.
-
- A real HTTPResponse is read with read1, which returns what one receive brings: read(n) waits
- for all n bytes, so a trickle would block it for hours and the window check would never run.
- Anything else (file:// bodies, test doubles) keeps plain read. Each read1 stops at the next
- ``chunk_size`` boundary and progress is reported there, so the progress lines land where the
- whole-chunk reads put them while the stall window is still checked after every receive."""
+ """Streams response into write and returns the byte count, raising retryable StalledDownload or
+ TruncatedDownload; a real HTTPResponse uses read1 because read(n) waits for all n bytes and
+ would never reach the stall window check; progress lands at chunk_size boundaries."""
per_receive = isinstance(response, http.client.HTTPResponse)
read = response.read1 if per_receive else response.read
downloaded = 0
@@ -988,13 +973,9 @@ def release_asset_map(release: dict[str, Any]) -> dict[str, str]:
def release_asset_digests(release: dict[str, Any]) -> dict[str, str]:
- """asset name -> bare sha256 hex, for the assets whose digest GitHub reports.
-
- Separate from release_asset_map because the name -> url mapping is what nearly every
- caller wants and widening its return type would touch all of them. GitHub returns
- `digest` as an algorithm-prefixed string ("sha256:<hex>"); anything else is skipped
- rather than guessed at, so a future algorithm cannot be read as a sha256.
- """
+ """Maps asset name to bare sha256 hex from GitHub's digest field, accepting only sha256:
+ prefixed digests and skipping others; kept separate from release_asset_map to leave its
+ return type alone."""
assets = release.get("assets")
if not isinstance(assets, list):
return {}
@@ -1122,11 +1103,9 @@ def web_release_tags(
*,
limit: int = 30,
) -> list[str]:
- """Recent release tags, newest first, from github.com/<repo>/releases.atom.
-
- The only tokenless surface that ORDERS releases, so it is what restores the
- older-release walk-back, and the only one that can name the newest nightly.
- """
+ """Recent release tags, newest first, from the releases.atom feed; the only tokenless source
+ that orders releases, so it restores the older-release walk-back and can name the newest
+ nightly."""
url = f"https://github.com/{urllib.parse.quote(repo, safe = '/')}/releases.atom"
body = _fetch_web_metadata(ops, url)
tags: list[str] = []
@@ -1143,12 +1122,9 @@ _PRERELEASE_LABEL_RE = re.compile(r"Label--warning[^>]*>\s*Pre-release\s*<", re.
def web_release_prerelease(ops: ModuleOps, repo: str, tag: str) -> bool:
- """Whether <repo>@<tag> is marked pre-release, read from its release page.
-
- The feed and the asset fragment both omit it, and asserting a value we did not read
- would let the web path select a release the REST path filters out. Draft is not
- asked: a draft is not served anonymously, so reaching this page proves publication.
- """
+ """Pre-release flag is read from the release page rather than assumed, so the web path never
+ picks a release the REST path filters out; drafts are not checked since reaching the page
+ proves publication."""
url = (
f"https://github.com/{urllib.parse.quote(repo, safe = '/')}/releases/tag/"
f"{urllib.parse.quote(tag, safe = '')}"
@@ -1159,12 +1135,8 @@ def web_release_prerelease(ops: ModuleOps, repo: str, tag: str) -> bool:
def _web_release_prerelease_or_default(
ops: ModuleOps, repo: str, tag: str, default: bool | None
) -> bool:
- """The release's prerelease flag, or *default* when the page cannot be read.
-
- The assets and their digests have already loaded by this point, so discarding them
- because one more request failed would drop a usable release for a fact the caller
- may already know from the tag.
- """
+ """Returns the prerelease flag, or default when the page cannot be read, since the assets
+ already loaded and one failed request must not drop a usable release."""
try:
return web_release_prerelease(ops, repo, tag)
except Exception as exc: # noqa: BLE001 - a known answer beats losing the release
@@ -1250,18 +1222,9 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
def _try_repair_missing_slash(
member_name: str, link_name: str, archive_names: set[str]
) -> str | None:
- """Repair a mangled symlink from some upstream llama.cpp Mac releases
- (e.g. b9165, b9169) whose linkname drops the separator AND the file
- basename's leading char between the top-level dir and the rest:
-
- llama-b9165/libggml-rpc.0.dylib -> llama-b9165ibggml-rpc.0.11.1.dylib
-
- Detect the pattern (linkname starts with the top-level dir but no
- following slash), then find the archive entry under that dir whose
- basename ends with the mangled suffix; only accept a unique match.
- Returns the corrected linkname relative to the member's parent dir --
- callers join it with `target.parent`, so a full `top/file` path would
- double the prefix into `top/top/file`."""
+ """Repairs mangled Mac llama.cpp symlinks (e.g. b9165, b9169) whose linkname drops the
+ separator and the basename's leading character; accepts only a unique match, returned
+ relative to the member's parent dir because callers join it onto target.parent."""
if "/" not in member_name or "/" in link_name:
return None
top, _, _ = member_name.partition("/")
@@ -1488,10 +1451,9 @@ def install_lock_path(install_dir: Path) -> Path:
# ── macOS version parsing ──
def parse_macos_version(value: str | None) -> tuple[int, int] | None:
- """Parse a macOS product version into (major, minor).
-
- Handles "14.7.1", "15.5", "26.0", bare "26". None when empty/unparseable
- (callers then defer to runtime validation rather than reject every prebuilt)."""
+ """Parses a macOS product version into (major, minor), e.g. 14.7.1, 15.5 or bare 26; None when
+ empty or unparseable, so callers defer to runtime validation instead of rejecting every
+ prebuilt."""
if not value:
return None
match = re.match(r"\s*(\d+)(?:\.(\d+))?", str(value))
@@ -1838,9 +1800,8 @@ def sm_range(artifact: Any) -> int:
def blackwell_capable_linux_runtime_lines(host_sms: list[str], artifacts: list[Any]) -> list[str]:
- """CUDA runtime lines (highest major first) shipping a bundle covering every
- visible host SM. Lets a Blackwell host prefer a native sm_120 line over torch's
- reported line, mirroring the Windows Blackwell preference."""
+ """CUDA runtime lines, highest major first, whose bundles cover every visible host SM; lets a
+ Blackwell host prefer a native sm_120 line over torch's reported line, mirroring Windows."""
lines: set[str] = set()
for artifact in artifacts:
line = artifact.runtime_line
@@ -2050,11 +2011,9 @@ def valid_sha256(value: Any) -> str | None:
def parse_release_checksums(
ops: ModuleOps, repo: str, release_tag: str, payload: Any
) -> dict[str, str]:
- """Asset name -> sha256 from a release's checksum-index asset.
-
- That index is the authority for each asset's sha256. It is validated for
- schema/component and that its ``release_tag`` matches the resolved release,
- so a redirected or mismatched index is rejected; malformed fails closed."""
+ """Asset name to sha256 from the release checksum-index asset, the authority for each asset's
+ digest; the index must match schema, component and release_tag, and malformed input fails
+ closed."""
label = f"{ops.SHA256_ASSET_NAME} in {repo}@{release_tag}"
if not isinstance(payload, dict):
raise PrebuiltFallback(f"{label} was not a JSON object")
@@ -2115,9 +2074,8 @@ def expected_sha256_for(
*,
manifest_sha256: str | None = None,
) -> str:
- """The sha256 the archive must match, from the release checksum-index entry.
- An asset absent from the index fails closed. Any sha256 the manifest embeds
- for the asset must agree with the index (a mismatch means a tampered manifest)."""
+ """The sha256 the archive must match, from the release checksum index; an asset missing from the
+ index fails closed, and a manifest sha256 that disagrees means a tampered manifest."""
digest = checksums.get(asset_name)
if digest is None:
raise ReleaseIntegrityError(
@@ -2421,9 +2379,8 @@ def macos_version_label(host: Any) -> str | None:
def walk_back_for(host: Any, skipped_release_tag: str | None) -> WalkBack | None:
- """The walk-back to record when the planner settled below *skipped_release_tag*
- on this host; None when there is nothing to record (no skipped release, not
- macOS, or a host version the marker-only re-check could not compare)."""
+ """Walk-back to record when the planner settled below skipped_release_tag on this host; None
+ without a skipped release, off macOS, or when the host version cannot be compared."""
if not skipped_release_tag:
return None
label = macos_version_label(host)
@@ -2445,9 +2402,8 @@ def marker_walk_back(marker: dict[str, Any]) -> WalkBack | None:
def walk_back_stands(marker: dict[str, Any], host: Any, expected_release: str | None) -> bool:
- """Whether the marker's walk-back still explains why *expected_release*, the newest
- published release, is not the installed one: same skipped release, same host
- macOS version."""
+ """Whether the marker's walk-back still explains why expected_release, the newest published
+ release, is not installed: same skipped release and same host macOS version."""
recorded = marker_walk_back(marker)
if recorded is None or not expected_release:
return False
@@ -2689,12 +2645,8 @@ def locate_server_in_tree(ops: ModuleOps, root: Path, host: Any) -> Path:
def assemble_install_tree(ops: ModuleOps, bundle_root: Path, staged_root: Path, host: Any) -> Path:
- """Lay out staged_root as a full install: <runtime bin dir>/<server + libs>.
-
- Everything beside the server in the archive (shared libs, backend kernel
- subdirs, license/build-info) is co-located into the canonical bin dir so the
- server's RUNPATH=$ORIGIN resolves its libs.
- """
+ """Lay out staged_root as a full install in the runtime bin dir: co-locate everything beside the
+ server (shared libs, backend kernel subdirs, license) so RUNPATH=$ORIGIN resolves its libs."""
bin_dir = ops.runtime_bin_dir(staged_root, host)
bin_dir.mkdir(parents = True, exist_ok = True)
for entry in sorted(bundle_root.iterdir()):
@@ -2940,20 +2892,9 @@ def install_selected_prebuilt(
def _settle_kept_install(
ops: ModuleOps, install_dir: Path, host: Any, selection: InstallSelection, *, locked: bool
) -> bool:
- """Let a component catch up the marker of an install it is keeping, under the lock.
-
- Returns False only when the pre-lock keep's re-check under the lock found another
- install on disk; everything else, a settle that fails included, keeps the install.
-
- Optional: a component that has nothing to write defines neither hook. One that
- does (whisper's slim pairing backfill) rewrites the marker, and a rewrite outside
- the install lock races a concurrent installer swapping in a new release: the old
- marker is read, the tree is replaced, the old fields are written over the new
- marker. So the pre-lock keep takes the lock for the write, re-checks that the
- install it read is still the one on disk, and only then settles it. Never raises:
- the install is already valid, and a lock that cannot be had or a write that fails
- costs the next run the same settle, not the install.
- """
+ """Catches up a kept install's marker under the install lock, since an unlocked rewrite can race
+ a concurrent swap; optional per component; returns False only when the locked re-check finds
+ another install; never raises."""
settle = getattr(ops, "settle_kept_install", None)
needs_settling = getattr(ops, "kept_install_needs_settling", None)
try:
diff --git a/studio/scripts/unsloth_freeze_report.py b/studio/scripts/unsloth_freeze_report.py
index f0fb1028bbc..a154734ea7a 100644
--- a/studio/scripts/unsloth_freeze_report.py
+++ b/studio/scripts/unsloth_freeze_report.py
@@ -292,17 +292,9 @@ def studio_backend_pids() -> list[int]:
def stop_leftover_backend():
- """Stop a backend left behind by the previous candidate.
-
- Closing the app does not necessarily stop the backend it started, and an orphaned one
- is the worst possible state to measure in: it still answers, so the next launch attaches
- to it (`OwnedReady`) instead of starting its own, but the process that copied its output
- into the log died with the app. The result is a backend that serves and is never written
- down, and every candidate after the first reads zero.
-
- Only processes attributable to Unsloth are touched. Matching on the port alone would
- happily kill an unrelated program that happens to be listening there.
- """
+ """Stops the backend a previous candidate left behind: an orphan still answers (attaching as
+ OwnedReady) but its log copier died with the app; only Unsloth processes are killed, never by
+ port alone."""
for pid in studio_backend_pids():
try:
os.kill(pid, signal.SIGTERM)
@@ -312,13 +304,9 @@ def stop_leftover_backend():
def wait_for_leftover_backend_to_stop(timeout = 30):
- """Wait for OUR backend to go, but say so, and give up early.
-
- This used to wait 120s per candidate in silence, and on any listener at all. A port held
- by something that is not Unsloth never clears and never needed to: the backend walks on
- to the next free port in the range (_resolve_port in studio/backend/run.py). Waiting on
- it turned an unrelated service into an eight minute hang with no output and no reason.
- """
+ """Waits up to a bounded timeout, with progress output, for the leftover Unsloth backend to
+ exit; a port held by another program is never waited on because _resolve_port in
+ studio/backend/run.py moves to the next free port."""
if not studio_backend_pids():
return True
print(f" waiting up to {timeout}s for the previous backend to exit", flush = True)
@@ -342,11 +330,8 @@ def backend_offsets() -> dict:
def backend_tail(before: dict) -> str:
- """Everything appended to any supervised backend log since `before`.
-
- Re-globbed rather than reusing the earlier listing, because the run being measured
- usually creates its own log file, which was not there when the offsets were taken.
- """
+ """Returns everything appended to any supervised backend log since the before offsets; logs are
+ re-globbed because the measured run usually creates its own log file."""
out = []
try:
logs = list(BACKEND_LOGS.glob("backend-*.log"))
@@ -413,12 +398,8 @@ def _last_rise(samples: list, column: int) -> int | None:
def _first_heard(samples: list, column: int) -> int | None:
- """Elapsed time of the earliest sample that proves that counter was moving.
-
- A rise between two samples proves it, and so does a first sample that is already above
- zero: that count was accumulated during the interval before it. None means the counter
- never moved while the run was being watched.
- """
+ """Elapsed time of the earliest sample proving the counter moved: a rise between samples, or a
+ first sample already above zero; None if it never moved while watched."""
if not samples:
return None
if samples[0][column] > 0: