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.

Make the notebooks smoke job reach the check it exists for (#10125)

Daniel Han31af9ab6e1c6
diff --git a/.github/workflows/notebooks-ci.yml b/.github/workflows/notebooks-ci.yml
index 3d30aff807a..407c80b88fe 100644
--- a/.github/workflows/notebooks-ci.yml
+++ b/.github/workflows/notebooks-ci.yml
@@ -115,7 +115,19 @@ jobs:
# update_all_notebooks.py.
pip install \
'nbformat>=5.10' 'nbconvert>=7.16' 'pyspellchecker>=0.8' \
- 'huggingface_hub>=0.34' 'tqdm>=4.66'
+ 'huggingface_hub>=0.34' 'tqdm>=4.66' \
+ pytest 'pyyaml>=6'
+
+ - name: Smoke-install contract
+ # Run here, not only in the auto-discovering test jobs, because those key
+ # on `tests/**` and `scripts/**` and this file is not in their paths. A PR
+ # editing only this workflow would otherwise skip the guard that exists to
+ # protect this workflow, which is how the smoke job's interpreter pin and
+ # its snapshot drifted apart unnoticed in the first place.
+ #
+ # This job checks the repo out under `unsloth/`, so the path is prefixed;
+ # an unprefixed one collects nothing and passes vacuously.
+ run: python -m pytest unsloth/tests/notebooks/test_smoke_install_contract.py -q
- name: Diff Colab oracle vs committed snapshots (advisory)
# Pulls pip-freeze.gpu.txt + apt-list-gpu.txt + os-info-gpu.txt
@@ -384,7 +396,15 @@ jobs:
name: smoke install (Colab-shaped venv, opt-in)
if: ${{ github.event.inputs.include_smoke == 'true' || github.event_name == 'schedule' }}
runs-on: ubuntu-latest
- timeout-minutes: 25
+ # Above the sum of every per-step cap below (8 restore + 3 seed + 28 install
+ # + 10 save + 10 install-cell + 5 verify = 64, plus ~4 for the checkouts and
+ # interpreter setup that GitHub charges to this clock without showing in the
+ # step timings). The steps are what should stop a stall: a step that exceeds
+ # `timeout-minutes` is killed and the job reports `failure` with the step
+ # named, whereas this cap reports `cancelled` with nothing, and `cancelled`
+ # outranks `failure` in the run rollup. If this number is ever the one that
+ # fires, the step budgets are wrong.
+ timeout-minutes: 70
strategy:
fail-fast: false
matrix:
@@ -419,8 +439,14 @@ jobs:
ref: ${{ env.NOTEBOOKS_REF }}
path: notebooks
persist-credentials: false
+ # Whatever interpreter the snapshot was taken on. Colab rotated 3.12 to
+ # 3.13 and #9376 refreshed the freeze accordingly, but this pin stayed on
+ # 3.12, so the job has been installing a 3.13 environment onto a 3.12
+ # runner ever since. `python_version` in the mapping is the snapshot's own
+ # record of that, and the seed step below fails loudly if the two drift
+ # apart again rather than letting one pin resolve short.
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
- with: { python-version: '3.12' }
+ with: { python-version: '3.13' }
- name: Restore the pip cache
id: pip-cache
@@ -428,6 +454,9 @@ jobs:
# under `unsloth/`, so the unprefixed path is a directory that does not
# exist and the step fails with "Can't find 'action.yml'".
uses: ./unsloth/.github/actions/pip-cache-restore
+ # ~2 minutes observed for the 10.3 GB entry. Capped because a slow cache
+ # transfer is otherwise unbounded and lands on the job clock.
+ timeout-minutes: 8
with:
name: notebooks-colab
# The freeze is the pin set, so it is what the downloads depend on. The
@@ -443,16 +472,38 @@ jobs:
unsloth/.github/workflows/notebooks-ci.yml
- name: Seed Colab-shaped venv from pip-freeze (CPU-mapped)
+ timeout-minutes: 3
run: |
- # Strip cu128 local versions, route torch/torchvision to the CPU
- # wheel index, drop CUDA-specific deps the runner can't use.
- python -u - <<'PY' > /tmp/seed_pins.txt
- import json, re
+ # set -e, or the interpreter check below is decorative: the heredoc
+ # exits 1, the `cat`/`head`/`wc` after it succeed, and the step takes
+ # the last command's status and reports green with an ::error:: in the
+ # log. Same shape as the bug this job already shipped once.
+ set -euo pipefail
+ # Strip cu128 local versions, split the torch packages out for the CPU
+ # wheel index, drop what the runner can't use.
+ python -u - <<'PY'
+ import json, re, sys
mapping = json.load(open("unsloth/scripts/data/colab_to_cpu_pin.json"))
rewrite = mapping["rewrite"]
skip = set(mapping["skip"])
spoof = set(mapping["module_spoof"])
- out = []
+
+ # The freeze is a snapshot of a Colab image, so it is only installable on
+ # the interpreter that image was running. Drift here is not cosmetic: it
+ # is what made every bulk resolve fail and every leg time out.
+ want = mapping["python_version"]
+ have = "%d.%d" % sys.version_info[:2]
+ if want != have:
+ print(
+ f"::error::the Colab snapshot was captured on Python {want} but this "
+ f"runner is {have}. Pins carrying a Requires-Python floor cannot "
+ f"resolve. Move python-version in this workflow to {want}, or refresh "
+ f"the snapshot and its python_version together.",
+ file = sys.stderr,
+ )
+ raise SystemExit(1)
+
+ torch_pins, rest = [], []
for line in open("unsloth/scripts/data/colab_pip_freeze.gpu.txt"):
line = line.strip()
if not line or line.startswith("#"):
@@ -461,50 +512,142 @@ jobs:
if not m:
continue
name, ver = m.group(1).lower(), m.group(2)
- if name in skip:
- continue
- if name in spoof:
+ if name in skip or name in spoof:
continue
- if name in rewrite:
- ver = re.sub(r"[+\-].+$", "", ver)
- out.append(f"{name}=={ver}")
- else:
- ver = re.sub(r"[+\-].+$", "", ver)
- out.append(f"{name}=={ver}")
- print("\n".join(out))
+ # Drop the local version (`+cu128`) whatever the package is; the CPU
+ # index publishes the same version without it.
+ ver = re.sub(r"[+\-].+$", "", ver)
+ (torch_pins if name in rewrite else rest).append(f"{name}=={ver}")
+
+ open("/tmp/seed_torch.txt", "w").write("\n".join(torch_pins) + "\n")
+ open("/tmp/seed_pins.txt", "w").write("\n".join(rest) + "\n")
+
+ # Packages the image pins at a version PyPI ships only as an sdist.
+ # --no-binary overrides --only-binary=:all: per package, so these are
+ # allowed to build while everything else must arrive as a wheel. Only
+ # the ones actually present are named: pip errors on a --no-binary
+ # entry it never sees in the resolve.
+ wanted = set(mapping.get("no_binary", []))
+ present = sorted(wanted & {p.split("==")[0] for p in rest})
+ open("/tmp/seed_no_binary.txt", "w").write(",".join(present))
+ print(f"{len(torch_pins)} torch pins, {len(rest)} others, Python {have}")
+ print(f"allowed to build from sdist: {present}")
PY
+ cat /tmp/seed_torch.txt
head -5 /tmp/seed_pins.txt
wc -l /tmp/seed_pins.txt
- name: Install Colab-shaped venv
+ # A cap this step reports itself. `timeout-minutes` on the job scores an
+ # overrun as `cancelled`, and `cancelled` outranks `failure` in GitHub's
+ # run rollup, so a matrix where every leg timed out reads as though
+ # somebody pressed stop, and one leg that genuinely failed beside them is
+ # hidden outright (2026-08-21 did exactly that). Nothing watches this
+ # workflow, so a silent stall was indistinguishable from a pass.
+ #
+ # The inner `timeout` calls bound each phase and print why; this is the
+ # backstop for the step as a whole. Every phase is counted at its real
+ # worst case, which is its duration PLUS its --kill-after grace, since
+ # that grace is additional time after the first signal:
+ #
+ # pip upgrade 2m + 15s = 2m15
+ # torch 6m + 30s = 6m30
+ # bulk resolve 12m + 30s = 12m30
+ # per-pin 8m + 10s = 8m10 (see the deadline below)
+ # ------
+ # 29m25
+ #
+ # The earlier sum said 6 + 12 + 8 = 26 and ignored all four graces, which
+ # put the true worst case at 28m40 against a 28m cap. The step backstop
+ # would then have killed the run BEFORE the per-pin loop could print the
+ # budget error that is the whole point of bounding it.
+ timeout-minutes: 30
run: |
- python -m pip install --upgrade pip
- # One resolve for the whole pin set instead of one per line. The per-line loop
- # below re-resolved against both indexes for every one of ~683 pins, which is
- # why this step spent its entire 25 minute cap here and never once reached
- # "Verify imports under spoof".
+ set -uo pipefail
+ timeout --signal=INT --kill-after=15s 2m python -m pip install --upgrade pip
+
+ # Only the three torch packages want the PyTorch index. Pointing
+ # --index-url at it globally made all 682 other pins resolve against it
+ # first and fall through to PyPI, once each.
+ timeout --signal=INT --kill-after=30s 6m \
+ pip install --only-binary=:all: -r /tmp/seed_torch.txt \
+ --index-url https://download.pytorch.org/whl/cpu \
+ --extra-index-url https://pypi.org/simple 2>&1 | tee /tmp/install_torch.log
+ rc=${PIPESTATUS[0]}
+ if [ "$rc" -ne 0 ]; then
+ echo "::error::CPU torch install failed (exit $rc). Last lines:"
+ tail -40 /tmp/install_torch.log
+ exit "$rc"
+ fi
+
+ # One resolve for the whole pin set. The per-line fallback below is
+ # best effort and quadratic-ish -- later pins uninstall and downgrade
+ # what earlier ones installed -- so reaching it at all is a defect, not
+ # a mode. It stays because a Colab rotation can always introduce a pin
+ # PyPI will not serve, and a partial venv still exercises the install
+ # cell; the warning is what makes that visible.
#
- # Best-effort is preserved, just moved: a single unresolvable pin fails the bulk
- # install, and the fallback then walks the list line by line exactly as before,
- # tolerating the ones that cannot resolve on CPU. The smoke contract is "the
- # install cell + the unsloth import works", not "the entire Colab venv
- # reproduces."
- if ! pip install -r /tmp/seed_pins.txt \
- --index-url https://download.pytorch.org/whl/cpu \
- --extra-index-url https://pypi.org/simple; then
- echo "::warning::bulk resolve failed, falling back to per-pin best effort"
- while IFS= read -r spec; do
- pip install "$spec" --index-url https://download.pytorch.org/whl/cpu \
- --extra-index-url https://pypi.org/simple || \
- echo "::warning::pin failed: $spec"
- done < /tmp/seed_pins.txt
+ # --only-binary=:all: so a pin needing a system library the runner does
+ # not have fails immediately instead of spending 20-90s on a build that
+ # cannot succeed. The exceptions are named rather than assumed: 16 pins
+ # in this snapshot are pure Python and published only as an sdist, and
+ # --only-binary alone made the bulk resolve fail on the first of them
+ # every single run, which is the failure this job kept hitting. They
+ # come from the mapping's no_binary list, which overrides --only-binary
+ # per package.
+ NO_BINARY="$(cat /tmp/seed_no_binary.txt)"
+ BUILDABLE=()
+ [ -n "$NO_BINARY" ] && BUILDABLE=(--no-binary="$NO_BINARY")
+ timeout --signal=INT --kill-after=30s 12m \
+ pip install --only-binary=:all: "${BUILDABLE[@]}" -r /tmp/seed_pins.txt \
+ --index-url https://pypi.org/simple 2>&1 | tee /tmp/install_seed.log
+ rc=${PIPESTATUS[0]}
+ if [ "$rc" -eq 0 ]; then
+ exit 0
+ fi
+ if [ "$rc" -eq 124 ]; then
+ echo "::error::the Colab seed install exceeded 12 minutes. Last lines:"
+ tail -40 /tmp/install_seed.log
+ exit 1
fi
+ echo "::warning::bulk resolve failed (exit $rc), falling back to per-pin best effort"
+ grep -E "^ERROR: (Could not find|No matching|Ignored)" /tmp/install_seed.log | head -20 || true
+ total=$(grep -c . /tmp/seed_pins.txt || echo 0)
+ done_n=0; failed_n=0
+ # Bounded, because an unbounded fallback is how this job spent 112 days
+ # being scored `cancelled`. Running out of budget is a failure with a
+ # number attached, not a silent stop, and the per-pin cap keeps one
+ # pathological resolve from eating the whole allowance.
+ deadline=$(( SECONDS + 480 ))
+ while IFS= read -r spec; do
+ [ -n "$spec" ] || continue
+ if [ "$SECONDS" -ge "$deadline" ]; then
+ echo "::error::per-pin fallback ran out of budget at $done_n/$total pins, $failed_n failed"
+ exit 1
+ fi
+ done_n=$(( done_n + 1 ))
+ # Capped at what is LEFT, not a flat 90s. The deadline is only tested
+ # before launch, so a flat cap let the last pin start at the deadline
+ # and run 90s past it, plus its kill grace -- the loop then overran its
+ # own budget by 100s and could take the step cap with it.
+ cap=$(( deadline - SECONDS ))
+ [ "$cap" -gt 90 ] && cap=90
+ timeout --signal=INT --kill-after=10s "${cap}s" \
+ pip install --only-binary=:all: "${BUILDABLE[@]}" "$spec" \
+ --index-url https://pypi.org/simple \
+ > /dev/null 2>&1 || { failed_n=$(( failed_n + 1 )); echo "::warning::pin failed: $spec"; }
+ done < /tmp/seed_pins.txt
+ echo "::warning::per-pin fallback finished: $done_n/$total attempted, $failed_n failed"
+
- name: Save the pip cache
if: always()
# always(), because the fallback path is exactly when the cache is worth
# most: it installs 709 pins one at a time, and a partial download set is
# still a head start on the next run.
+ #
+ # Uploads multiple GB on a miss.
+ timeout-minutes: 10
uses: ./unsloth/.github/actions/pip-cache-save
with:
dir: ${{ steps.pip-cache.outputs.dir }}
@@ -512,13 +655,34 @@ jobs:
cache-hit: ${{ steps.pip-cache.outputs.cache-hit }}
- name: Run install cell
+ # The notebook's own install cell, which runs arbitrary pip work this
+ # workflow does not control. Uncapped, it was the remaining way to reach
+ # the job cap and be scored `cancelled`.
+ timeout-minutes: 10
+ env:
+ NOTEBOOK: ${{ matrix.notebook }}
run: |
- python unsloth/scripts/notebook_validator.py convert \
- --notebooks-dir notebooks --out _converted
- # Take the converted .py and run the install cell only.
- BASE="$(basename '${{ matrix.notebook }}' .ipynb | tr -d '()' | tr -c '[:alnum:]_' _)"
- PY="_converted/${BASE}.py"
- [ -f "$PY" ] || { echo "::error::$PY not found"; ls _converted | head; exit 1; }
+ set -euo pipefail
+ # Convert THIS notebook only, and take whatever file the converter
+ # produced, rather than converting all 560 and rebuilding the name.
+ #
+ # The name was rebuilt with
+ # basename "$nb" .ipynb | tr -d '()' | tr -c '[:alnum:]_' _
+ # which turned basename's trailing newline into a trailing underscore,
+ # so every leg looked for `<name>_.py` and none has ever been found.
+ # It also mapped dots to underscores where notebook_to_python.py keeps
+ # them. Two spellings of one rule, and the copy was wrong; asking the
+ # converter removes the second spelling entirely, and dropping 559
+ # conversions we never read removes a basename collision with it.
+ rm -rf _converted && mkdir -p _converted
+ python unsloth/scripts/notebook_to_python.py -o _converted "notebooks/$NOTEBOOK"
+ mapfile -t converted < <(find _converted -maxdepth 1 -type f -name '*.py' | sort)
+ if [ "${#converted[@]}" -ne 1 ]; then
+ echo "::error::expected exactly one converted script for $NOTEBOOK, got ${#converted[@]}"
+ printf '%s\n' "${converted[@]:-(none)}"
+ exit 1
+ fi
+ PY="${converted[0]}"
# Truncate at the first `from unsloth import` so we run install +
# core imports only.
awk '/^from unsloth import/ { print "import sys; sys.exit(0)"; exit } { print }' "$PY" > _smoke.py
@@ -532,6 +696,7 @@ jobs:
PY
- name: Verify imports under spoof
+ timeout-minutes: 5
run: |
PYTHONPATH=unsloth/tests python -u - <<'PY'
import sys, types
diff --git a/scripts/data/colab_to_cpu_pin.json b/scripts/data/colab_to_cpu_pin.json
index 51128b2ffbd..9bad6b52166 100644
--- a/scripts/data/colab_to_cpu_pin.json
+++ b/scripts/data/colab_to_cpu_pin.json
@@ -1,5 +1,7 @@
{
"_comment": "Maps Colab GPU runtime pinned wheels to CPU equivalents for ubuntu-latest CI smoke jobs. The Colab GPU image ships +cu128 builds that won't install on a CPU-only runner; this map either rewrites the spec to a CPU wheel from https://download.pytorch.org/whl/cpu or falls back to module-spoof for packages with no CPU build.",
+ "python_version": "3.13",
+ "_python_version_comment": "The interpreter the freeze beside this file was captured on. Colab rotated 3.12 to 3.13 and the freeze was refreshed, but notebooks-ci.yml stayed pinned to 3.12, so the seed install was resolving a 3.13 environment against a 3.12 runner and audioop-lts (a backport of the stdlib module 3.13 removed, hence Requires-Python >=3.13) could never resolve. That failed the bulk install on every single run and dropped the job into a 682-pin one-at-a-time fallback that spent the whole 25 minute cap. Recorded here so the workflow can assert on it instead of drifting again the next time Colab rotates.",
"rewrite": {
"torch": {
"from_local_version": "+cu128",
@@ -17,7 +19,14 @@
"module_spoof": {
"torchcodec": "no CPU wheel published; smoke job sys.modules-stubs torchcodec before importing unsloth"
},
+ "_skip_comment": "Two kinds. The nvidia-*/triton entries are CUDA runtime wheels a CPU runner cannot use. The rest are sdist-only packages whose builds need system libraries the hosted image does not carry (ipopt, dbus-1, cmake, gdal-config, cairo, R), so they cannot install on any interpreter and only ever cost build time. Observed failing in the 2026-08-31 scheduled run.",
"skip": [
+ "cyipopt",
+ "dbus-python",
+ "dlib",
+ "gdal",
+ "libcugraph-cu12",
+ "libcuvs-cu12",
"nvidia-cublas-cu12",
"nvidia-cuda-cupti-cu12",
"nvidia-cuda-nvrtc-cu12",
@@ -31,6 +40,32 @@
"nvidia-nccl-cu12",
"nvidia-nvjitlink-cu12",
"nvidia-nvtx-cu12",
+ "psycopg2",
+ "pycairo",
+ "pygobject",
+ "pylibcugraph-cu12",
+ "python-apt",
+ "rpy2",
"triton"
- ]
+ ],
+ "no_binary": [
+ "antlr4-python3-runtime",
+ "community",
+ "cufflinks",
+ "editdistance",
+ "glob2",
+ "gym",
+ "imutils",
+ "jieba",
+ "lazr.restfulclient",
+ "lazr.uri",
+ "matplotlib-venn",
+ "moviepy",
+ "promise",
+ "pydotplus",
+ "pyspark",
+ "python-louvain",
+ "wadllib"
+ ],
+ "_no_binary_comment": "Passed to pip as --no-binary, which overrides --only-binary=:all: per package. Without it the bulk resolve fails on the first of these and every run falls into the per-pin path, which is the failure this whole job kept hitting. Derived by asking PyPI, for every pin in the freeze, whether it publishes a wheel COMPATIBLE with the pinned interpreter and manylinux x86_64, not merely whether a wheel exists: editdistance ships wheels but none for cp313, and checking only for existence missed it. 18 pins have no usable wheel; psycopg2 is in skip because it needs pg_config and cannot build here, the other 17 are pure Python or build in seconds. Re-derive after any Colab rotation."
}
diff --git a/scripts/notebook_to_python.py b/scripts/notebook_to_python.py
index 4b64123d6a6..c50c98270a7 100644
--- a/scripts/notebook_to_python.py
+++ b/scripts/notebook_to_python.py
@@ -12,7 +12,6 @@ Converts IPython magics to plain Python:
/content/... -> _WORKING_DIR + /...
"""
-import nbformat
import re
import shlex
import sys
@@ -193,6 +192,10 @@ def convert_notebook(
allow_shell: bool = True,
) -> str:
"""Convert notebook JSON content to Python script."""
+ # Local, so the string helpers below import without nbformat. The CPU test job
+ # does not install it, and a module-level import failed collection there.
+ import nbformat
+
# Parse notebook
if isinstance(notebook_content, str):
notebook = nbformat.reads(notebook_content, as_version = 4)
@@ -253,6 +256,17 @@ def convert_notebook(
return "\n".join(lines)
+def converted_filename(filename: str) -> str:
+ """The .py name this script writes for a given notebook filename.
+
+ One spelling of the rule. notebooks-ci.yml had a second one in shell whose
+ `tr -c '[:alnum:]_' _` turned basename's trailing newline into a trailing
+ underscore, so the smoke job looked for `<name>_.py` and never found it.
+ """
+ out = filename.replace(".ipynb", ".py")
+ return out.replace("(", "").replace(")", "").replace("-", "_")
+
+
def convert_notebook_to_script(
source: str,
output_dir: str | None = None,
@@ -277,8 +291,7 @@ def convert_notebook_to_script(
content = f.read()
source_name = source
- output_filename = filename.replace(".ipynb", ".py")
- output_filename = output_filename.replace("(", "").replace(")", "").replace("-", "_")
+ output_filename = converted_filename(filename)
if output_dir:
output_path = os.path.join(output_dir, output_filename)
diff --git a/tests/notebooks/test_smoke_install_contract.py b/tests/notebooks/test_smoke_install_contract.py
new file mode 100644
index 00000000000..e20c6198429
--- /dev/null
+++ b/tests/notebooks/test_smoke_install_contract.py
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team.
+"""Pins the two contracts the notebooks-ci smoke job kept breaking silently.
+
+The job had never once reached the import check it exists for: 872 matrix legs
+across 109 scheduled runs and 112 days, all red. Two independent causes:
+
+ * The runner pinned Python 3.12 while the Colab snapshot beside it had been
+ refreshed to a 3.13 image. `audioop-lts` requires 3.13, so the bulk install
+ failed in 8 seconds every run and fell back to 682 one-at-a-time installs
+ that spent the whole cap. Nothing tied the two files together.
+
+ * The workflow rebuilt the converted script's filename in shell instead of
+ asking the converter, and the copy was wrong for every row of the matrix.
+
+Neither is noticeable otherwise: a leg over `timeout-minutes` is scored
+`cancelled`, and `cancelled` outranks `failure` in GitHub's run rollup.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+
+REPO = Path(__file__).resolve().parents[2]
+WORKFLOW = REPO / ".github" / "workflows" / "notebooks-ci.yml"
+MAPPING = REPO / "scripts" / "data" / "colab_to_cpu_pin.json"
+FREEZE = REPO / "scripts" / "data" / "colab_pip_freeze.gpu.txt"
+
+sys.path.insert(0, str(REPO / "scripts"))
+from notebook_to_python import converted_filename # noqa: E402
+
+JOB = "smoke-install"
+
+
+def _job() -> dict:
+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))
+ job = doc["jobs"].get(JOB)
+ assert job, f"{JOB} is gone from {WORKFLOW.name}; this file checks nothing"
+ return job
+
+
+def _notebooks() -> list[str]:
+ nbs = _job()["strategy"]["matrix"]["notebook"]
+ assert nbs, "the smoke matrix is empty; this guard checks nothing"
+ return nbs
+
+
+def _mapping() -> dict:
+ return json.loads(MAPPING.read_text(encoding = "utf-8"))
+
+
+# --- the interpreter the snapshot was taken on ---------------------------------------
+
+
+def test_the_snapshot_records_the_interpreter_it_was_captured_on():
+ assert re.fullmatch(r"3\.\d+", _mapping().get("python_version", "")), (
+ "colab_to_cpu_pin.json must record python_version, the interpreter the freeze "
+ "beside it came from. Without it nothing connects a Colab rotation to the "
+ "runner pin, which is how the job came to install a 3.13 environment on 3.12."
+ )
+
+
+def test_the_smoke_job_runs_the_interpreter_the_snapshot_names():
+ want = _mapping()["python_version"]
+ pins = [
+ str((s.get("with") or {}).get("python-version"))
+ for s in _job()["steps"]
+ if "setup-python" in str(s.get("uses", ""))
+ ]
+ assert pins, f"{JOB} does not pin an interpreter at all"
+ assert set(pins) == {want}, (
+ f"{JOB} pins Python {pins} but the Colab snapshot was captured on {want}. A pin "
+ f"carrying a Requires-Python floor above the runner cannot resolve, and one "
+ f"such pin fails the whole bulk install."
+ )
+
+
+def test_the_freeze_resolves_against_the_interpreter_the_snapshot_names():
+ """A pin whose Requires-Python floor is above the runner can never resolve.
+
+ `audioop-lts` is the live example: it exists only for 3.13+, so its presence in
+ the freeze is itself evidence of the image's interpreter.
+ """
+ want = _mapping()["python_version"]
+ names = {
+ m.group(1).lower()
+ for line in FREEZE.read_text(encoding = "utf-8").splitlines()
+ if (m := re.match(r"^([A-Za-z0-9._-]+)\s*==", line.strip()))
+ }
+ if "audioop-lts" in names:
+ assert want == "3.13" or tuple(map(int, want.split("."))) >= (3, 13), (
+ f"the freeze pins audioop-lts, which requires Python >= 3.13, but "
+ f"python_version says {want}"
+ )
+
+
+# --- the converted script's name ------------------------------------------------------
+
+
[email protected]("notebook", _notebooks())
+def test_every_matrix_notebook_maps_to_one_converted_script(notebook):
+ name = converted_filename(Path(notebook).name)
+ assert name.endswith(".py") and not name.endswith("_.py"), (
+ f"{notebook} converts to {name!r}. A trailing underscore is the signature of "
+ f"rebuilding the name in shell, where basename's newline becomes one."
+ )
+
+
+def test_converted_names_do_not_collide_across_the_matrix():
+ """The job takes 'the one .py in the output directory', so a collision hides a leg."""
+ seen: dict[str, list[str]] = {}
+ for nb in _notebooks():
+ seen.setdefault(converted_filename(Path(nb).name), []).append(nb)
+ clashes = {k: v for k, v in seen.items() if len(v) > 1}
+ assert not clashes, f"these matrix notebooks convert to the same filename: {clashes}"
+
+
+ "filename,expected",
+ [
+ ("Gemma3_(4B)-Vision.ipynb", "Gemma3_4B_Vision.py"),
+ ("Whisper.ipynb", "Whisper.py"),
+ # A dot survives; the shell copy mapped it to `_`.
+ ("Llama3.1_(8B)-GRPO.ipynb", "Llama3.1_8B_GRPO.py"),
+ ("gpt-oss-(20B)-Fine-tuning.ipynb", "gpt_oss_20B_Fine_tuning.py"),
+ ],
+)
+def test_the_naming_rule_itself(filename, expected):
+ assert converted_filename(filename) == expected
+
+
+def _shell(job) -> str:
+ """Every `run:` body in the job, comments stripped.
+
+ The steps quote the old broken pipeline to explain why it went, and a rule about
+ what the shell DOES must not read that prose as code.
+ """
+ lines = []
+ for step in job["steps"]:
+ for line in str(step.get("run", "")).splitlines():
+ if not line.lstrip().startswith("#"):
+ lines.append(line)
+ return "\n".join(lines)
+
+
+def test_the_workflow_asks_the_converter_instead_of_rebuilding_the_name():
+ """Anti-regression: the checks above read the matrix, not the step body, so
+ only this one can see a reintroduced `tr` pipeline."""
+ body = _shell(_job())
+ assert "tr -c '[:alnum:]_'" not in body, (
+ "the smoke job is rebuilding the converted filename in shell again. Call "
+ "scripts/notebook_to_python.py on the one notebook and take the file it wrote."
+ )
+ assert "notebook_to_python.py" in body, (
+ "the smoke job should convert its own matrix notebook with the converter "
+ "directly, so the name it looks for is the name that was written"
+ )
+
+
+# --- the install itself ---------------------------------------------------------------
+
+
+def test_the_seed_install_refuses_source_builds():
+ """Sdist-only pins need system libraries the runner lacks; without --only-binary
+ pip spends 20-90s per package on a doomed build."""
+ body = _shell(_job())
+ installs = [ln for ln in body.splitlines() if re.search(r"\bpip install\b", ln)]
+ offenders = [
+ ln.strip() for ln in installs if "--upgrade pip" not in ln and "--only-binary" not in ln
+ ]
+ assert not offenders, "these seed installs allow source builds:\n " + "\n ".join(offenders)
+
+
+def test_the_known_unbuildable_pins_are_skipped():
+ """Each failed a source build in the 2026-08-31 run, and one is enough to fail
+ the bulk resolve for the whole set."""
+ skip = set(_mapping()["skip"])
+ # name -> the system dependency whose absence killed its build in that run.
+ system_bound = {
+ "cyipopt": "ipopt",
+ "dbus-python": "dbus-1",
+ "dlib": "cmake",
+ "gdal": "gdal-config",
+ "pycairo": "cairo",
+ "pygobject": "girepository",
+ "python-apt": "apt",
+ "rpy2": "R_HOME",
+ }
+ missing = sorted(set(system_bound) - skip)
+ assert not missing, (
+ f"these pins cannot build on ubuntu-latest on any interpreter and only cost "
+ f"build time, so they belong in the skip list: {missing}"
+ )