CI(notebooks): cross-repo validator for unslothai/notebooks

New PR-time + scheduled workflow that walks every nb/, kaggle/, and
original_template/ notebook in unslothai/notebooks and statically
validates the install cells and user-facing code against:

  - googlecolab/backend-info pip-freeze.gpu.txt (Colab oracle, refreshed
    on every run; fallback snapshot committed under scripts/data/).
  - PyPI metadata for transitive constraint resolution.
  - Hardcoded torch/torchcodec ABI table.
  - Hardcoded peft/torchao floor table.
  - The live unsloth + trl API surface, introspected under
    tests/_zoo_aggressive_cuda_spoof.py so the api job runs on a
    GPU-less ubuntu-latest runner.

Catches the bug classes from notebooks#258 / #260 / #261 / #264 / #221
and commit 51b1462 mechanically:

  R-INST-001  forbid git+ HEAD installs (notebooks#221)
  R-INST-002  --no-deps + transitive constraint violation
  R-INST-003  peft 0.19+ requires torchao 0.16.0+ (notebooks#258)
  R-INST-004  torch <-> torchcodec ABI mismatch (notebooks#261a)
  R-INST-005  --no-deps transformers + Colab tokenizers drift
              (notebooks#261b / #264)
  R-INST-006  forbid !!pip
  R-API-003   adamw_torch_fused -> adamw_8bit hint (warning)
  R-API-004   notebook references symbols outside live unsloth surface
  R-EXC-001   DONT_UPDATE_EXCEPTIONS notebooks must satisfy the same
              policy clauses as generated notebooks (notebooks#260)
  R-DRIFT-001 update_all_notebooks.py emits no diff (commit 51b1462)
  R-CONV-001  notebook_to_python.py converts every .ipynb cleanly

Files:
  .github/workflows/notebooks-ci.yml          PR-time + cron + dispatch
  scripts/notebook_validator.py               1148 LOC, single-file
  scripts/notebook_to_python.py               battle-tested converter
  scripts/data/colab_pip_freeze.gpu.txt       fallback snapshot
  scripts/data/colab_to_cpu_pin.json          cu128 -> CPU wheel map
  tests/notebooks/test_validator_fixtures.py  21 golden tests, all green

CPU-only by design. The api-introspect job follows the existing
consolidated-tests-ci spoof pattern (lines 309/417/536/626/826/1081/
1586/1998 of consolidated-tests-ci.yml). The smoke-install job is
opt-in via workflow_dispatch and stubs torchcodec since no CPU wheel
exists.

Validated on the live unslothai/notebooks@7af0ac0f tree: every fixture
test passes, exceptions check is silent, lint surfaces 27 errors + 6
warnings on real notebooks (mix of #258-class regressions in 6 nb/
notebooks the previous template fixes did not reach, plus 14
git+-HEAD installs in hand-tuned exception notebooks).

.github/workflows/notebooks-ci.yml

@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+#
+# Cross-repo notebook validator. Lives in unslothai/unsloth (this repo)
+# and inspects every notebook in unslothai/notebooks at HEAD (or the
+# ref dispatched in via repository_dispatch).
+#
+# Catches the bug classes that landed in:
+#   - unslothai/notebooks#258  Colab torchao 0.10 vs peft 0.19 floor
+#   - unslothai/notebooks#260  DONT_UPDATE_EXCEPTIONS coverage drift
+#   - unslothai/notebooks#261  torch/torchcodec ABI; --no-deps tokenizers
+#   - unslothai/notebooks#264  --no-deps transformers + Colab tokenizers drift
+#   - unslothai/notebooks#221  git+ HEAD installs in install cells
+#   - unslothai/notebooks  commit 51b1462  template/notebook drift
+#
+# CPU-only by design. Layer 2 (api-introspect) reuses the existing
+# tests/_zoo_aggressive_cuda_spoof.py harness so `import unsloth`
+# succeeds on a GPU-less ubuntu-latest runner.
+
+name: Notebooks CI
+
+on:
+  pull_request:
+    paths:
+      - 'unsloth/**'
+      - 'scripts/notebook_validator.py'
+      - 'scripts/notebook_to_python.py'
+      - 'scripts/data/colab_pip_freeze.gpu.txt'
+      - 'scripts/data/colab_to_cpu_pin.json'
+      - 'tests/notebooks/**'
+      - 'tests/_zoo_aggressive_cuda_spoof.py'
+      - '.github/workflows/notebooks-ci.yml'
+  schedule:
+    # Daily 06:17 UTC. Catches Colab preinstall bumps (the upstream image
+    # is rebuilt roughly weekly) without us waiting on a PR. Off the
+    # :00/:30 fleet-collision spots.
+    - cron: '17 6 * * *'
+  workflow_dispatch:
+    inputs:
+      notebooks_ref:
+        description: 'unslothai/notebooks ref to lint (branch / SHA / tag)'
+        default: 'main'
+      include_smoke:
+        description: 'Also run the install-cell smoke matrix (longer)'
+        type: boolean
+        default: false
+  repository_dispatch:
+    # Fired by a tiny companion workflow on unslothai/notebooks.
+    types: [notebooks_pr_opened, notebooks_main_pushed]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  NOTEBOOKS_REF: >-
+    ${{ github.event.inputs.notebooks_ref ||
+        github.event.client_payload.ref ||
+        'main' }}
+
+jobs:
+  static:
+    name: static (drift + lint + exceptions)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout unsloth (this PR)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with:
+          path: unsloth
+
+      - name: Checkout unslothai/notebooks @ ${{ env.NOTEBOOKS_REF }}
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with:
+          repository: unslothai/notebooks
+          ref: ${{ env.NOTEBOOKS_REF }}
+          path: notebooks
+          fetch-depth: 0  # drift check needs git status / diff
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install validator deps
+        run: |
+          python -m pip install --upgrade pip
+          # nbformat + nbconvert come from the converter's requirements;
+          # spellchecker + huggingface_hub are imported at module top of
+          # update_all_notebooks.py.
+          pip install \
+            'nbformat>=5.10' 'nbconvert>=7.16' 'pyspellchecker>=0.8' \
+            'huggingface_hub>=0.34' 'tqdm>=4.66'
+
+      - name: Refresh Colab pip-freeze (best-effort; falls back to snapshot)
+        run: |
+          python unsloth/scripts/notebook_validator.py refresh-colab \
+              --out unsloth/scripts/data/colab_pip_freeze.gpu.txt \
+            || echo "::warning::refresh-colab failed; using committed snapshot"
+
+      - name: Drift check (re-run update_all_notebooks.py + git diff)
+        working-directory: ${{ github.workspace }}
+        run: |
+          python unsloth/scripts/notebook_validator.py drift \
+              --notebooks-dir notebooks
+
+      - name: Convert sanity (every nb / kaggle / original_template -> .py)
+        run: |
+          python unsloth/scripts/notebook_validator.py convert \
+              --notebooks-dir notebooks \
+              --out _converted
+
+      - name: Lint (install cells + AST scan, env-scoped)
+        run: |
+          python unsloth/scripts/notebook_validator.py lint \
+              --notebooks-dir notebooks \
+              --colab-pin unsloth/scripts/data/colab_pip_freeze.gpu.txt \
+              --no-pypi
+        # --no-pypi skips R-INST-002 (transitive resolve via PyPI metadata).
+        # Layer 1 keeps PR-time wall-clock predictable; the daily cron run
+        # below drops --no-pypi and refreshes the cache.
+
+      - name: DONT_UPDATE_EXCEPTIONS coverage
+        run: |
+          python unsloth/scripts/notebook_validator.py exceptions \
+              --notebooks-dir notebooks
+
+  static-with-pypi:
+    name: static + transitive resolve (cron / dispatch only)
+    if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with: { path: unsloth }
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with:
+          repository: unslothai/notebooks
+          ref: ${{ env.NOTEBOOKS_REF }}
+          path: notebooks
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with: { python-version: '3.12', cache: 'pip' }
+      - name: Install
+        run: pip install -U pip
+      - name: Refresh Colab oracle
+        run: |
+          python unsloth/scripts/notebook_validator.py refresh-colab \
+              --out unsloth/scripts/data/colab_pip_freeze.gpu.txt
+      - name: Lint with live PyPI metadata
+        run: |
+          python unsloth/scripts/notebook_validator.py lint \
+              --notebooks-dir notebooks \
+              --colab-pin unsloth/scripts/data/colab_pip_freeze.gpu.txt
+
+  api-introspect:
+    name: api surface (under CUDA spoof)
+    runs-on: ubuntu-latest
+    timeout-minutes: 12
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with: { path: unsloth }
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with:
+          repository: unslothai/notebooks
+          ref: ${{ env.NOTEBOOKS_REF }}
+          path: notebooks
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with: { python-version: '3.12', cache: 'pip' }
+
+      - name: Install CPU torch + pinned unsloth + trl
+        run: |
+          python -m pip install --upgrade pip
+          pip install --index-url https://download.pytorch.org/whl/cpu 'torch>=2.8,<2.11'
+          # Pin to the same versions update_all_notebooks.py installs in
+          # generated notebooks. Keep these in lockstep with PIN_TRL /
+          # PIN_TRANSFORMERS in unslothai/notebooks/update_all_notebooks.py.
+          pip install 'transformers>=4.56,<5.6' 'trl>=0.22,<0.26' 'accelerate>=1.0' \
+                      'datasets>=3.4,<5' 'peft>=0.15,<0.20' \
+                      'bitsandbytes>=0.43' 'sentencepiece' 'protobuf'
+          pip install --no-deps unsloth_zoo unsloth
+
+      - name: Convert notebooks for AST scan
+        run: |
+          python unsloth/scripts/notebook_validator.py convert \
+              --notebooks-dir notebooks --out _converted
+
+      - name: Dump unsloth + trl API surface (under CUDA spoof)
+        run: |
+          PYTHONPATH=unsloth/tests python -u - <<'PY'
+          import sys, json, inspect
+          import _zoo_aggressive_cuda_spoof as _spoof
+          _spoof.apply()
+          import unsloth
+          import trl
+          surface = {}
+          for cls_name in ("FastLanguageModel", "FastVisionModel", "FastModel"):
+              cls = getattr(unsloth, cls_name, None)
+              if cls is None:
+                  continue
+              surface[cls_name] = sorted(n for n in dir(cls) if not n.startswith("_"))
+          surface["SFTConfig_kwargs"] = sorted(inspect.signature(trl.SFTConfig.__init__).parameters)
+          json.dump(surface, open("_api_surface.json", "w"), indent=2)
+          print("dumped surface for:", list(surface))
+          PY
+
+      - name: Run API rule against converted notebooks
+        run: |
+          python unsloth/scripts/notebook_validator.py api \
+              --converted-dir _converted \
+              --surface _api_surface.json
+
+  smoke-install:
+    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
+    strategy:
+      fail-fast: false
+      matrix:
+        # One representative notebook per installation_*_content template.
+        # Add rows when a new install template lands in update_all_notebooks.py.
+        notebook:
+          - 'nb/Llama3.1_(8B)-Alpaca.ipynb'           # installation_content
+          - 'nb/Gemma3_(4B)-Vision.ipynb'             # installation_content + vision
+          - 'nb/Llama3.1_(8B)-GRPO.ipynb'             # installation_extra_grpo_content
+          - 'nb/gpt-oss-(20B)-Fine-tuning.ipynb'      # installation_gpt_oss_content
+          - 'nb/Qwen3_5_(4B)_Vision.ipynb'            # installation_qwen3_5_content
+          - 'nb/Nemotron-3-Nano-30B-A3B_A100.ipynb'   # installation_nemotron_nano_content
+          - 'nb/Whisper.ipynb'                         # installation_whisper_content
+          - 'nb/Synthetic_Data_Hackathon.ipynb'        # installation_synthetic_data_content
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with: { path: unsloth }
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+        with:
+          repository: unslothai/notebooks
+          ref: ${{ env.NOTEBOOKS_REF }}
+          path: notebooks
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with: { python-version: '3.12' }
+
+      - name: Seed Colab-shaped venv from pip-freeze (CPU-mapped)
+        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
+          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 = []
+          for line in open("unsloth/scripts/data/colab_pip_freeze.gpu.txt"):
+              line = line.strip()
+              if not line or line.startswith("#"):
+                  continue
+              m = re.match(r"^([A-Za-z0-9._-]+)\s*==\s*(.+)$", line)
+              if not m:
+                  continue
+              name, ver = m.group(1).lower(), m.group(2)
+              if name in skip:
+                  continue
+              if 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))
+          PY
+          head -5 /tmp/seed_pins.txt
+          wc -l /tmp/seed_pins.txt
+
+      - name: Install Colab-shaped venv
+        run: |
+          python -m pip install --upgrade pip
+          # Best-effort: any single line that fails to resolve on CPU is
+          # tolerated; the smoke contract is "the install cell + the unsloth
+          # import works", not "the entire Colab venv reproduces."
+          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
+
+      - name: Run install cell
+        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; }
+          # 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
+          PYTHONPATH=unsloth/tests python -u - <<'PY'
+          import _zoo_aggressive_cuda_spoof as _s; _s.apply()
+          # Stub torchcodec for cells that import it — no CPU wheel exists.
+          import sys, types
+          if "torchcodec" not in sys.modules:
+              sys.modules["torchcodec"] = types.ModuleType("torchcodec")
+          exec(open("_smoke.py").read(), {"__name__": "__main__"})
+          PY
+
+      - name: Verify imports under spoof
+        run: |
+          PYTHONPATH=unsloth/tests python -u - <<'PY'
+          import sys, types
+          if "torchcodec" not in sys.modules:
+              sys.modules["torchcodec"] = types.ModuleType("torchcodec")
+          import _zoo_aggressive_cuda_spoof as _s; _s.apply()
+          import unsloth, peft, torch, torchao, transformers, tokenizers
+          print("OK: imports pass under CUDA spoof")
+          PY