feat: added images, new sft notebook, jobs to do grpo

.cursorrules

@@ -3,7 +3,7 @@
 ## Training Results Page
 - Route: `GET /train` → `dashboard/train_results.html` (served from `main.py`)
 - API: `GET /api/training-status` → reads `results/eval_results.json` when present; exposes plot file flags and `HF_MODEL_REPO` presence
-- Static: `results/` is served at `/results/` via `StaticFiles` in `main.py` (directory is created on startup if missing)
+- Static: `results/` at `/results/`, `images/` at `/images/` (e.g. committed `images/sft_loss_curve.png`) via `StaticFiles` in `main.py`
 - `results/` is gitignored for data; plot PNGs/HTML can be committed intentionally if the team chooses
 - The `/train` page uses placeholders when files are missing
 - Training runs in Colab / local GPU — **not** inside the Space process

README.md

@@ -165,6 +165,8 @@ GRPO Fine-tuning — 100 steps, G=4, static JSONL prompts
   sh4shv4t/parlay-grpo-1-5b
 ```
 
+**Run GRPO on Hugging Face Jobs** (pre-paid credits, data + SFT on the Hub; `scripts/hf_grpo_entry.sh`; template uses **`--timeout 6h`** and **`a100-large`**): see [`training/GRPO_HF_RUNBOOK.md`](training/GRPO_HF_RUNBOOK.md).
+
 ```text
 Gemini self-play (generate_data.py)
     → 80 quality-filtered episodes across 9 persona×scenario combos
@@ -184,6 +186,8 @@ The ω warmup is a practical detail worth flagging: at step 0, the base model oc
 
 ### Results
 
+![SFT training loss — Qwen2.5-1.5B + LoRA on Parlay episodes](images/sft_loss_curve.png)
+
 ![Mean episode reward over GRPO training steps](results/grpo_reward_curve.png)
 
 ![GRPO training loss](results/grpo_loss_curve.png)

dashboard/api.py

@@ -48,6 +48,7 @@ _sessions: dict[str, dict[str, Any]] = {}
 # Opponent backend for /api/game/move: "gemini" (default) or "trained" (HF_MODEL_REPO + Qwen)
 OPPONENT_MODE: str = "gemini"
 _RESULTS_DIR = Path("results")
+_IMAGES_DIR = Path("images")
 _CP_COSTS: dict[TacticalMove, int] = {
     TacticalMove.ANCHOR_HIGH: 0,
     TacticalMove.BATNA_REVEAL: 20,
@@ -345,6 +346,13 @@ def _training_status_payload() -> dict[str, Any]:
         except Exception:  # noqa: BLE001
             has_results = False
     repo = (os.environ.get("HF_MODEL_REPO") or "").strip() or None
+
+    sft_loss_path: str | None = None
+    if (_IMAGES_DIR / "sft_loss_curve.png").is_file():
+        sft_loss_path = "/images/sft_loss_curve.png"
+    elif (_RESULTS_DIR / "sft_loss_curve.png").is_file():
+        sft_loss_path = "/results/sft_loss_curve.png"
+
     return {
         "has_results": has_results,
         "grpo_mean_reward": grpo,
@@ -352,10 +360,12 @@ def _training_status_payload() -> dict[str, Any]:
         "random_mean_reward": rnd,
         "model_on_hub": bool(repo),
         "model_repo": repo,
+        "sft_loss_url": sft_loss_path,
         "plots_available": {
             "reward_curve": (_RESULTS_DIR / "grpo_reward_curve.png").is_file(),
             "comparison": (_RESULTS_DIR / "training_curves.png").is_file(),
             "transcript": (_RESULTS_DIR / "before_after_transcript.html").is_file(),
+            "sft_loss": sft_loss_path is not None,
         },
     }
 

dashboard/train_results.html

@@ -136,6 +136,12 @@
       </div>
     </section>
 
+    <section>
+      <h2>SFT cold start — training loss</h2>
+      <div id="fig-sft"></div>
+      <p class="caption" id="cap-sft" hidden>Supervised fine-tuning loss (Qwen2.5-1.5B + LoRA on Parlay episodes from Colab).</p>
+    </section>
+
     <section>
       <h2>GRPO Training Curve</h2>
       <div id="fig-reward"></div>
@@ -198,6 +204,19 @@
         d.style.color = x >= 0 ? "var(--emerald)" : "var(--scarlet)";
       }
     }
