Feat/monday sprint 2 (#19)

* plan sprint

* model config loading

* model config

* llama studio config

* common fix

* lm eval fix

* llama studio config

* llama studio model

* modal fix

* modal fix eval

* fix

* fix config and stuff model switch

* common fix

* server app modal

* server and orgin fix

* Pin torch 2.11 for HF ZeroGPU Space compatibility.

ZeroGPU rejects torch 2.12; supported versions are 2.8–2.11.

Co-authored-by: Cursor <cursoragent@cursor.com>

* finetuning stuff

* fix common and experiment

* readme md

* experiment

* fix experiment

* finetuning stuff

* finetuning

* fix experiment and stuff

* adaptaters + config fix

---------

Co-authored-by: msgencrypted-auto <msgencrypted.auto@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/plans/llama_backend_model_switching_77de87de.plan.md

@@ -0,0 +1,231 @@
+---
+name: Llama backend model switching
+overview: Add the official MiniCPM-V-4.6 GGUF preset from openbmb/MiniCPM-V-4.6-gguf for the llama.cpp / Llama Champion path, then wire a shared runtime model selector so local dev can switch between transformers and llama.cpp backends (and other presets) from Gradio Settings and Studio — not just the Chat debug tab.
+todos:
+  - id: add-gguf-preset
+    content: Add minicpm-v-4.6-gguf preset to models.yaml (openbmb/MiniCPM-V-4.6-gguf) and document in .env.example
+    status: completed
+  - id: runtime-model-state
+    content: Add set_runtime_model_key() and make get_active_model_key() runtime-aware in model_loading.py
+    status: completed
+  - id: classic-ui-sync
+    content: Wire Settings + Chat dropdowns to set_runtime_model_key; reload on change
+    status: completed
+  - id: studio-api-sync
+    content: Add api_set_active_model + studio.js settings dropdown handler; sync debug picker
+    status: completed
+  - id: tests-docs
+    content: Test preset parsing + runtime key override; document local switching in USAGE.md
+    status: completed
+isProject: false
+---
+
+# Llama backend + runtime model switching (local dev)
+
+## What already exists
+
+Your repo already has **two inference backends** behind one factory — no new backend code is required for **text** inference:
+
+```mermaid
+flowchart LR
+  GradioUI[Gradio Classic + Studio]
+  ModelLoading[model_loading.py]
+  Factory[factory.py]
+  LlamaCpp[LlamaCppBackend]
+  Transformers[TransformersBackend]
+  GradioUI --> ModelLoading --> Factory
+  Factory -->|preset.backend=llama_cpp| LlamaCpp
+  Factory -->|preset.backend=transformers| Transformers
+```
+
+- Presets live in [`models.yaml`](models.yaml); backend is chosen **per preset**, not via a separate toggle.
+- Switching transformers → llama.cpp means switching preset, e.g. `minicpm-v-4.6` → `minicpm-v-4.6-gguf` (to be added).
+- [`libs/inference/src/inference/llama_cpp.py`](libs/inference/src/inference/llama_cpp.py) downloads GGUF from Hub and runs `create_chat_completion`.
+- [`ALLOW_MODEL_SWITCH`](libs/inference/src/inference/config.py) gates dropdowns in Settings, Chat, and Studio debug — but **only Chat/Debug actually pass the selected key to inference**.
+
+### Current gap (why switching feels broken)
+
+[`get_active_model_key()`](apps/gradio-space/src/gradio_space/model_loading.py) always returns the **startup** preset from env/`models.yaml`:
+
+```12:13:apps/gradio-space/src/gradio_space/model_loading.py
+def get_active_model_key() -> str:
+    return _app_config.active_model
+```
+
+Lesson slides, ResearchMind, EchoCoach, TeacherVoice, and Studio Research/Slides all call `get_active_model_key()` — so changing the Settings dropdown only updates the status panel, not the model used by those tabs.
+
+---
+
+## Step 1 — Add MiniCPM-V-4.6 GGUF preset (OpenBMB + llama.cpp)
+
+Official GGUF is published at [`openbmb/MiniCPM-V-4.6-gguf`](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf). This is the **quantized llama.cpp build** of the same ~0.8B multimodal model already registered as `minicpm-v-4.6` (transformers). Recommended quant for local dev: **Q4_K_M** (~529 MB).
+
+Add to [`models.yaml`](models.yaml):
+
+```yaml
+  minicpm-v-4.6-gguf:
+    label: MiniCPM-V 4.6 (GGUF / llama.cpp)
+    backend: llama_cpp
+    model_repo: openbmb/MiniCPM-V-4.6-gguf
+    model_file: MiniCPM-V-4.6-Q4_K_M.gguf
+    multimodal: true
+    n_ctx: 8192
+    n_gpu_layers: 0
+```
+
+Pair with the existing transformers preset for A/B comparison:
+
+| Preset key | Backend | Hub source | Use case |
+|------------|---------|------------|----------|
+| `minicpm-v-4.6` | transformers | `openbmb/MiniCPM-V-4.6` | Full multimodal (image/video) via HF processor |
+| `minicpm-v-4.6-gguf` | llama_cpp | `openbmb/MiniCPM-V-4.6-gguf` | Llama Champion / Off-the-Grid; text chat + future image via llama.cpp |
+
+Also update [`.env.example`](.env.example) with a commented dev block:
+
+```bash
+ALLOW_MODEL_SWITCH=true
+ACTIVE_MODEL=minicpm-v-4.6          # transformers default (or minicpm5-1b)
+# switch in UI to minicpm-v-4.6-gguf for llama.cpp
+```
+
+Prefetch locally (optional, speeds first load):
+
+```bash
+uv run python scripts/download_model.py --preset minicpm-v-4.6-gguf
+```
+
+Per the [model card](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf), llama.cpp loads it directly — no custom fork:
+
+```bash
+llama-cli -hf openbmb/MiniCPM-V-4.6-gguf:Q4_K_M
+```
+
+This satisfies the **Llama Champion** badge (llama.cpp runtime) while keeping the **OpenBMB / Tiny Titan** story (same MiniCPM-V 4.6 model family). LoRA/merged lesson presets on MiniCPM5-1B remain **transformers-only**.
+
+### Multimodal caveat (text vs image)
+
+- **Text-only tabs** (Lesson slides, ResearchMind, Chat, EchoCoach) work immediately — `LlamaCppBackend.chat()` passes string messages to `create_chat_completion`.
+- **Image input via llama.cpp** requires OpenAI-style message content arrays (`type: image_url`). Current `LlamaCppBackend.chat()` types messages as `list[dict[str, str]]` and does not forward images. Defer image support to a follow-up unless a tab needs it now; keep `minicpm-v-4.6` (transformers) for full VLM demos.
+
+---
+
+## Step 2 — Shared runtime model state
+
+Extend [`model_loading.py`](apps/gradio-space/src/gradio_space/model_loading.py):
+
+| Function | Behavior |
+|----------|----------|
+| `set_runtime_model_key(key: str) -> str` | Validate key exists; if changed, call `reset_backend()` and clear load cache for old key; return label for UI |
+| `get_active_model_key()` | Return `_runtime_model_key` if set, else `_app_config.active_model` |
+| `reload_model(key)` | Also call `set_runtime_model_key(key)` so reload pins the selection app-wide |
+
+This is a small, centralized change — every tab that already calls `get_active_model_key()` will automatically respect the runtime selection once Settings updates it.
+
+---
+
+## Step 3 — Classic Gradio UI wiring
+
+### Settings panel ([`settings_panel.py`](apps/gradio-space/src/gradio_space/ui/settings_panel.py))
+
+On dropdown `.change`:
+1. Call `set_runtime_model_key(selected_key)`
+2. Update status markdown (existing `model_status`)
+3. Optionally auto-reload weights (or keep explicit "Reload model" button — recommend **reload on change** for dev UX)
+
+Return `model_dropdown` from `build_settings_panel()` (already does) and expose it to [`app.py`](apps/gradio-space/src/gradio_space/app.py) if needed for cross-tab sync.
+
+### Chat tab ([`tabs/chat.py`](apps/gradio-space/src/gradio_space/tabs/chat.py))
+
+When `allow_model_switch` is on:
+- On Chat model dropdown change → `set_runtime_model_key(mkey)` so Chat and Settings stay in sync
+- Default dropdown value = `get_active_model_key()` (runtime-aware)
+
+### App header badge (small UX win)
+
+When `allow_model_switch` is false, keep current read-only badge. When true, show active preset + backend in Settings accordion header so devs always know which backend is live.
+
+---
+
+## Step 4 — Studio UI wiring
+
+In [`api/studio.py`](apps/gradio-space/src/gradio_space/api/studio.py):
+
+- Add `api_set_active_model(model_key: str)` → calls `set_runtime_model_key`, returns updated `model_status`
+- Register as `@server.api(name="set_active_model")`
+- `api_model_choices()` should report `active_model=get_active_model_key()` (runtime-aware)
+- `api_reload_model()` already accepts `model_key`; ensure it calls `set_runtime_model_key` too
+
+In [`static/studio/studio.js`](apps/gradio-space/static/studio/studio.js) `initSettings()`:
+- On `#settings-model-key` change → `callApi("set_active_model", [key])` then refresh status
+- Keep debug chat dropdown in sync with settings dropdown
+
+Studio Research + Slides already delegate to helpers that use `get_active_model_key()` — no per-endpoint `model_key` param needed once runtime state exists.
+
+---
+
+## Step 5 — Dev workflow (how you use it)
+
+```bash
+# .env
+ALLOW_MODEL_SWITCH=true
+ACTIVE_MODEL=minicpm-v-4.6
+```
+
+```bash
+uv sync --all-packages
+uv run --package gradio-space python -m gradio_space.server
+```
+
+| Goal | Action |
+|------|--------|
+| Transformers MiniCPM-V 4.6 (full VLM) | Select `minicpm-v-4.6` in Settings (or leave startup default) |
+| llama.cpp MiniCPM-V 4.6 (Llama track) | Select `minicpm-v-4.6-gguf` — backend switches automatically |
+| Text-only MiniCPM5 | Select `minicpm5-1b` |
+| Fine-tuned lesson LoRA | Select `minicpm5-1b-lesson-lora` (transformers only) |
+| Compare Qwen GGUF baseline | Select `qwen3b-gguf` |
+
+**There is no separate "backend" dropdown** — backend follows the preset. Dropdown labels already include backend hints; optionally prefix choices with `[llama.cpp]` / `[transformers]` in `model_choices()` for clarity.
+
+### Compatibility notes to surface in Settings status
+
+- `minicpm-v-4.6-gguf` is text-ready on all tabs; image/video input needs transformers `minicpm-v-4.6` until llama.cpp multimodal messages are wired
+- LoRA/merged local presets require transformers
+- First llama.cpp load downloads ~529 MB GGUF from Hub (subsequent loads use cache)
+
+---
+
+## Step 6 — Tests and docs
+
+- Extend [`libs/inference/tests/test_config.py`](libs/inference/tests/test_config.py) to assert `minicpm-v-4.6-gguf` parses with `backend=llama_cpp` and `multimodal=true`
+- Add a small unit test for `set_runtime_model_key` / `get_active_model_key` override in gradio-space tests (or inference tests if kept in `model_loading.py`)
+- Add a short "Switching models locally" subsection to [`USAGE.md`](USAGE.md) and [`apps/gradio-space/README.md`](apps/gradio-space/README.md)
+- Update [`TODO.md`](TODO.md) Llama Champion checklist to reference `minicpm-v-4.6-gguf` instead of generic MiniCPM5 GGUF
+
+---
+
+## Architecture after changes
+
+```mermaid
+sequenceDiagram
+  participant Dev as Dev_UI_Settings
+  participant ML as model_loading
+  participant Factory as inference_factory
+  participant Tab as Any_Tab_or_Studio_API
+
+  Dev->>ML: set_runtime_model_key("minicpm-v-4.6-gguf")
+  ML->>Factory: reset_backend()
+  Tab->>ML: get_active_model_key()
+  ML-->>Tab: "minicpm-v-4.6-gguf"
+  Tab->>ML: ensure_model_loaded(key)
+  ML->>Factory: get_backend(key).load()
+  Note over Factory: LlamaCppBackend loads MiniCPM-V-4.6-Q4_K_M.gguf
+```
+
+---
+
+## Out of scope (per your choices)
+
+- Pinning HF Space to Llama GGUF for judges (deployment config only — set `ACTIVE_MODEL=minicpm-v-4.6-gguf` in Space secrets; keep `ALLOW_MODEL_SWITCH=false`)
+- llama.cpp multimodal image message plumbing in `LlamaCppBackend` (defer; transformers preset covers VLM demos)
+- Converting fine-tuned LoRA weights to GGUF
+- Separate backend-only toggle (preset-based switching is simpler and already matches factory design)

.cursor/plans/todo_last_sprint_tracks_b100b17b.plan.md

@@ -0,0 +1,187 @@
+---
+name: TODO Last Sprint Tracks
+overview: "Close remaining hackathon badge gaps after the completed llama backend sprint: publish a gated Well-Tuned adapter via Modal, finish Llama Champion README/TODO hygiene (preset + runtime switching already shipped as minicpm-v-4.6-gguf), and ship Field Notes as in-repo report plus HF blog draft."
+todos:
+  - id: well-tuned-publish
+    content: Run Modal teaching-lora pipeline (smoke → full publish) and verify MSGEncrypted/minicpm5-1b-teaching-lora is public on Hub
+    status: pending
+  - id: gguf-preset
+    content: "DONE via llama_backend plan: minicpm-v-4.6-gguf preset in models.yaml + .env.example + tests"
+    status: completed
+  - id: runtime-switching
+    content: "DONE via llama_backend plan: set_runtime_model_key, Classic Settings + Studio api_set_active_model"
+    status: completed
+  - id: llama-docs
+    content: "Add Llama Champion to README.md badge targets; cross-link USAGE.md switching section (already written)"
+    status: pending
+  - id: llama-space-optional
+    content: "Optional: pin ACTIVE_MODEL=minicpm-v-4.6-gguf on a dev Space or document local-only verify for judges"
+    status: pending
+  - id: field-notes-md
+    content: Write research/docs/field-notes.md covering skill-matrix QLoRA → lm-eval → gate → Hub publish (include teaching-lora results)
+    status: pending
+  - id: hf-blog
+    content: Adapt field-notes.md into HF blog post and link from README when published
+    status: pending
+  - id: readme-scorecard
+    content: Update README badge targets + TODO.md checkboxes; confirm social post URL
+    status: pending
+isProject: false
+---
+
+# TODO.md Last Sprint Tracks Plan (updated)
+
+Target: **6 merit badges + Bonus Quest Champion** per [TODO.md](TODO.md).
+
+**Prerequisite completed:** [llama_backend_model_switching plan](llama_backend_model_switching_77de87de.plan.md) — all todos marked done.
+
+```mermaid
+flowchart LR
+  subgraph done [Already done]
+    OffGrid[Off the Grid]
+    OffBrand[Off Brand]
+    Sharing[Sharing is Caring]
+    LlamaCore["Llama Champion core: minicpm-v-4.6-gguf + runtime switching"]
+  end
+  subgraph sprint [Remaining sprint]
+    WellTuned[Well-Tuned: Modal publish]
+    LlamaDocs["Llama Champion: README + TODO hygiene"]
+    FieldNotes[Field Notes: blog]
+    Hygiene[README scorecard + social]
+  end
+  done --> Bonus[Bonus Quest Champion]
+  WellTuned --> Bonus
+  LlamaDocs --> Bonus
+  FieldNotes --> Bonus
+  Hygiene --> Bonus
+```
+
+**Strategy unchanged:** Main HF Space stays on `ACTIVE_MODEL=minicpm5-1b` (transformers) for the live teacher demo + Well-Tuned LoRA story. Llama Champion is satisfied via **local llama.cpp preset + runtime switching** (already implemented), not a Space switch.
+
+---
+
+## Completed by llama backend sprint (remove from scope)
+
+The original Track 2 assumed `minicpm5-1b-gguf`. The implemented approach uses **`minicpm-v-4.6-gguf`** instead — same OpenBMB / Tiny Titan story, official [`openbmb/MiniCPM-V-4.6-gguf`](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf), and pairs with the existing transformers VLM preset for A/B comparison.
+
+| Deliverable | Status | Where |
+|-------------|--------|-------|
+| GGUF preset | Done | [`models.yaml`](models.yaml) `minicpm-v-4.6-gguf` |
+| `.env.example` dev block | Done | Commented `ALLOW_MODEL_SWITCH` + preset hint |
+| Runtime model switching | Done | [`model_loading.py`](apps/gradio-space/src/gradio_space/model_loading.py) `set_runtime_model_key()` |
+| Classic Settings + Chat sync | Done | [`settings_panel.py`](apps/gradio-space/src/gradio_space/ui/settings_panel.py), [`tabs/chat.py`](apps/gradio-space/src/gradio_space/tabs/chat.py) |
+| Studio API + JS sync | Done | [`api/studio.py`](apps/gradio-space/src/gradio_space/api/studio.py), [`studio.js`](apps/gradio-space/static/studio/studio.js) |
+| Local switching docs | Done | [`USAGE.md`](USAGE.md) "Switching models locally", [`apps/gradio-space/README.md`](apps/gradio-space/README.md) |
+| Tests | Done | [`test_config.py`](libs/inference/tests/test_config.py), [`test_model_loading.py`](apps/gradio-space/tests/test_model_loading.py) |
+| TODO.md preset item | Done | `[x] Add minicpm-v-4.6-gguf preset` |
+
+**Do not add `minicpm5-1b-gguf`** unless you explicitly want a second GGUF preset for the 1B lesson model — the llama sprint chose V4.6 GGUF deliberately (multimodal family parity, smaller download ~529 MB).
+
+---
+
+## Track 1 — Well-Tuned: publish one public adapter (unchanged)
+
+**Status:** Pipeline complete; needs operational GPU run.
+
+**Primary job:** `teaching-lora` → `MSGEncrypted/minicpm5-1b-teaching-lora`
+
+**Run sequence:**
+
+1. Smoke: `modal run research/modal/finetune_app.py --job teaching-lora --max-steps 20 --no-publish`
+2. Full publish: `modal run research/modal/finetune_app.py --job teaching-lora` (or `::publish_only` if artifacts exist)
+3. Verify public Hub repo + model card tags from [`render_model_card`](research/modal/_common.py)
+
+**Optional Space tie-in:**
+
+```bash
+modal volume get slm-finetune teaching-lora ./models/finetuned/minicpm5-1b-lora
+# ACTIVE_MODEL=minicpm5-1b-lesson-lora
+```
+
+---
+
+## Track 2 — Llama Champion: finish docs + badge closure (reduced scope)
+
+**What remains** (README + TODO hygiene only — no new preset or switching code):
+
+1. **README.md** — add **Llama Champion** to Badge targets section:
+   - Preset: `minicpm-v-4.6-gguf` (llama.cpp backend)
+   - Local verify: `ALLOW_MODEL_SWITCH=true`, select preset in Settings — link to [USAGE.md switching section](USAGE.md)
+   - Note: LoRA lesson presets remain transformers-only; main Space stays `minicpm5-1b`
+
+2. **TODO.md** — check off completed items, narrow open ones:
+   - `[x]` Add preset (already done)
+   - `[ ]` Document llama.cpp path in README (USAGE already done; README pending)
+   - `[ ]` "Run Space on llama.cpp" — **optional**: either pin `ACTIVE_MODEL=minicpm-v-4.6-gguf` on a dev Space, or document that local runtime switching satisfies the badge (see llama plan out-of-scope note)
+
+3. **Optional polish:** 30s demo clip showing Settings → `minicpm-v-4.6-gguf` → Chat response on llama.cpp
+
+**Acceptance:** README documents Llama Champion; TODO scorecard `[ ]` → `[x]` for Llama Champion.
+
+---
+
+## Track 3 — Field Notes: in-repo report + HF blog draft (unchanged)
+
+Create [`research/docs/field-notes.md`](research/docs/field-notes.md):
+
+| Section | Content source |
+|---------|----------------|
+| Problem & stack | README + lesson agent narrative |
+| Skill-matrix design | [`experiments.yaml`](research/modal/experiments.yaml) |
+| Pipeline | train → lm-eval → gate → Hub publish |
+| Modal ops | [`research/modal/README.md`](research/modal/README.md) |
+| Results | `teaching-lora` gate output (after Track 1) |
+| Local inference story | Brief mention of llama.cpp switching (completed sprint) |
+| Repro | Modal commands + Hub adapter link |
+
+HF blog: adapt same content (~800–1200 words), link from README.
+
+---
+
+## Track 4 — README + submission hygiene (merged with Track 2)
+
+Update [`README.md`](README.md) Badge targets:
+
+- **Llama Champion** — `minicpm-v-4.6-gguf`, link to USAGE switching docs
+- **Field Notes** — link to `research/docs/field-notes.md` (+ HF blog when live)
+- **Bonus Quest Champion** — all 6 merit badges qualify
+
+Update [`TODO.md`](TODO.md) checkboxes as tracks complete.
+
+**Manual:** confirm social post URL in README; Community Choice share.
+
+---
+
+## Revised execution order
+
+| Step | Type | Est. | Unblocks |
+|------|------|------|----------|
+| 1. Modal `teaching-lora` publish | GPU ops | 1–3 hr | Well-Tuned + Field Notes results |
+| 2. README Llama Champion + badge table | Docs | ~20 min | Llama Champion closure |
+| 3. `research/docs/field-notes.md` | Docs | ~2 hr | Field Notes badge |
+| 4. README/TODO full scorecard | Docs | ~15 min | Submission completeness |
+| 5. HF blog adaptation | Docs | ~1 hr | Judge visibility |
+| 6. Optional Space GGUF pin or demo clip | Ops | ~30 min | Stronger "Run on llama.cpp" checkbox |
+
+**Estimated remaining:** ~3–5 hours (Modal GPU dominates; Llama code work is done).
+
+---
+
+## Out of scope
+
+- `minicpm5-1b-gguf` preset (superseded by `minicpm-v-4.6-gguf` decision)
+- New runtime switching code (done)
+- OpenAI / Nemotron / Thousand Token Wood tracks
+- llama.cpp multimodal image plumbing in `LlamaCppBackend`
+- LoRA → GGUF conversion
+- Model verification pipeline — post-hackathon
+
+---
+
+## Risk mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Gate fails on `teaching-lora` | Try `math-lora`; increase `max_steps`; inspect Volume before re-run |
+| Judges expect Space on llama.cpp | README + optional dev Space with `ACTIVE_MODEL=minicpm-v-4.6-gguf`; local switching demo clip |
+| HF blog time crunch | In-repo `field-notes.md` first |

.env.example

@@ -1,7 +1,7 @@
 # --- Preset selection (models.yaml is the source of truth) ---
 ACTIVE_MODEL=minicpm5-1b
-# Dev: enable dropdown in Gradio. Space: leave false to pin one model for visitors.
-ALLOW_MODEL_SWITCH=false
+# Defaults to true when unset (models.yaml). Space: set false to pin one model for visitors.
+# ALLOW_MODEL_SWITCH=false
 # MODEL_PRESETS_PATH=./models.yaml
 
 # --- Agent outputs ---
@@ -24,7 +24,13 @@ ALLOW_MODEL_SWITCH=false
 # MODEL_ID=openbmb/MiniCPM5-1B
 # TRUST_REMOTE_CODE=true
 
+# --- Local dev: switch backends/models in Gradio Settings (Classic + Studio) ---
+# ALLOW_MODEL_SWITCH=true
+# ACTIVE_MODEL=minicpm-v-4.6          # transformers default (or minicpm5-1b)
+# switch in UI to minicpm-v-4.6-gguf for llama.cpp / Llama Champion track
+
 # --- llama.cpp presets (optional) ---
+# ACTIVE_MODEL=minicpm-v-4.6-gguf
 # ACTIVE_MODEL=qwen3b-gguf
 # INFERENCE_BACKEND=llama_cpp
 # MODEL_REPO=Qwen/Qwen2.5-3B-Instruct-GGUF

README.md

@@ -31,6 +31,8 @@ See **[USAGE.md](USAGE.md)** for local run, Gradio SDK / ZeroGPU Space deploymen
 
 **Demo video:** [https://www.youtube.com/watch?v=bwtOiZvJ-7k](https://www.youtube.com/watch?v=bwtOiZvJ-7k)
 
+**X post:** [https://x.com/MSG_Encrypted/status/2066570320861921748](https://x.com/MSG_Encrypted/status/2066570320861921748)
+
 ## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/)
@@ -80,6 +82,38 @@ modal run research/modal/server_app.py --pipeline                   # full sweep
 
 Pull a passing adapter into the Space: `modal volume get slm-finetune math-lora ./models/finetuned/minicpm5-1b-lora`, then set `ACTIVE_MODEL=minicpm5-1b-lesson-lora`.
 
+### Llama track (Llama Champion + Off-the-Grid)
+
+The same OpenBMB **MiniCPM-V 4.6** model runs on **llama.cpp** via the [`minicpm-v-4.6-gguf`](models.yaml) preset — GGUF weights from [`openbmb/MiniCPM-V-4.6-gguf`](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf) (~529 MB Q4_K_M). No cloud LLM API; inference stays fully local through [`libs/inference/src/inference/llama_cpp.py`](libs/inference/src/inference/llama_cpp.py).
+
+| Preset | Backend | Use case |
+| ------ | ------- | -------- |
+| `minicpm-v-4.6` | transformers | Full VLM (image/video) via Hugging Face |
+| `minicpm-v-4.6-gguf` | llama.cpp | **Llama Champion** badge; text on all tabs today |
+
+**Space (judges):** pin the GGUF preset — no runtime switching for visitors.
+
+```bash
+ACTIVE_MODEL=minicpm-v-4.6-gguf
+ALLOW_MODEL_SWITCH=false
+```
+
+**Local dev:** switch backends at runtime without restarting.
+
+```bash
+ALLOW_MODEL_SWITCH=true
+ACTIVE_MODEL=minicpm-v-4.6          # transformers startup default
+# Settings or Chat → select minicpm-v-4.6-gguf for llama.cpp
+```
+
+Prefetch weights (optional):
+
+```bash
+uv run python scripts/download_model.py --preset minicpm-v-4.6-gguf
+```
+
+See [USAGE.md](USAGE.md) (section *Switching models locally*) for Classic and Studio UI details.
+
 ## How it works
 
 1. **Skill** — `skills/education-pptx/SKILL.md` (Hermes / agentskills.io format)
@@ -109,7 +143,8 @@ Optional research tooling (not required for the Space): see [research/USAGE.md](
 
 | Variable | Default | Description |
 | -------- | ------- | ----------- |
-| `ACTIVE_MODEL` | `minicpm5-1b` | Preset key from `models.yaml` |
+| `ACTIVE_MODEL` | `minicpm5-1b` | Preset key from `models.yaml` (use `minicpm-v-4.6-gguf` for Llama track) |
+| `ALLOW_MODEL_SWITCH` | `false` | Set `true` locally to switch presets in Settings / Chat |
 | `AGENT_OUTPUTS_DIR` | `/tmp/agent_outputs` | Generated `.pptx` files |
 | `AGENT_TRACES_DIR` | `outputs/traces` | Agent trace JSON |
 | `SKILLS_DIR` | `./skills` | Skill definitions root |
@@ -124,7 +159,7 @@ See [`.env.example`](.env.example) and [`models.yaml`](models.yaml) for model pr
 1. Create a Space under [build-small-hackathon](https://huggingface.co/build-small-hackathon) with **Gradio** SDK (Blank template).
 2. Link this repository — HF builds from root `app.py` + `requirements.txt` (README YAML above).
 3. Hardware: **ZeroGPU** for burst GPU inference, or **GPU basic** for always-on GPU.
-4. Set `ACTIVE_MODEL=minicpm5-1b`, `ALLOW_MODEL_SWITCH=false`, `RESEARCHMIND_DATA_DIR=/tmp/researchmind`.
+4. Set `ACTIVE_MODEL=minicpm5-1b` (or `minicpm-v-4.6-gguf` for [Llama track](#llama-track-llama-champion--off-the-grid)), `ALLOW_MODEL_SWITCH=false`, `RESEARCHMIND_DATA_DIR=/tmp/researchmind`.
 
 A root `Dockerfile` is kept for a later **Docker SDK** deploy (flip README to `sdk: docker`). See [USAGE.md](USAGE.md).
 
@@ -136,10 +171,11 @@ A root `Dockerfile` is kept for a later **Docker SDK** deploy (flip README to `s
 | **Off Brand** | Custom Studio UI at `/` (Gradio 6 Server mode, not default Gradio chrome) |
 | **Modal** (partner) | GPU `train → eval → gate → publish` on [Modal](https://modal.com) — [`research/modal/`](research/modal/) |
 | **Well-Tuned** (finetuning) | Skill-matrix QLoRA adapters on MiniCPM5-1B, lm-eval gates, Hub publish |
+| **Llama Champion** | `minicpm-v-4.6-gguf` on llama.cpp — same OpenBMB VLM family, local GGUF inference |
 
 - Space live under build-small-hackathon
 - Demo video: [YouTube](https://www.youtube.com/watch?v=bwtOiZvJ-7k) — real user enters topic → download `.pptx` → show agent trace
-- Social post published
+- Social post published: [X](https://x.com/MSG_Encrypted/status/2066570320861921748)
 - Submission by **June 15, 2026**
 
 ### Badge targets
@@ -149,6 +185,7 @@ A root `Dockerfile` is kept for a later **Docker SDK** deploy (flip README to `s
 - **OpenBMB** — `openbmb/MiniCPM5-1B`
 - **Sharing is Caring** — upload traces with `scripts/upload_trace.py`
 - **Off-the-Grid** — local inference only (no cloud LLM API)
+- **Llama Champion** — llama.cpp backend with [`openbmb/MiniCPM-V-4.6-gguf`](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf); see [Llama track](#llama-track-llama-champion--off-the-grid)
 - **Well-Tuned** — per-skill QLoRA adapters trained + gated + published via the [Modal + Fine-tuning track](#modal--fine-tuning-track-well-tuned)
 - **Modal** — same pipeline; see [`research/modal/README.md`](research/modal/README.md)
 

TODO.md

@@ -15,8 +15,8 @@ below is parked for follow-up PRs.
 
 ## 🦙 Llama Champion badge (cheap, high value)
 - [ ] Run the Space on the **llama.cpp / GGUF** backend (`libs/inference/src/inference/llama_cpp.py`).
-- [ ] Confirm MiniCPM5-1B has a GGUF (or convert/quantize one) — keep OpenBMB story intact.
-- [ ] Document the llama.cpp path in README + Space (which `ACTIVE_MODEL` preset).
+- [x] Add `minicpm-v-4.6-gguf` preset (`openbmb/MiniCPM-V-4.6-gguf`) — OpenBMB multimodal on llama.cpp.
+- [ ] Document the llama.cpp path in README + Space (`ACTIVE_MODEL=minicpm-v-4.6-gguf`).
 
 ## 📓 Field Notes badge (cheapest miss — no blog exists yet)
 - [ ] Write a blog post / report on the fine-tuning + Modal pipeline:

USAGE.md

@@ -58,6 +58,37 @@ The header in Classic includes a link back to Studio UI.
 
 The model loads on the **first Generate** (Lesson slides) or chat message. Agent traces are written to `outputs/traces/`. After code changes, restart the process to pick up updates.
 
+### Switching models locally (transformers ↔ llama.cpp)
+
+For local dev you can switch presets at runtime without restarting:
+
+```bash
+# .env
+ALLOW_MODEL_SWITCH=true
+ACTIVE_MODEL=minicpm-v-4.6          # startup default (transformers)
+```
+
+| UI | Where to switch |
+|----|-----------------|
+| **Classic** (`/classic`) | **Settings** accordion → Model preset dropdown (reloads on change) |
+| **Classic** Chat tab | Model preset dropdown (syncs app-wide) |
+| **Studio** (`/`) | Settings drawer → Model preset; Debug tab has the same list |
+
+| Goal | Preset key |
+|------|------------|
+| MiniCPM-V 4.6 transformers (full VLM) | `minicpm-v-4.6` |
+| MiniCPM-V 4.6 llama.cpp / Llama Champion | `minicpm-v-4.6-gguf` |
+| MiniCPM5 1B text | `minicpm5-1b` |
+| Lesson LoRA (transformers only) | `minicpm5-1b-lesson-lora` |
+
+Prefetch the GGUF weights (optional):
+
+```bash
+uv run python scripts/download_model.py --preset minicpm-v-4.6-gguf
+```
+
+On Hugging Face Space, keep `ALLOW_MODEL_SWITCH=false` and pin one preset via `ACTIVE_MODEL`.
+
 ### Lesson slides — research sources
 
 The **Lesson slides** tab can ground outlines on external sources before building the deck:

apps/gradio-space/README.md

@@ -41,10 +41,20 @@ This package uses **Gradio 6 Server mode** (`gradio.Server`):
 
 **Settings & debug**
 
-- `model_status`, `model_choices`, `reload_model`
+- `model_status`, `model_choices`, `set_active_model`, `reload_model`
 - `debug_chat`
 - `save_upload`
 
+### Switching models locally
+
+Set `ALLOW_MODEL_SWITCH=true` in `.env` (see [USAGE.md](../../USAGE.md)). The Settings drawer and Classic **Settings** accordion share one runtime preset — changing it reloads weights and applies to Lesson slides, Research, and voice tabs (not just Chat debug).
+
+| Preset | Backend |
+|--------|---------|
+| `minicpm-v-4.6` | transformers (full VLM) |
+| `minicpm-v-4.6-gguf` | llama.cpp (Llama Champion track) |
+| `minicpm5-1b` | transformers |
+
 ## Demo script (judges) — Language lessons + Cohere stack
 
 **Badge line:** Cohere Labs — Transcribe + Tiny Aya on one local Language lessons page.

apps/gradio-space/src/gradio_space/api/studio.py

@@ -26,6 +26,7 @@ from gradio_space.model_loading import (
     get_active_model_key,
     model_status,
     reload_model,
+    select_and_reload_model,
 )
 from gradio_space.research_helpers import (
     list_session_choices,
@@ -873,7 +874,8 @@ def api_model_status() -> dict[str, Any]:
 
 
 def api_model_choices() -> dict[str, Any]:
-    active = _app_config.active
+    key = get_active_model_key()
+    active = _app_config.get_model(key)
     allow_switch = bool(
         _app_config.allow_model_switch and len(_app_config.models) > 1
     )
@@ -881,7 +883,7 @@ def api_model_choices() -> dict[str, Any]:
     if allow_switch:
         choices = [{"key": k, "label": label} for label, k in _app_config.model_choices()]
     return ok(
-        active_model=_app_config.active_model,
+        active_model=key,
         active_label=active.label,
         active_backend=active.backend,
         allow_model_switch=allow_switch,
@@ -891,6 +893,17 @@ def api_model_choices() -> dict[str, Any]:
     )
 
 
+def api_set_active_model(model_key: str = "") -> dict[str, Any]:
+    key = (model_key or "").strip() or get_active_model_key()
+    try:
+        status_md = select_and_reload_model(key)
+    except KeyError as exc:
+        return err(str(exc), model_key=key)
+    if status_md.lower().startswith("error") or "failed" in status_md.lower():
+        return err(status_md, status_markdown=status_md, model_key=key)
+    return ok(status_markdown=status_md, model_key=key)
+
+
 def api_reload_model(model_key: str = "") -> dict[str, Any]:
     key = (model_key or "").strip() or get_active_model_key()
     status_md = reload_model(key)
@@ -1211,6 +1224,10 @@ def register_studio_apis(server: gr.Server) -> None:
     def _model_choices() -> dict[str, Any]:
         return api_model_choices()
 
+    @server.api(name="set_active_model")
+    def _set_active_model(model_key: str = "") -> dict[str, Any]:
+        return api_set_active_model(model_key)
+
     @server.api(name="reload_model")
     def _reload_model(model_key: str = "") -> dict[str, Any]:
         return api_reload_model(model_key)

apps/gradio-space/src/gradio_space/model_loading.py

@@ -4,13 +4,29 @@ from inference.factory import get_backend, reset_backend
 from inference.response_clean import strip_reasoning_output
 
 _app_config = get_app_config()
+_runtime_model_key: str | None = None
 _current_model_key: str | None = None
 _load_state: dict[str, bool] = {}
 _load_errors: dict[str, str] = {}
 
 
 def get_active_model_key() -> str:
-    return _app_config.active_model
+    return _runtime_model_key or _app_config.active_model
+
+
+def set_runtime_model_key(key: str) -> str:
+    """Pin the active preset for all tabs until process restart."""
+    global _runtime_model_key, _current_model_key
+
+    model = get_model_config(key)
+    previous = get_active_model_key()
+    if key != previous:
+        reset_backend()
+        _current_model_key = None
+        _load_state.pop(previous, None)
+        _load_errors.pop(previous, None)
+    _runtime_model_key = key
+    return model.label
 
 
 def ensure_model_loaded(model_key: str) -> str | None:
@@ -53,7 +69,7 @@ def runtime_device_hint(model_key: str) -> str:
 
 
 def warmup(model_key: str | None = None) -> str:
-    key = model_key or _app_config.active_model
+    key = model_key or get_active_model_key()
     model = get_model_config(key)
 
     if _load_state.get(key):
@@ -80,7 +96,8 @@ def reload_model(model_key: str) -> str:
     """Clear cached backend and reload weights for settings panel."""
     global _current_model_key
 
-    key = model_key or _app_config.active_model
+    key = model_key or get_active_model_key()
+    set_runtime_model_key(key)
     reset_backend()
     _current_model_key = None
     _load_state.pop(key, None)
@@ -91,6 +108,11 @@ def reload_model(model_key: str) -> str:
     return warmup(key)
 
 
+def select_and_reload_model(model_key: str) -> str:
+    """Switch runtime preset and load weights (Settings dropdown)."""
+    return reload_model(model_key)
+
+
 def preload_active_model() -> str:
     """Load the active preset at startup so the first request is fast."""
     key = get_active_model_key()
@@ -106,7 +128,16 @@ def preload_active_model() -> str:
 
 def model_status(model_key: str) -> str:
     model = get_model_config(model_key)
-    return f"**{model.label}**\n\n- Backend: `{model.backend}`\n- {warmup(model_key)}"
+    notes = ""
+    if model.backend == "llama_cpp" and model.multimodal:
+        notes = (
+            "\n- Note: text-only on llama.cpp; use transformers preset for image/video input."
+        )
+    return (
+        f"**{model.label}**\n\n"
+        f"- Backend: `{model.backend}`\n"
+        f"- {warmup(model_key)}{notes}"
+    )
 
 
 def _history_to_messages(history: list) -> list[dict[str, str]]:

apps/gradio-space/src/gradio_space/server.py

@@ -23,7 +23,7 @@ from gradio_space.ui.theme import get_theme, load_css
 _PKG_ROOT = Path(__file__).resolve().parent
 _APP_ROOT = _PKG_ROOT.parents[1]
 _STATIC_DIR = _APP_ROOT / "static" / "studio"
-_STUDIO_ASSET_VERSION = "20260615"
+_STUDIO_ASSET_VERSION = "20260615b"
 _STUDIO_INDEX_HTML = _STATIC_DIR / "index.html"
 
 

apps/gradio-space/src/gradio_space/tabs/chat.py

@@ -1,5 +1,6 @@
 import gradio as gr
 
+from gradio_space.model_loading import get_active_model_key, set_runtime_model_key
 from gradio_space.research_helpers import (
     list_session_choices,
     rag_aware_chat,
@@ -29,7 +30,7 @@ def build_chat_tab(workspace: WorkspaceWidgets) -> None:
         "Plain chat or corpus-grounded answers — traces appear in Advanced when RAG is on."
     )
 
-    model_key = _app_config.active_model
+    model_key = get_active_model_key()
 
     with gr.Group():
         gr.Markdown("#### RAG scope (override workspace defaults)")
@@ -57,11 +58,17 @@ def build_chat_tab(workspace: WorkspaceWidgets) -> None:
     if _app_config.allow_model_switch and len(_app_config.models) > 1:
         model_dropdown = gr.Dropdown(
             choices=_app_config.model_choices(),
-            value=_app_config.active_model,
+            value=get_active_model_key(),
             label="Model preset (debug override)",
         )
 
+        def _on_model_change(mkey: str) -> None:
+            set_runtime_model_key(mkey)
+
+        model_dropdown.change(fn=_on_model_change, inputs=model_dropdown)
+
         def _chat(message, history, mkey, use_rag_flag, sid, docs, ws_sid, ws_docs):
+            set_runtime_model_key(mkey)
             sid = resolve_session(sid, ws_sid)
             docs = resolve_doc_ids(docs, ws_docs)
             reply, trace_json, trace_summary = rag_aware_chat(
@@ -83,7 +90,7 @@ def build_chat_tab(workspace: WorkspaceWidgets) -> None:
             examples=[
                 [
                     "What do my ingested sources say about AI agents?",
-                    _app_config.active_model,
+                    get_active_model_key(),
                     True,
                     "",
                     [],
@@ -92,7 +99,7 @@ def build_chat_tab(workspace: WorkspaceWidgets) -> None:
                 ],
                 [
                     "Hello! What can you help me with?",
-                    _app_config.active_model,
+                    get_active_model_key(),
                     False,
                     "",
                     [],

apps/gradio-space/src/gradio_space/ui/settings_panel.py

@@ -3,7 +3,12 @@ from __future__ import annotations
 import gradio as gr
 
 from echocoach.config import get_echo_coach_config
-from gradio_space.model_loading import model_status, reload_model
+from gradio_space.model_loading import (
+    get_active_model_key,
+    model_status,
+    reload_model,
+    select_and_reload_model,
+)
 from inference.config import get_app_config
 from researchmind.config import get_config as get_research_config
 
@@ -39,11 +44,17 @@ def _paths_summary() -> str:
 def build_settings_panel() -> tuple[gr.Dropdown | None, gr.Markdown, gr.Button]:
     """Build settings accordion contents. Returns (model_dropdown or None, status_md, reload_btn)."""
     model_dropdown: gr.Dropdown | None = None
+    active_key = get_active_model_key()
 
     if _app_config.allow_model_switch and len(_app_config.models) > 1:
+        active = _app_config.get_model(active_key)
+        gr.Markdown(
+            f"**Runtime model:** `{active.key}` — {active.label}  \n"
+            f"**Backend:** `{active.backend}`"
+        )
         model_dropdown = gr.Dropdown(
             choices=_app_config.model_choices(),
-            value=_app_config.active_model,
+            value=active_key,
             label="Model preset",
         )
     else:
@@ -53,7 +64,7 @@ def build_settings_panel() -> tuple[gr.Dropdown | None, gr.Markdown, gr.Button]:
             f"**Backend:** `{active.backend}`"
         )
 
-    status_md = gr.Markdown(value=model_status(_app_config.active_model))
+    status_md = gr.Markdown(value=model_status(active_key))
     gr.Markdown("#### Voice stack")
     gr.Markdown(_voice_stack_summary())
     with gr.Accordion("Paths & files", open=False):
@@ -62,13 +73,17 @@ def build_settings_panel() -> tuple[gr.Dropdown | None, gr.Markdown, gr.Button]:
     reload_btn = gr.Button("Reload model", variant="secondary", size="sm")
 
     if model_dropdown is not None:
-        model_dropdown.change(fn=model_status, inputs=model_dropdown, outputs=status_md)
+        model_dropdown.change(
+            fn=select_and_reload_model,
+            inputs=model_dropdown,
+            outputs=status_md,
+        )
 
     if model_dropdown is not None:
         reload_btn.click(fn=reload_model, inputs=[model_dropdown], outputs=status_md)
     else:
         reload_btn.click(
-            fn=lambda: reload_model(_app_config.active_model),
+            fn=lambda: reload_model(get_active_model_key()),
             outputs=status_md,
         )
 

apps/gradio-space/static/studio/studio.js

@@ -26,9 +26,21 @@ function toggleTheme() {
 applyTheme(getPreferredTheme());
 
 function appOrigin() {
-  const { protocol, hostname } = window.location;
-  const secureProto = protocol === "http:" ? "https:" : protocol;
-  return `${secureProto}//${hostname}`;
+  const { protocol, hostname, port } = window.location;
+  if (protocol === "https:") {
+    return window.location.origin;
+  }
+  const isLocal =
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "[::1]" ||
+    hostname === "0.0.0.0";
+  if (isLocal) {
+    return window.location.origin;
+  }
+  // HF Spaces: TLS terminates at the edge; Gradio client must use https.
+  const portSuffix = port ? `:${port}` : "";
+  return `https://${hostname}${portSuffix}`;
 }
 
 const SLIDE_PIPELINE_STEPS = [
@@ -1125,6 +1137,15 @@ async function initVoicePresets() {
   return initLanguageLessons();
 }
 
+async function selectActiveModel(key) {
+  const data = await callApi("set_active_model", [key]);
+  $("#settings-status").innerHTML = renderMarkdownLite(data.status_markdown || "");
+  const fresh = await callApi("model_choices", []);
+  state.modelChoices = fresh;
+  $("#settings-active-model").textContent = `${fresh.active_label} (${fresh.active_backend})`;
+  return data;
+}
+
 async function initSettings() {
   const data = await callApi("model_choices", []);
   state.modelChoices = data;
@@ -1147,10 +1168,20 @@ async function initSettings() {
     if (select) {
       select.innerHTML = options;
       select.value = data.active_model;
+      select.onchange = () => {
+        const key = select.value;
+        if (debugSelect) debugSelect.value = key;
+        selectActiveModel(key).catch(() => {});
+      };
     }
     if (debugSelect) {
       debugSelect.innerHTML = options;
       debugSelect.value = data.active_model;
+      debugSelect.onchange = () => {
+        const key = debugSelect.value;
+        if (select) select.value = key;
+        selectActiveModel(key).catch(() => {});
+      };
     }
   }
 }

apps/gradio-space/tests/test_model_loading.py

@@ -0,0 +1,48 @@
+import importlib
+
+import pytest
+
+
+@pytest.fixture
+def model_loading_module(monkeypatch, tmp_path):
+    presets = tmp_path / "models.yaml"
+    presets.write_text(
+        """
+defaults:
+  active_model: alpha
+  allow_model_switch: true
+models:
+  alpha:
+    label: Alpha
+    backend: transformers
+    model_id: openbmb/MiniCPM5-1B
+  beta:
+    label: Beta GGUF
+    backend: llama_cpp
+    model_repo: openbmb/MiniCPM-V-4.6-gguf
+    model_file: MiniCPM-V-4.6-Q4_K_M.gguf
+    multimodal: true
+"""
+    )
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("ACTIVE_MODEL", raising=False)
+
+    import inference.config as inference_config
+    import gradio_space.model_loading as model_loading
+
+    importlib.reload(inference_config)
+    importlib.reload(model_loading)
+    return model_loading
+
+
+def test_runtime_model_key_override(model_loading_module):
+    ml = model_loading_module
+    assert ml.get_active_model_key() == "alpha"
+    ml.set_runtime_model_key("beta")
+    assert ml.get_active_model_key() == "beta"
+
+
+def test_set_runtime_model_key_unknown_raises(model_loading_module):
+    ml = model_loading_module
+    with pytest.raises(KeyError):
+        ml.set_runtime_model_key("missing")

libs/inference/src/inference/config.py

@@ -74,7 +74,7 @@ class AppConfig:
 
     active_model: str
     models: dict[str, ModelConfig]
-    allow_model_switch: bool = False
+    allow_model_switch: bool = True
     model_cache_dir: str | None = None
     presets_path: Path | None = None
 
@@ -238,7 +238,7 @@ def load_app_config() -> AppConfig:
 
     allow_model_switch = os.environ.get("ALLOW_MODEL_SWITCH")
     if allow_model_switch is None:
-        allow_switch = bool(defaults.get("allow_model_switch", False))
+        allow_switch = bool(defaults.get("allow_model_switch", True))
     else:
         allow_switch = allow_model_switch.lower() in {"1", "true", "yes"}
 

libs/inference/src/inference/transformers.py

@@ -72,16 +72,26 @@ class TransformersBackend:
             )
 
         if self._config.adapter_path:
+            import re
             from pathlib import Path
 
             from peft import PeftModel
 
-            adapter = Path(self._config.adapter_path)
-            if not adapter.is_dir():
+            adapter = self._config.adapter_path
+            adapter_dir = Path(adapter)
+            if adapter_dir.is_dir():
+                # Local adapter (e.g. pulled from the Modal Volume).
+                adapter_src = str(adapter_dir)
+            elif re.fullmatch(r"[\w.-]+/[\w.-]+", adapter):
+                # Hugging Face Hub repo id (e.g. the Modal-published adapter) —
+                # PeftModel fetches it remotely; no manual pull required.
+                adapter_src = adapter
+            else:
                 raise FileNotFoundError(
-                    f"LoRA adapter not found for preset {self._config.key!r}: {adapter}"
+                    f"LoRA adapter not found for preset {self._config.key!r}: "
+                    f"{adapter} (expected a local dir or a Hub repo id 'org/name')"
                 )
-            self._model = PeftModel.from_pretrained(self._model, str(adapter))
+            self._model = PeftModel.from_pretrained(self._model, adapter_src)
 
         if plan.device == "cpu":
             assert self._model is not None

libs/inference/tests/test_config.py

@@ -30,6 +30,51 @@ models:
     assert config.get_model("demo").model_repo == "org/model-GGUF"
 
 
+def test_allow_model_switch_defaults_true_without_env(tmp_path, monkeypatch):
+    presets = tmp_path / "models.yaml"
+    presets.write_text(
+        """
+defaults:
+  active_model: demo
+models:
+  demo:
+    label: Demo preset
+    backend: llama_cpp
+    model_repo: org/model-GGUF
+    model_file: demo.gguf
+"""
+    )
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("ALLOW_MODEL_SWITCH", raising=False)
+
+    config = load_app_config()
+
+    assert config.allow_model_switch is True
+
+
+def test_allow_model_switch_env_false_overrides(tmp_path, monkeypatch):
+    presets = tmp_path / "models.yaml"
+    presets.write_text(
+        """
+defaults:
+  active_model: demo
+  allow_model_switch: true
+models:
+  demo:
+    label: Demo preset
+    backend: llama_cpp
+    model_repo: org/model-GGUF
+    model_file: demo.gguf
+"""
+    )
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("ALLOW_MODEL_SWITCH", "false")
+
+    config = load_app_config()
+
+    assert config.allow_model_switch is False
+
+
 def test_legacy_env_overrides_active_preset(tmp_path, monkeypatch):
     presets = tmp_path / "models.yaml"
     presets.write_text(
@@ -54,6 +99,24 @@ models:
     assert model.model_file == "override.gguf"
 
 
+def test_minicpm_v_gguf_preset_from_repo(monkeypatch):
+    repo_root = Path(__file__).resolve().parents[3]
+    models_yaml = repo_root / "models.yaml"
+    if not models_yaml.is_file():
+        pytest.skip("repo models.yaml not found")
+
+    monkeypatch.chdir(repo_root)
+    monkeypatch.delenv("ACTIVE_MODEL", raising=False)
+    monkeypatch.delenv("ALLOW_MODEL_SWITCH", raising=False)
+
+    model = load_app_config().get_model("minicpm-v-4.6-gguf")
+
+    assert model.backend == "llama_cpp"
+    assert model.multimodal is True
+    assert model.model_repo == "openbmb/MiniCPM-V-4.6-gguf"
+    assert model.model_file == "MiniCPM-V-4.6-Q4_K_M.gguf"
+
+
 def test_resolve_relative_model_path(tmp_path, monkeypatch):
     local_dir = tmp_path / "gemma_merged_model"
     local_dir.mkdir()

models.yaml

@@ -5,9 +5,8 @@ defaults:
   # active_model: minicpm-v-4.6
   active_model: minicpm5-1b
 
-  # Dev: set ALLOW_MODEL_SWITCH=true in .env to expose a dropdown in Gradio.
-  # Space: keep false so visitors use one pinned model.
-  allow_model_switch: false
+  # Default true for local dev (dropdown in Gradio). Space: set ALLOW_MODEL_SWITCH=false.
+  allow_model_switch: true
 
 models:
   minicpm-v-4.6:
@@ -17,6 +16,15 @@ models:
     trust_remote_code: true
     multimodal: true
 
+  minicpm-v-4.6-gguf:
+    label: MiniCPM-V 4.6 (GGUF / llama.cpp)
+    backend: llama_cpp
+    model_repo: openbmb/MiniCPM-V-4.6-gguf
+    model_file: MiniCPM-V-4.6-Q4_K_M.gguf
+    multimodal: true
+    n_ctx: 8192
+    n_gpu_layers: 0
+
   qwen3b-gguf:
     label: Qwen 2.5 3B Instruct (GGUF)
     backend: llama_cpp
@@ -68,6 +76,24 @@ models:
     model_id: ./models/finetuned/minicpm5-1b-lora-merged
     trust_remote_code: true
 
+  # Well-Tuned track: base MiniCPM5-1B + a Modal-published LoRA adapter pulled
+  # straight from the Hub (no local files needed). These point at the repos the
+  # finetune pipeline publishes once a job clears its lm-eval gate
+  # (research/modal/experiments.yaml -> publish.hub_repo).
+  minicpm5-1b-teaching-hub:
+    label: MiniCPM5 1B teaching LoRA (Hub, fine-tuned)
+    backend: transformers
+    model_id: openbmb/MiniCPM5-1B
+    adapter_path: MSGEncrypted/minicpm5-1b-teaching-lora
+    trust_remote_code: true
+
+  minicpm5-1b-math-hub:
+    label: MiniCPM5 1B math LoRA (Hub, fine-tuned)
+    backend: transformers
+    model_id: openbmb/MiniCPM5-1B
+    adapter_path: MSGEncrypted/minicpm5-1b-math-lora
+    trust_remote_code: true
+
   tiny-aya-global:
     label: Tiny Aya Global 3.3B (multilingual coach)
     backend: transformers

requirements.txt

@@ -3,8 +3,9 @@
 
 # Pinned runtime deps (do not pin gradio, spaces, or huggingface_hub — HF preinstalls them)
 accelerate==1.13.0
-torch==2.12.0
-torchvision==0.27.0
+# ZeroGPU supports torch 2.8–2.11 only (not 2.12).
+torch==2.11.0
+torchvision==0.26.0
 transformers==5.10.2
 peft==0.19.1
 # llama-cpp-python omitted — compiles from source on HF (10+ min / timeout).

research/evals/configs/lm_eval_code.yaml

@@ -8,7 +8,11 @@ claim: Better code generation
 tasks:
   - humaneval
   - mbpp
+  - hellaswag   # general-capability guard (catch regression from skill tuning)
+  - piqa        # general-capability guard
 
+# humaneval/mbpp execute model-generated code; opt in explicitly.
+confirm_run_unsafe_code: true
 num_fewshot: 0
 limit: 50
 seed: 42

research/evals/configs/lm_eval_math.yaml

@@ -7,6 +7,8 @@ claim: Better math reasoning
 tasks:
   - gsm8k
   - arc_challenge
+  - hellaswag   # general-capability guard (catch regression from skill tuning)
+  - piqa        # general-capability guard
 
 num_fewshot: 5
 limit: 100

research/evals/src/slm_evals/run_lm_eval.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 import argparse
 import datetime
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -52,6 +53,17 @@ _METRIC_PRIORITY = (
     "bleu,none",
 )
 
+# lm-eval tasks that execute model-generated code (pass@k). lm-eval refuses to
+# run them unless confirm_run_unsafe_code=True, and the HF `evaluate` code_eval
+# metric additionally requires HF_ALLOW_CODE_EVAL=1.
+_CODE_EXEC_TASK_PREFIXES = ("humaneval", "mbpp")
+
+
+def _requires_code_execution(tasks: list[str], override: bool | None) -> bool:
+    if override is not None:
+        return bool(override)
+    return any(str(t).lower().startswith(_CODE_EXEC_TASK_PREFIXES) for t in tasks)
+
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
@@ -347,6 +359,19 @@ def main() -> int:
 
     _ensure_lm_eval_models_registered()
 
+    confirm_unsafe_code = _requires_code_execution(
+        cfg["tasks"], cfg.get("confirm_run_unsafe_code")
+    )
+    if confirm_unsafe_code:
+        # Required by the HF `evaluate` code_eval metric to compute pass@k.
+        os.environ.setdefault("HF_ALLOW_CODE_EVAL", "1")
+        print(
+            "Enabling code execution for tasks "
+            f"{[t for t in cfg['tasks'] if str(t).lower().startswith(_CODE_EXEC_TASK_PREFIXES)]} "
+            "(confirm_run_unsafe_code=True, HF_ALLOW_CODE_EVAL=1)",
+            file=sys.stderr,
+        )
+
     seed = int(cfg.get("seed", 42))
     model_args = dict(spec.model_args)
     eval_device = cfg.get("device")
@@ -367,6 +392,7 @@ def main() -> int:
         numpy_random_seed=seed,
         torch_random_seed=seed,
         fewshot_random_seed=seed,
+        confirm_run_unsafe_code=confirm_unsafe_code,
         log_samples=False,
     )
 

research/finetune.py

@@ -92,7 +92,6 @@ from datasets import load_dataset
 from transformers import (
     AutoModelForCausalLM,
     AutoTokenizer,
-    DataCollatorForLanguageModeling,
     Trainer,
     TrainingArguments,
 )
@@ -247,12 +246,36 @@ def parse_args():
         else None,
         help="Cap examples after loading (useful for Hub smoke tests)",
     )
+    p.add_argument(
+        "--mix-json",
+        type=str,
+        default=os.environ.get("FINETUNE_MIX_JSON"),
+        help=(
+            "JSON list of dataset source specs to mix/replay; overrides "
+            "--dataset/--format. Each spec: "
+            '{"dataset":..,"format":..,"columns":{..},"dataset_config":..,'
+            '"dataset_split":..,"max_samples":..,"max_len":..,"weight":..}'
+        ),
+    )
     p.add_argument(
         "--format",
         type=str,
         default=os.environ.get("FINETUNE_FORMAT", "chat"),
         choices=["alpaca", "chat", "prompt", "text"],
     )
+    # Column-name overrides: let a dataset's own columns map onto a --format
+    # without preprocessing (e.g. MetaMathQA query/response -> prompt format,
+    # orca-math question/answer -> prompt format).
+    p.add_argument("--prompt-key", default=None,
+                   help="column to use as the prompt (prompt format)")
+    p.add_argument("--response-key", default=None,
+                   help="column to use as the response (prompt format)")
+    p.add_argument("--instruction-key", default=None,
+                   help="column to use as instruction (alpaca format)")
+    p.add_argument("--input-key", default=None,
+                   help="column to use as optional input (alpaca format)")
+    p.add_argument("--output-key", default=None,
+                   help="column to use as output (alpaca format)")
     p.add_argument("--mode", type=str, default="lora",
                    choices=["full", "lora", "qlora"])
     p.add_argument(
@@ -273,6 +296,22 @@ def parse_args():
     p.add_argument("--mask_prompt", action="store_true", default=True,
                    help="compute loss only on the response tokens")
     p.add_argument("--no_mask_prompt", dest="mask_prompt", action="store_false")
+    # training schedule / regularization (previously hardcoded)
+    p.add_argument("--lr_scheduler", type=str, default="cosine",
+                   help="LR scheduler type: cosine, linear, constant, ...")
+    p.add_argument("--weight_decay", type=float, default=0.01)
+    p.add_argument("--max_grad_norm", type=float, default=1.0)
+    p.add_argument("--logging_steps", type=int, default=10)
+    p.add_argument("--eval_steps", type=int, default=None,
+                   help="eval every N steps (default: max_steps//5, else 200)")
+    p.add_argument("--save_steps", type=int, default=500)
+    p.add_argument("--save_total_limit", type=int, default=2)
+    p.add_argument("--early_stopping_patience", type=int, default=0,
+                   help=">0 enables early stopping + load_best_model_at_end on eval_loss")
+    p.add_argument("--neftune_noise_alpha", type=float, default=None,
+                   help="NEFTune noise alpha (e.g. 5) — quick instruction-tuning gain")
+    p.add_argument("--report_to", type=str, default="none",
+                   help="trainer reporting: none, wandb, tensorboard, ...")
     # lora hparams
     p.add_argument("--lora_r", type=int, default=16)
     p.add_argument("--lora_alpha", type=int, default=32)
@@ -398,6 +437,7 @@ def save_training_results(
         "dataset": args.dataset,
         "dataset_config": args.dataset_config,
         "dataset_split": args.dataset_split,
+        "mix": json.loads(args.mix_json) if args.mix_json else None,
         "format": args.format,
         "mode": args.mode,
         "output_dir": out_dir,
@@ -431,23 +471,29 @@ def save_training_results(
     return path
 
 
-def to_prompt_response(example, fmt, tokenizer):
+def to_prompt_response(example, fmt, tokenizer, keys=None):
     """Normalize any supported format into a single training string,
-    returning (full_text, prompt_text). prompt_text is None for raw text."""
+    returning (full_text, prompt_text). prompt_text is None for raw text.
+
+    `keys` optionally remaps a dataset's column names onto the format's
+    expected fields (e.g. {"prompt": "query"} for MetaMathQA)."""
+    keys = keys or {}
     if fmt == "text":
-        return example["text"], None
+        return example[keys.get("text", "text")], None
 
     if fmt == "alpaca":
-        instr = example.get("instruction", "")
-        inp = example.get("input", "") or ""
-        out = example.get("output", "")
+        instr = example.get(keys.get("instruction", "instruction"), "")
+        inp = example.get(keys.get("input", "input"), "") or ""
+        out = example.get(keys.get("output", "output"), "")
         user = instr if not inp else f"{instr}\n\n{inp}"
         messages = [{"role": "user", "content": user},
                     {"role": "assistant", "content": out}]
 
     elif fmt == "prompt":
-        prompt = example.get("prompt", "")
-        resp = example.get("completion", example.get("response", ""))
+        prompt = example.get(keys.get("prompt", "prompt"), "")
+        rkey = keys.get("response")
+        resp = example.get(rkey, "") if rkey else example.get(
+            "completion", example.get("response", ""))
         messages = [{"role": "user", "content": prompt},
                     {"role": "assistant", "content": resp}]
 
@@ -471,9 +517,9 @@ def to_prompt_response(example, fmt, tokenizer):
     return full, prompt_only
 
 
-def build_tokenize_fn(tokenizer, fmt, max_len, mask_prompt):
+def build_tokenize_fn(tokenizer, fmt, max_len, mask_prompt, keys=None):
     def fn(example):
-        full, prompt = to_prompt_response(example, fmt, tokenizer)
+        full, prompt = to_prompt_response(example, fmt, tokenizer, keys)
         ids = tokenizer(full, truncation=True, max_length=max_len,
                         add_special_tokens=(fmt == "text"))["input_ids"]
         labels = list(ids)
@@ -485,6 +531,82 @@ def build_tokenize_fn(tokenizer, fmt, max_len, mask_prompt):
     return fn
 
 
+def _source_specs(args) -> list[dict]:
+    """Return the list of dataset source specs to train on.
+
+    With --mix-json, parse the JSON list verbatim. Otherwise synthesize a
+    single source from the top-level --dataset/--format/--*-key args."""
+    if args.mix_json:
+        specs = json.loads(args.mix_json)
+        if not isinstance(specs, list) or not specs:
+            raise SystemExit("--mix-json must be a non-empty JSON list of source specs")
+        return specs
+    return [{
+        "dataset": args.dataset,
+        "format": args.format,
+        "dataset_config": args.dataset_config,
+        "dataset_split": args.dataset_split,
+        "max_samples": args.dataset_max_samples,
+        "columns": {k: v for k, v in {
+            "prompt": args.prompt_key, "response": args.response_key,
+            "instruction": args.instruction_key, "input": args.input_key,
+            "output": args.output_key,
+        }.items() if v},
+    }]
+
+
+def _apply_weight(ds, weight):
+    """Up-sample (weight > 1, with repeats) or sub-sample (weight < 1) a source."""
+    if not weight or weight == 1.0 or len(ds) == 0:
+        return ds
+    target = max(0, int(round(len(ds) * float(weight))))
+    if target == 0:
+        return ds.select([])
+    n = len(ds)
+    return ds.select([i % n for i in range(target)])  # repeats when target > n
+
+
+def build_training_dataset(args, tokenizer):
+    """Load, tokenize, weight and concatenate every source into one dataset.
+
+    Each source carries its own format / columns / split / max_len so a skill
+    dataset can be mixed with a general-data replay slice in one run."""
+    from datasets import concatenate_datasets
+
+    specs = _source_specs(args)
+    multi = len(specs) > 1
+    if multi:
+        print(f"Mixing {len(specs)} dataset source(s):")
+
+    parts = []
+    for i, spec in enumerate(specs):
+        dataset = spec.get("dataset")
+        if not dataset:
+            raise SystemExit(f"mix source #{i} is missing 'dataset'")
+        fmt = spec.get("format", args.format)
+        raw = load_raw_dataset(
+            dataset,
+            config=spec.get("dataset_config"),
+            split=spec.get("dataset_split", "train"),
+            max_samples=spec.get("max_samples"),
+        )
+        raw = raw.shuffle(seed=args.seed)
+        keys = spec.get("columns") or {}
+        max_len = spec.get("max_len", args.max_len)
+        tokenize = build_tokenize_fn(tokenizer, fmt, max_len, args.mask_prompt, keys)
+        tok = raw.map(tokenize, remove_columns=raw.column_names,
+                      desc=f"tokenizing {dataset}")
+        tok = tok.filter(lambda e: len(e["input_ids"]) > 1)
+        tok = _apply_weight(tok, spec.get("weight"))
+        if multi:
+            wnote = f" (weight {spec['weight']})" if spec.get("weight") else ""
+            print(f"  - {dataset} [{fmt}] -> {len(tok)} examples{wnote}")
+        parts.append(tok)
+
+    ds = parts[0] if len(parts) == 1 else concatenate_datasets(parts)
+    return ds.shuffle(seed=args.seed)
+
+
 class CausalCollator:
     """Pads input_ids with pad_token and labels with IGNORE_INDEX."""
     def __init__(self, tokenizer):
@@ -795,7 +917,10 @@ def main():
     print(f"Base model: {args.model}")
     if preset_key:
         print(f"Preset: {preset_key}")
-    print(f"Dataset: {args.dataset}")
+    if args.mix_json:
+        print(f"Dataset mix: {len(json.loads(args.mix_json))} source(s)")
+    else:
+        print(f"Dataset: {args.dataset}")
     print(f"Output: {args.out}")
     print(f"Device: {args.device}")
 
@@ -813,17 +938,7 @@ def main():
     if _training_uses_cuda(args):
         print(f"GPU after model load: {_gpu_memory_summary()}")
 
-    ds = load_raw_dataset(
-        args.dataset,
-        config=args.dataset_config,
-        split=args.dataset_split,
-        max_samples=args.dataset_max_samples,
-    )
-    ds = ds.shuffle(seed=args.seed)
-    tokenize = build_tokenize_fn(tokenizer, args.format, args.max_len,
-                                 args.mask_prompt)
-    ds = ds.map(tokenize, remove_columns=ds.column_names, desc="tokenizing")
-    ds = ds.filter(lambda e: len(e["input_ids"]) > 1)
+    ds = build_training_dataset(args, tokenizer)
 
     if args.val_split > 0:
         split = ds.train_test_split(test_size=args.val_split, seed=args.seed)
@@ -831,6 +946,16 @@ def main():
     else:
         train_ds, eval_ds = ds, None
 
+    # Default eval cadence to the run length so short (max_steps) runs still
+    # evaluate mid-training instead of only at the end.
+    eval_steps = args.eval_steps
+    if eval_steps is None:
+        eval_steps = max(1, args.max_steps // 5) if args.max_steps > 0 else 200
+
+    use_best = args.early_stopping_patience > 0 and eval_ds is not None
+    # load_best_model_at_end needs save_steps aligned to eval_steps.
+    save_steps = eval_steps if use_best else args.save_steps
+
     targs = TrainingArguments(
         output_dir=args.out,
         num_train_epochs=args.epochs,
@@ -839,28 +964,41 @@ def main():
         per_device_eval_batch_size=args.batch_size,
         gradient_accumulation_steps=args.grad_accum,
         learning_rate=lr,
-        lr_scheduler_type="cosine",
+        lr_scheduler_type=args.lr_scheduler,
         warmup_ratio=args.warmup_ratio,
-        weight_decay=0.01,
-        logging_steps=10,
+        weight_decay=args.weight_decay,
+        max_grad_norm=args.max_grad_norm,
+        logging_steps=args.logging_steps,
         eval_strategy="steps" if eval_ds is not None else "no",
-        eval_steps=200,
+        eval_steps=eval_steps,
         save_strategy="steps",
-        save_steps=500,
-        save_total_limit=2,
+        save_steps=save_steps,
+        save_total_limit=args.save_total_limit,
+        load_best_model_at_end=use_best,
+        metric_for_best_model="eval_loss" if use_best else None,
+        greater_is_better=False if use_best else None,
         bf16=bf16_ok,
         fp16=(not bf16_ok and _training_uses_cuda(args)),
         gradient_checkpointing=args.gradient_checkpointing,
-        report_to="none",
+        neftune_noise_alpha=args.neftune_noise_alpha,
+        report_to=args.report_to,
         seed=args.seed,
     )
 
+    callbacks = []
+    if use_best:
+        from transformers import EarlyStoppingCallback
+        callbacks.append(
+            EarlyStoppingCallback(early_stopping_patience=args.early_stopping_patience)
+        )
+
     trainer = Trainer(
         model=model,
         args=targs,
         train_dataset=train_ds,
         eval_dataset=eval_ds,
         data_collator=CausalCollator(tokenizer),
+        callbacks=callbacks,
     )
 
     train_result = trainer.train(resume_from_checkpoint=args.resume)
@@ -894,7 +1032,7 @@ def main():
         eval_metrics=eval_metrics,
     )
     m = json.loads(results_path.read_text())["metrics"]
-    print(f"\n--- scores ---")
+    print("\n--- scores ---")
     print(f"loss_score   = {m['loss_score']}  (lower is better)")
     print(f"result_score = {m['result_score']}  (0–100, higher is better)")
     print(f"Saved to {results_path}")

research/modal/_common.py

@@ -75,7 +75,12 @@ image = (
         ],
     )
     .run_commands(
-        "cd /repo && uv sync --frozen --group finetune --group lm-eval --no-dev"
+        "cd /repo && uv sync --frozen --group finetune --group lm-eval --no-dev",
+        # lm-eval's ifeval task (instructions profile) needs these, declared via
+        # the lm-eval[ifeval] extra but not activated into the project venv by the
+        # frozen group sync. Install the lock-pinned versions into /repo/.venv so
+        # `uv run slm-lm-eval` can import them.
+        "cd /repo && uv pip install langdetect==1.0.9 immutabledict==4.3.1",
     )
 )
 
@@ -114,6 +119,35 @@ def apply_defaults(job: dict[str, Any], defaults: dict[str, Any]) -> dict[str, A
     return {**defaults, **job}
 
 
+# Scalar hyperparameters an experiments.yaml job (or its nested `args:` block)
+# may set; each maps 1:1 onto a research/finetune.py flag so any run is tunable
+# from config without code changes.
+_FINETUNE_FLAGS: dict[str, str] = {
+    "model": "--model",
+    "lr": "--lr",
+    "batch_size": "--batch_size",
+    "grad_accum": "--grad_accum",
+    "max_len": "--max_len",
+    "warmup_ratio": "--warmup_ratio",
+    "weight_decay": "--weight_decay",
+    "max_grad_norm": "--max_grad_norm",
+    "lr_scheduler": "--lr_scheduler",
+    "logging_steps": "--logging_steps",
+    "eval_steps": "--eval_steps",
+    "save_steps": "--save_steps",
+    "save_total_limit": "--save_total_limit",
+    "early_stopping_patience": "--early_stopping_patience",
+    "neftune_noise_alpha": "--neftune_noise_alpha",
+    "report_to": "--report_to",
+    "seed": "--seed",
+    "lora_r": "--lora_r",
+    "lora_alpha": "--lora_alpha",
+    "lora_dropout": "--lora_dropout",
+    "lora_targets": "--lora_targets",
+    "val_split": "--val_split",
+}
+
+
 def build_finetune_cmd(job: dict[str, Any], out_dir: str) -> list[str]:
     cmd = [
         "uv",
@@ -124,23 +158,43 @@ def build_finetune_cmd(job: dict[str, Any], out_dir: str) -> list[str]:
         job.get("preset", "minicpm5-1b"),
         "--mode",
         job.get("mode", "lora"),
-        "--dataset",
-        job["dataset"],
-        "--format",
-        job["format"],
         "--out",
         out_dir,
     ]
+    # Dataset: a `mix:` list (skill data + general replay) takes precedence over
+    # a single --dataset/--format source.
+    if job.get("mix"):
+        cmd.extend(["--mix-json", json.dumps(job["mix"])])
+    else:
+        cmd.extend(["--dataset", job["dataset"], "--format", job["format"]])
+        if job.get("dataset_config"):
+            cmd.extend(["--dataset-config", job["dataset_config"]])
+        if job.get("dataset_split"):
+            cmd.extend(["--dataset-split", str(job["dataset_split"])])
+        if job.get("max_samples") is not None:
+            cmd.extend(["--dataset-max-samples", str(int(job["max_samples"]))])
+        # Optional column remap so a dataset's own columns fit the --format
+        # (e.g. MetaMathQA query/response -> prompt format).
+        for field, col in (job.get("columns") or {}).items():
+            cmd.extend([f"--{field}-key", str(col)])
+
     if job.get("max_steps") is not None:
         cmd.extend(["--max_steps", str(int(job["max_steps"]))])
     if job.get("epochs") is not None:
         cmd.extend(["--epochs", str(job["epochs"])])
-    if job.get("dataset_config"):
-        cmd.extend(["--dataset-config", job["dataset_config"]])
-    if job.get("dataset_split"):
-        cmd.extend(["--dataset-split", str(job["dataset_split"])])
-    if job.get("max_samples") is not None:
-        cmd.extend(["--dataset-max-samples", str(int(job["max_samples"]))])
+    if job.get("mask_prompt") is False:
+        cmd.append("--no_mask_prompt")
+
+    # Scalar hyperparameters: top-level keys plus an optional nested `args:` block.
+    overrides = {k: job[k] for k in _FINETUNE_FLAGS if k in job}
+    overrides.update(job.get("args") or {})
+    for key, value in overrides.items():
+        flag = _FINETUNE_FLAGS.get(key, f"--{key}")
+        if isinstance(value, bool):
+            if value:
+                cmd.append(flag)
+        else:
+            cmd.extend([flag, str(value)])
     return cmd
 
 
@@ -313,21 +367,28 @@ def evaluate_gate(
 
 def pull_artifacts(job_name: str, exp_name: str, dest: str = "models/finetuned") -> None:
     """Download an adapter and its lm-eval results from the `slm-finetune` Volume (run locally)."""
+    import shutil
     import subprocess
 
-    local_dir = f"{dest}/{job_name}"
-    print(f"--- pulling {job_name} -> {local_dir} ---")
-    subprocess.run(
-        ["modal", "volume", "get", "slm-finetune", job_name, local_dir, "--force"],
-        check=False,
-    )
+    def _get(remote: str, parent: str) -> None:
+        # For a folder REMOTE_PATH, `modal volume get` expects the *parent*
+        # directory as the destination and recreates the folder inside it.
+        # Passing the full target path (parent/<name>) raises
+        # "[Errno 21] Is a directory". Clear the target first for a clean pull.
+        name = remote.rsplit("/", 1)[-1]
+        shutil.rmtree(Path(parent) / name, ignore_errors=True)
+        Path(parent).mkdir(parents=True, exist_ok=True)
+        subprocess.run(
+            ["modal", "volume", "get", "slm-finetune", remote, f"{parent}/", "--force"],
+            check=False,
+        )
 
-    results_dir = f"results/lm_eval/{exp_name}"
-    print(f"--- pulling {results_dir} ---")
-    subprocess.run(
-        ["modal", "volume", "get", "slm-finetune", results_dir, results_dir, "--force"],
-        check=False,
-    )
+    print(f"--- pulling {job_name} -> {dest}/{job_name} ---")
+    _get(job_name, dest)
+
+    exp_dir = f"results/lm_eval/{exp_name}"
+    print(f"--- pulling {exp_dir} ---")
+    _get(exp_dir, "results/lm_eval")
 
 
 def check_gate_files(

research/modal/experiments.yaml

@@ -62,14 +62,32 @@ finetune:
       hub_repo: MSGEncrypted/minicpm5-1b-science-lora
       private: false
 
-  # --- math: grade-school word problems + instruction-style math solutions ---
+  # --- math: GSM8K/MATH natural-language CoT augmentation (MetaMathQA) ---
+  # MetaMathQA's NL chain-of-thought matches GSM8K's 5-shot format far better
+  # than MathInstruct's program-of-thought answers (which regressed gsm8k).
+  # The `mix:` adds a general-data replay slice (alpaca) so skill tuning does
+  # not regress the arc/hellaswag/piqa guards. `args:` flows any
+  # research/finetune.py hyperparameter straight through.
   - name: math-lora
     category: math
-    dataset: TIGER-Lab/MathInstruct
-    format: alpaca
-    dataset_split: "train[:1000]"
-    max_samples: 1000
-    description: Math instruction tuning (Hub, instruction/output columns)
+    max_steps: 150
+    mix:
+      - dataset: meta-math/MetaMathQA
+        format: prompt
+        columns:
+          prompt: query
+          response: response
+        dataset_split: "train[:3000]"
+        max_samples: 3000
+      - dataset: tatsu-lab/alpaca          # general replay: protect guard tasks
+        format: alpaca
+        dataset_split: "train[:600]"
+        max_samples: 600
+    args:
+      lora_r: 32
+      lora_alpha: 64
+      neftune_noise_alpha: 5
+    description: GSM8K/MATH NL-CoT (MetaMathQA) + alpaca replay, r=32 + NEFTune
     eval_profile: math
     goals:
       task: gsm8k
@@ -78,6 +96,10 @@ finetune:
       guard_tasks:
         - task: arc_challenge
           max_regress: 0.03
+        - task: hellaswag
+          max_regress: 0.03
+        - task: piqa
+          max_regress: 0.03
     publish:
       hub_repo: MSGEncrypted/minicpm5-1b-math-lora
       private: false
@@ -95,6 +117,11 @@ finetune:
       task: mbpp
       min_score: 0.05
       min_improve: 0.01
+      guard_tasks:
+        - task: hellaswag
+          max_regress: 0.03
+        - task: piqa
+          max_regress: 0.03
     publish:
       hub_repo: MSGEncrypted/minicpm5-1b-coding-lora
       private: false

research/modal/server_app.py

@@ -85,6 +85,7 @@ app = modal.App(APP_NAME, image=image)
     timeout=DEFAULT_WORKER_TIMEOUT,
     scaledown_window=DEFAULT_SCALEDOWN_WINDOW,
     min_containers=1,
+    max_containers=1,  # single warm container; serialize work, never sprawl
 )
 class GpuWorker:
     """Single warm GPU container for sequential finetune / lm-eval / shell commands."""
@@ -165,6 +166,10 @@ class GpuWorker:
         compare_to: str | None = None,
     ) -> dict[str, Any]:
         """Run slm-lm-eval on base model or finetuned checkpoint."""
+        # Pick up adapters committed by another container (e.g. a separate
+        # eval-only invocation) — the warm container's mount may predate them.
+        reload_volumes()
+
         if adapter_path:
             adapter_dir = Path(adapter_path)
             adapter_cfg = adapter_dir / "adapter_config.json"