Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.ymlindex 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: 70strategy:fail-fast: falsematrix:@@ -419,8 +439,14 @@ jobs:ref: ${{ env.NOTEBOOKS_REF }}path: notebookspersist-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 cacheid: 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: 8with: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: 3run: |- # 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, sysmapping = 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:continuename, 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.txthead -5 /tmp/seed_pins.txtwc -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: 30run: |- 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 1fi+ 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 cacheif: 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: 10uses: ./unsloth/.github/actions/pip-cache-savewith: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: 5run: |PYTHONPATH=unsloth/tests python -u - <<'PY'import sys, typesdiff --git a/scripts/data/colab_to_cpu_pin.json b/scripts/data/colab_to_cpu_pin.jsonindex 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.pyindex 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 nbformatimport reimport shleximport 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 notebookif 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.pynew file mode 100644index 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}"+ )