+    function sftSection(url) {
+      const el = document.getElementById("fig-sft");
+      const cap = document.getElementById("cap-sft");
+      if (url) {
+        el.innerHTML = '<img src="' + url + '" alt="SFT training loss" style="width:100%;border:1px solid var(--gold);border-radius:2px" />';
+        cap.hidden = false;
+      } else {
+        el.innerHTML = '<div class="fig-placeholder">SFT loss curve will appear after running ' +
+          '<a href="https://colab.research.google.com/github/sh4shv4t/Parlay/blob/main/training/notebooks/sft_qwen_colab.ipynb" target="_blank" rel="noopener">sft_qwen_colab.ipynb</a> ' +
+          'or by adding <code>images/sft_loss_curve.png</code> to the repo.</div>';
+        cap.hidden = true;
+      }
+    }
     function rewardSection(pa) {
       const el = document.getElementById("fig-reward");
       const cap = document.getElementById("cap-reward");
@@ -272,6 +291,7 @@
         if (data.has_results) {
           document.querySelector(".subtitle")?.setAttribute("data-has-eval", "1");
         }
+        sftSection(data.sft_loss_url);
         rewardSection(data.plots_available);
         compareSection(data.plots_available);
         await transcriptSection(data.plots_available);

main.py

@@ -78,6 +78,12 @@ try:
 except OSError as exc:
     logger.warning("Could not mount /results: %s", exc)
 
+os.makedirs("images", exist_ok=True)
+try:
+    app.mount("/images", StaticFiles(directory="images"), name="images")
+except OSError as exc:
+    logger.warning("Could not mount /images: %s", exc)
+
 
 @app.get("/", include_in_schema=False)
 async def serve_index() -> FileResponse:

scripts/hf_grpo_entry.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Run from the Parlay repository root (the folder that contains training/ and parlay_env/).
+# Intended for Linux GPU jobs (Hugging Face Jobs, RunPod, etc.).
+#
+# Usage (after: git clone ... && cd Parlay && pip install -r requirements-train.txt):
+#   export HF_TOKEN=...          # read private assets + push (required if PUSH_TO_HF=1)
+#   export GRPO_STEPS=120 GRPO_G=4
+#   bash scripts/hf_grpo_entry.sh
+#
+# See training/GRPO_HF_RUNBOOK.md for a full walkthrough.
+set -euo pipefail
+export PYTHONUNBUFFERED=1
+
+: "${DATASET_ID:=sh4shv4t/parlay-episodes}"
+: "${EPISODE_FILE:=episodes_v2.jsonl}"
+: "${SFT_MODEL:=sh4shv4t/parlay-sft-1-5b}"
+: "${GRPO_STEPS:=120}"
+: "${GRPO_G:=4}"
+: "${MIN_REWARD:=-50.0}"
+: "${OUTPUT_DIR:=outputs/grpo_run}"
+# Set to 0 to skip push (e.g. smoke test)
+: "${PUSH_TO_HF:=1}"
+# Model repo to upload the GRPO output folder to
+: "${HF_GRPO_REPO:=sh4shv4t/parlay-grpo-1-5b}"
+
+if [[ ! -f "training/grpo_train.py" ]]; then
+  echo "Run this script from the Parlay repo root (training/grpo_train.py not found). pwd=$(pwd)" >&2
+  exit 1
+fi
+
+echo "==> Downloading ${EPISODE_FILE} from dataset ${DATASET_ID} ..."
+export DATASET_ID EPISODE_FILE
+JSONL_PATH=$(
+  python -c "import os
+from huggingface_hub import hf_hub_download
+print(hf_hub_download(
+    repo_id=os.environ['DATASET_ID'],
+    filename=os.environ['EPISODE_FILE'],
+    repo_type='dataset',
+))"
+)
+echo "    JSONL: ${JSONL_PATH}"
+
+mkdir -p "$(dirname "$OUTPUT_DIR")"
+OUT_ABS="$(cd "$(dirname "$OUTPUT_DIR")" && pwd)/$(basename "$OUTPUT_DIR")"
+
+echo "==> GRPO: SFT=${SFT_MODEL} steps=${GRPO_STEPS} G=${GRPO_G} out=${OUT_ABS}"
+python -m training.grpo_train \
+  --model "${SFT_MODEL}" \
+  --data "${JSONL_PATH}" \
+  --output "${OUT_ABS}" \
+  --steps "${GRPO_STEPS}" \
+  --g "${GRPO_G}" \
+  --min-reward "${MIN_REWARD}"
+
+# Bundle Matplotlib curves + TRL log JSON into the model folder so one Hub upload includes visualizations.
+echo "==> Collecting training plots under ${OUT_ABS}/training_plots/ ..."
+TP="${OUT_ABS}/training_plots"
+mkdir -p "${TP}"
+for f in results/grpo_reward_curve.png results/grpo_loss_curve.png; do
+  if [[ -f "$f" ]]; then
+    cp -f "$f" "${TP}/"
+    echo "    + ${f}"
+  fi
+done
+if [[ -d "${OUT_ABS}/plots" ]]; then
+  shopt -s nullglob
+  for f in "${OUT_ABS}/plots/"*.png "${OUT_ABS}/plots/"*.json; do
+    [[ -e "$f" ]] || continue
+    cp -f "$f" "${TP}/"
+    echo "    + ${f}"
+  done
+  shopt -u nullglob
+fi
+if [[ ! -f "${TP}/grpo_reward_curve.png" && ! -f "${TP}/grpo_reward.png" ]]; then
+  echo "    (warning: no reward plot in training_plots — check logs for empty log_history or plot errors)"
+fi
+
+if [[ "${PUSH_TO_HF}" == "1" || "${PUSH_TO_HF}" == "true" ]]; then
+  if [[ -z "${HF_TOKEN:-}" && -z "${HUGGINGFACE_HUB_TOKEN:-}" ]]; then
+    echo "PUSH_TO_HF is set but neither HF_TOKEN nor HUGGINGFACE_HUB_TOKEN is set." >&2
+    exit 1
+  fi
+  # push_to_hub.py reads HF_TOKEN; Jobs often set HUGGINGFACE_HUB_TOKEN
+  export HF_TOKEN="${HF_TOKEN:-${HUGGINGFACE_HUB_TOKEN:-}}"
+  echo "==> Pushing to https://huggingface.co/${HF_GRPO_REPO} ..."
+  export HF_REPO_ID="${HF_GRPO_REPO}"
+  python -m training.push_to_hub --model "${OUT_ABS}" --repo "${HF_GRPO_REPO}"
+else
+  echo "==> PUSH_TO_HF disabled; model saved at ${OUT_ABS}"
+fi
+
+echo "==> Done."

training/GRPO_HF_RUNBOOK.md

@@ -0,0 +1,174 @@
+# Run Parlay GRPO on Hugging Face (Jobs + your credits)
+
+## Checklist — what you actually do
+
+1. **On your PC:** install the HF CLI → `hf auth login` (token with read + write).
+2. **Money:** confirm [pre-paid credits / billing](https://huggingface.co/settings/billing) ($30 is enough for a modest A100 run if you cap time and steps).
+3. **Repo:** commit and push this repo (including `scripts/hf_grpo_entry.sh`) to GitHub — or set `GITHUB_CLONE` in the job to a URL/branch that has the script.
+4. **Start the job** from your terminal using the **`hf jobs run ... huggingface/trl ...`** command in [§3.1](#31-command-template). This runbook uses **`--timeout 6h`** on **`a100-large`** (see [§3.2](#32-is-6-hours-on-a100-enough)).
+5. **Watch** [huggingface.co/jobs](https://huggingface.co/jobs) until it finishes or errors.
+6. **Artifacts:** the trained adapter lands in `HF_GRPO_REPO` (default `sh4shv4t/parlay-grpo-1-5b`). **Plots** are generated during training and copied into **`training_plots/`** inside that upload (see [Visualizations](#visualizations--curves)).
+7. **Optional — local app / README:** download `grpo_reward_curve.png` / `grpo_loss_curve.png` from the model repo’s `training_plots/` (or from the job’s `results/` folder) and put them in your clone under `results/` so the Space **Training Results** page can show them ([`dashboard/api.py`](../dashboard/api.py) looks for `results/grpo_reward_curve.png`).
+
+---
+
+This walkthrough uses assets that are **already on the Hub**:
+
+| What | Hub ID |
+|------|--------|
+| Episodes JSONL (dataset) | `sh4shv4t/parlay-episodes` (file: `episodes_v2.jsonl`) |
+| SFT LoRA (starting point) | `sh4shv4t/parlay-sft-1-5b` |
+| Optional: upload GRPO output here | `sh4shv4t/parlay-grpo-1-5b` (default in `scripts/hf_grpo_entry.sh`) |
+
+`training/grpo_train.py` loads the SFT **adapter** from the Hub (it looks for `adapter_config.json` and fetches the **base** model name from that file, usually `Qwen/Qwen2.5-1.5B-Instruct`).
+
+**Requirements:** a Hugging Face account with [pre-paid credits](https://huggingface.co/pricing) and a [fine-grained or classic token](https://huggingface.co/settings/tokens) with **read** (dataset + models) and **write** (if you push the trained adapter to your model repo).
+
+---
+
+## 0. What you are paying for
+
+- [Jobs pricing](https://huggingface.co/docs/hub/jobs-pricing) is **per minute** while the job is **starting** or **running** (rough guide: 1× A100 large ≈ $2.50/hr; **$30** is on the order of **~12 h** on that flavor if you used it nonstop—always check the current table).
+- The default timeout for Jobs is **short**; you must set **`--timeout`**. This guide standardizes on **`6h`** for **1× A100** with `GRPO_STEPS=120` and `G=4` (see §3.2). Cost is still **~per minute of runtime** (see current [pricing](https://huggingface.co/docs/hub/jobs-pricing)).
+
+---
+
+## 1. One-time setup on your laptop
+
+1. **Install the HF CLI** (see [Quickstart](https://huggingface.co/docs/hub/jobs-quickstart)):
+   - e.g. `curl -LsSf https://hf.co/cli/install.sh | bash` (macOS/Linux) or the Windows installer from the same doc page.
+2. **Log in**:
+   - `hf auth login`  
+   - Paste a token with **read** and **write** to the Hub.
+3. **Confirm credits** at [huggingface.co/settings/billing](https://huggingface.co/settings/billing).
+4. **Open the Jobs UI** to watch runs: [huggingface.co/jobs](https://huggingface.co/jobs) (or your org’s jobs page).
+
+---
+
+## 2. What the repo provides
+
+From the **repository root** after `git clone`:
+
+- **`scripts/hf_grpo_entry.sh`**  
+  - Downloads `episodes_v2.jsonl` from `sh4shv4t/parlay-episodes`  
+  - Runs `python -m training.grpo_train` with the Hub SFT adapter  
+  - Optionally runs `python -m training.push_to_hub` to upload the output folder
+
+You only need a **GPU Linux** environment with **git**, **Python**, and **pip**; the rest is installed from `requirements-train.txt`.
+
+---
+
+## 3. Recommended: Hugging Face Job with the TRL image
+
+Hugging Face documents a ready image for TRL workflows: `huggingface/trl` (see [Popular images](https://huggingface.co/docs/hub/jobs-popular-images)).
+
+### 3.1 Command template
+
+Run this from **your** machine; it starts the job in the cloud and streams logs. Adjust `GITHUB_CLONE` if you use a fork (your MetaHackathon mirror should push to GitHub or you must change the URL).
+
+```bash
+# `--secrets HF_TOKEN` passes your Hub token (from `hf auth login`) into the job for downloads + push.
+# Image is the first *positional* argument after flags (same pattern as: hf jobs run ubuntu echo hi).
+# Point GITHUB_CLONE at your fork if needed.
+hf jobs run \
+  --flavor a100-large \
+  --timeout 5h \
+  --secrets HF_TOKEN \
+  --env GITHUB_CLONE=https://github.com/sh4shv4t/Parlay.git \
+  --env GRPO_STEPS=120 \
+  --env GRPO_G=4 \
+  --env PUSH_TO_HF=1 \
+  --env HF_GRPO_REPO=sh4shv4t/parlay-grpo-1-5b \
+  huggingface/trl \
+  bash -lc 'set -e; apt-get update -qq && apt-get install -y -qq git; git clone --depth 1 "$GITHUB_CLONE" /work; cd /work; pip install -q -r requirements-train.txt; bash scripts/hf_grpo_entry.sh'
+```
+
+**Note:** if your CLI version differs, run `hf jobs run --help`. If the image already has `git`, drop the `apt-get` / `apt-get install` lines. The TRL image is listed under [Popular images](https://huggingface.co/docs/hub/jobs-popular-images). For a UV-based job instead, see `hf jobs uv run --image huggingface/trl ...` in the same page (usually a small `train.py`); Parlay’s GRPO needs the **full** repo, so the `git clone` pattern above is the straightforward fit.
+
+**Windows:** run this block from **Git Bash** or **WSL** (so `bash -lc '... "$GITHUB_CLONE" ...'` is parsed like Linux). In plain PowerShell, quote escaping is different—open this file in an editor and paste the block there.
+
+**Environment variables** you can add with `--env`:
+
+| Variable | Default (in `hf_grpo_entry.sh`) | Purpose |
+|----------|---------------------------------|---------|
+| `DATASET_ID` | `sh4shv4t/parlay-episodes` | JSONL source |
+| `EPISODE_FILE` | `episodes_v2.jsonl` | File inside the dataset repo |
+| `SFT_MODEL` | `sh4shv4t/parlay-sft-1-5b` | Hub LoRA to continue from |
+| `GRPO_STEPS` | `120` | Training steps |
+| `GRPO_G` | `4` | Group size (lower if OOM) |
+| `MIN_REWARD` | `-50.0` | Skips very bad train rows |
+| `OUTPUT_DIR` | `outputs/grpo_run` | Local output in the job |
+| `PUSH_TO_HF` | `1` | Set to `0` to skip upload |
+| `HF_GRPO_REPO` | `sh4shv4t/parlay-grpo-1-5b` | Push target |
+
+`HF_TOKEN` is provided by **`--secrets HF_TOKEN`** (or the short form your CLI supports) so `huggingface-cli` / `huggingface_hub` can push; it must be allowed to write to `HF_GRPO_REPO`.
+
+### 3.2 Is 6 hours on A100 enough?
+
+**Usually yes** for the template defaults: **Qwen2.5-1.5B** + SFT LoRA, **`GRPO_STEPS=120`**, **`GRPO_G=4`**. In practice, training often finishes in **on the order of 1–3 hours** of wall time; **6h** is a **safety cap** for Hub downloads, first-time `pip install`, and plotting—so the job is not cut off at the default short timeout. If you **increase** steps into the many hundreds, either raise **`--timeout` to `8h`** or **lower** `GRPO_STEPS` / `G` to stay inside 6h.
+
+### 3.3 If the job OOMs
+
+Lower **`GRPO_G`** first (e.g. `2` or `1`), then **`GRPO_STEPS`**. A100 80GB usually runs `G=4` for this 1.5B setup; T4-style VRAM may need `G=2`.
+
+### 3.4 If the job times out
+
+Increase **`--timeout`**, or run two shorter jobs: first run saves under `OUTPUT_DIR` / Hub; a second could continue from a saved adapter (only if you wire resume in your workflow—the stock `grpo_train` is single-stage; the practical fix is a longer timeout or fewer steps per job and manual continuation by pointing `--model` at the last save).
+
+### 3.5 Cheaper hardware
+
+Use `--flavor t4-small` (or `l4x1` per [hardware list](https://huggingface.co/docs/hub/jobs-pricing)) and reduce steps + `G` so the job **finishes** within the timeout; you trade wall-clock and quality for cost.
+
+### 3.6 After the run
+
+- **Model:** [huggingface.co/sh4shv4t/parlay-grpo-1-5b](https://huggingface.co/sh4shv4t/parlay-grpo-1-5b) (if you pushed to that repo).
+- **Curves:** also under that repo in **`training_plots/`** (bundled by `scripts/hf_grpo_entry.sh` before upload).
+
+---
+
+## Visualizations & curves
+
+GRPO already **builds charts in code** (`training/grpo_train.py` → `_save_training_plots`):
+
+| Output | Where it is written during training | What it shows |
+|--------|-------------------------------------|----------------|
+| Reward curve | `results/grpo_reward_curve.png` and `<output>/plots/grpo_reward.png` | Mean reward vs step (blue) |
+| Loss curve | `results/grpo_loss_curve.png` and `<output>/plots/grpo_loss.png` | Training loss vs step |
+| Raw TRL logs | `<output>/plots/grpo_log.json` | Full `log_history` for your own plotting |
+
+**`scripts/hf_grpo_entry.sh`** copies those into **`<OUTPUT_DIR>/training_plots/`** before `push_to_hub`, so after a successful job you get **PNGs + JSON on the model card** next to the adapter (no extra step).
+
+**Training Results page (`/train`):** the API exposes `plots_available.reward_curve` when **`results/grpo_reward_curve.png`** exists in the deployed app’s repo. After you download the PNGs from the Hub (or copy from a job artifact), add them under `results/` in the git repo you deploy to Spaces and redeploy.
+
+**Optional extras (not wired in repo by default):**
+
+- **W&B / TensorBoard:** set `report_to` in `GRPOConfig` inside `training/grpo_train.py` if you want live dashboards (adds setup and secrets).
+- **Eval bar chart:** after GRPO, run `python -m training.evaluate ...` locally or in a small job to regenerate `results/eval_results.json` and comparison figures (see main README).
+
+---
+
+## 4. Alternative: `hf jobs uv run` (TRL quickstart style)
+
+The [Jobs quickstart](https://huggingface.co/docs/hub/jobs-quickstart) uses `hf jobs uv run` with `--with trl` and a small `train.py`. Parlay’s GRPO needs the **full repo** (for `parlay_env` and reward functions), so the **`git clone` + `huggingface/trl` image** pattern in §3 is usually simpler than inlining the whole project into one file.
+
+---
+
+## 5. Alternative: Colab (no Jobs)
+
+Use `notebooks/parlay_grpo_colab.ipynb`. In the **config** cell, set:
+
+```python
+JSONL_VIA_HF = ("sh4shv4t/parlay-episodes", "episodes_v2.jsonl")
+SFT_MODEL_HF = "sh4shv4t/parlay-sft-1-5b"
+# Optional: use Colab Pro+ or a longer runtime; HF Jobs avoids Colab’s usage caps.
+```
+
+---
+
+## 6. Sanity checks before spending credits
+
+- **Non-empty train split:** `grpo_train` only uses JSONL lines with `"split": "train"`. If the script prints `0 remaining for GRPO`, fix the JSONL or filters (`MIN_REWARD`).
+- **Token:** `python -c "from huggingface_hub import hf_hub_download; print(hf_hub_download('sh4shv4t/parlay-episodes','episodes_v2.jsonl', repo_type='dataset'))"` on your machine should print a local path.
+- **Config pre-flight:** `python scripts/check_training_config.py` (read-only) reviews env defaults for SFT/GRPO.
+
+If anything in this file drifts (repo names, file names), align with `README.md` and `scripts/push_dataset.py` (`episodes_v2.jsonl`).

training/notebooks/build_sft_qwen_colab.py

@@ -38,7 +38,11 @@ episodes using **Supervised Fine-Tuning (SFT)** with LoRA via
 3. Formats to ChatML, trains with LoRA (r=16)
 4. Plots, evaluates before/after, pushes adapter to `sh4shv4t/parlay-negotiator`
 
-**Runtime:** ~25 min on T4 · **Cost:** $0 (free tier).""")
+**Runtime:** ~25 min on T4 · **Cost:** $0 (free tier).
+
+**If `load_dataset` fails on `Feature type 'Json'`:** the install cell upgrades `datasets`;
+if it still fails, use **Runtime → Restart runtime**, then run from Step 2 onward. The
+data cell also falls back to downloading `episodes_v2.jsonl` directly (no `Json` schema).""")
 
 add_md("## Step 1 — Install dependencies")
 
@@ -52,18 +56,39 @@ subprocess.run([
 subprocess.run([
     sys.executable, "-m", "pip", "install",
     "trl>=0.8.6", "peft>=0.10.0", "accelerate>=0.28.0",
-    "datasets>=2.18.0", "huggingface-hub>=0.22.0",
     "bitsandbytes>=0.43.0", "xformers", "--quiet",
 ], check=True)
-print("OK: dependencies")""")
+# Hub dataset uses `Json` features — needs datasets 3.x (Colab ships an older build)
+subprocess.run([
+    sys.executable, "-m", "pip", "install",
+    "-U", "datasets>=3.0.0", "huggingface-hub>=0.23.0", "pyarrow>=14.0.0",
+    "--quiet",
+], check=True)
+import os
+os.environ.setdefault("UNSLOTH_DISABLE_STATISTICS", "1")
+print("OK: dependencies (datasets>=3 for Json dtype on Hub)")""")
+
+add_md("""## Step 2 — GPU + config
 
-add_md("## Step 2 — GPU + config")
+**GPU required** (Unsloth + 4-bit QLoRA will not run on CPU).
+
+In Colab: **Runtime** → **Change runtime type** → **Hardware accelerator** = **T4** (or L4 / A100 / V100) → **Save**, then re-run this cell. Free tier: choose **T4** if offered.
+
+**Unsloth:** we set `UNSLOTH_DISABLE_STATISTICS=1` below so Colab does not hang 120s on Unsloth’s Hugging Face “statistics” fetch (often mis-reported as “HF is down”).""")
 
 add_code("""import os, json
 import torch
 from google.colab import userdata
 
-assert torch.cuda.is_available(), "Use Runtime → Change runtime type → T4 GPU"
+# Before any `import unsloth` in later cells — avoids TimeoutError on HF stats ping
+os.environ.setdefault("UNSLOTH_DISABLE_STATISTICS", "1")
+
+if not torch.cuda.is_available():
+    raise RuntimeError(
+        "No GPU visible to PyTorch. Colab: Runtime → Change runtime type → set "
+        "Hardware accelerator to GPU (T4, L4, A100, …) → Save, then re-run. "
+        "If you are on **CPU** only, this notebook cannot train; connect a GPU session."
+    )
 print(torch.cuda.get_device_name(0), torch.cuda.get_device_properties(0).total_memory / 1e9, "GB VRAM")
 print("torch", torch.__version__, "cuda", torch.version.cuda)
 
@@ -80,10 +105,37 @@ MIN_REWARD_KEEP = 0.25""")
 
 add_md("## Step 3 — Load dataset")
 
-add_code("""from datasets import load_dataset
+add_code("""import json as _json
 import pandas as pd
-
-raw = load_dataset(DATASET_ID, token=HF_TOKEN)
+from datasets import Dataset, DatasetDict, load_dataset
+from huggingface_hub import hf_hub_download
+
+
+def load_parlay_episodes():
+    \"\"\"Prefer `load_dataset`; fall back to raw JSONL if Colab's old `datasets` can't parse `Json` features.\"\"\"
+    try:
+        return load_dataset(DATASET_ID, token=HF_TOKEN)
+    except (ValueError, KeyError) as e:
+        msg = str(e)
+        if "Json" not in msg and "Feature type" not in msg:
+            raise
+        path = hf_hub_download(
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            filename="episodes_v2.jsonl",
+            token=HF_TOKEN,
+        )
+        rows = []
+        with open(path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    rows.append(_json.loads(line))
+        df = pd.DataFrame(rows)
+        return DatasetDict({"train": Dataset.from_pandas(df, preserve_index=False)})
+
+
+raw = load_parlay_episodes()
 df = raw["train"].to_pandas()
 print(len(df), "rows", list(df.columns))
 if "reward" in df.columns:
@@ -137,7 +189,10 @@ eval_data  = Dataset.from_list(formatted[split:])""")
 
 add_md("## Step 5 — Model + LoRA (Unsloth)")
 
-add_code("""from unsloth import FastLanguageModel
+add_code("""import os
+os.environ.setdefault("UNSLOTH_DISABLE_STATISTICS", "1")
+
+from unsloth import FastLanguageModel
 from unsloth.chat_templates import get_chat_template
 
 model, tokenizer = FastLanguageModel.from_pretrained(
@@ -146,6 +201,7 @@ model, tokenizer = FastLanguageModel.from_pretrained(
     dtype=None,
     load_in_4bit=True,
     token=HF_TOKEN,
+    disable_log_stats=True,
 )
 tokenizer = get_chat_template(tokenizer, chat_template="chatml")
 model = FastLanguageModel.get_peft_model(
@@ -187,7 +243,7 @@ args = SFTConfig(
     fp16=not torch.cuda.is_bf16_supported(),
     bf16=torch.cuda.is_bf16_supported(),
     logging_steps=5,
-    evaluation_strategy="epoch",
+    eval_strategy="epoch",
     save_strategy="epoch",
     report_to="none",
     seed=42,