Default extraction to the fine-tuned MiniCPM-V Hub checkpoint.

Point DEFAULT_HF_REPO at build-small-hackathon/blood-test-minicpmv-4_6-medreason so local runs and the Space use our MedReason SFT model without extra env vars.

Co-authored-by: Codex <chatgpt-codex-connector[bot]@users.noreply.github.com>

DEPLOY.md

@@ -11,7 +11,7 @@ This workflow is intentionally fixed:
 5. When the fine-tuned model is ready, replace only the model variables for the active lanes.
 6. The llama.cpp lane is optional and must be enabled explicitly with environment variables.
 
-Do not change this architecture unless the project intentionally gives up ZeroGPU. The intended future model-serving change is inserting the fine-tuned Transformers repository into `ZEROGPU_MODEL_ID`, and optionally inserting the fine-tuned GGUF repository into `LLAMACPP_*` for the llama.cpp lane.
+Do not change this architecture unless the project intentionally gives up ZeroGPU. To swap models, change `ZEROGPU_MODEL_ID` (or `DEFAULT_HF_REPO` in `src/model_paths.py`) and optional `LLAMACPP_*` for the llama.cpp lane.
 
 ## 1. Space Metadata
 
@@ -35,13 +35,17 @@ ZeroGPU is Gradio-only on Hugging Face. It is not available for Docker Spaces, w
 
 ## 2. Default Model Serving (Transformers)
 
-The production Space path is the official OpenBMB Transformers repo:
+The production Space path is the fine-tuned Transformers repo:
 
 ```text
 EXTRACTOR_BACKEND=transformers
-ZEROGPU_MODEL_ID=openbmb/MiniCPM-V-4.6
+ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
 ```
 
+Hub: [build-small-hackathon/blood-test-minicpmv-4_6-medreason](https://huggingface.co/build-small-hackathon/blood-test-minicpmv-4_6-medreason)
+
+`ZEROGPU_MODEL_ID` is optional when it matches the code default in `src/model_paths.py`. Use `openbmb/MiniCPM-V-4.6` only for base-model baselines.
+
 The backend lives in:
 
 ```text
@@ -96,14 +100,14 @@ LLAMACPP_GGUF_REPO=openbmb/MiniCPM-V-4.6-gguf
 LLAMACPP_MODEL_FILE=MiniCPM-V-4_6-Q4_K_M.gguf
 ```
 
-## 4. Future Fine-Tuned Model
+## 4. Swapping or Retraining the Model
 
-When the fine-tuned model is ready:
+To publish a newer fine-tune:
 
-1. Upload the fine-tuned Transformers checkpoint to a Hugging Face model repo.
-2. Optionally convert/quantize the fine-tuned model to GGUF (+ mmproj) for the llama.cpp lane.
+1. Upload the Transformers checkpoint to a Hugging Face model repo.
+2. Optionally convert/quantize to GGUF (+ mmproj) for the llama.cpp lane.
 3. Keep the same Gradio + ZeroGPU architecture.
-4. Change only these variables:
+4. Point extraction at the new repo:
 
 ```bash
 ZEROGPU_MODEL_ID=<owner>/<fine-tuned-minicpm-v-transformers-repo>
@@ -112,6 +116,8 @@ LLAMACPP_MODEL_FILE=<fine-tuned-model>.gguf
 LLAMACPP_MMPROJ_FILE=<mmproj-file>.gguf
 ```
 
+Or update `DEFAULT_HF_REPO` in `src/model_paths.py` so local runs and the Space pick it up without an env override.
+
 Do not add model files to the Space git repo. Do not reintroduce Docker or `llama-server` for the ZeroGPU deployment.
 
 ## 5. Why This Architecture
@@ -122,9 +128,9 @@ This architecture keeps:
 
 - Free ZeroGPU eligibility.
 - No external hosted inference API calls.
-- The official OpenBMB Transformers runtime on ZeroGPU for PDF/image lab reports.
+- The fine-tuned Transformers runtime on ZeroGPU for PDF/image lab reports.
 - An optional llama.cpp / GGUF lane for badges and fine-tuned GGUF deployment.
-- A clean future swap to a fine-tuned model by changing only `ZEROGPU_MODEL_ID` and optional `LLAMACPP_*` variables.
+- A clean model swap by changing `ZEROGPU_MODEL_ID` / `DEFAULT_HF_REPO` and optional `LLAMACPP_*` variables.
 
 ## 6. Local Development
 

README.md

@@ -46,7 +46,7 @@ The knowledge graph is educational context, not diagnosis. The lab-provided refe
 
 ## Extraction Backends
 
-The default path is **Transformers vision** (OpenBMB MiniCPM-V 4.6). It handles PDFs, scans, and photos through the same document pipeline in `src/document_processing.py`.
+The default path is **Transformers vision** with our fine-tuned [blood-test-minicpmv-4_6-medreason](https://huggingface.co/build-small-hackathon/blood-test-minicpmv-4_6-medreason) checkpoint (MiniCPM-V 4.6 + MedReason SFT). It handles PDFs, scans, and photos through the same document pipeline in `src/document_processing.py`.
 
 | `EXTRACTOR_BACKEND` | Used for | PDF / image uploads |
 |---|---|---|
@@ -123,9 +123,11 @@ Default Space variables:
 
 ```bash
 EXTRACTOR_BACKEND=transformers
-ZEROGPU_MODEL_ID=openbmb/MiniCPM-V-4.6
+ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
 ```
 
+`ZEROGPU_MODEL_ID` is optional — the app defaults to the fine-tuned repo above. Override with `openbmb/MiniCPM-V-4.6` only for base-model experiments.
+
 Optional llama.cpp badge lane (not enabled in the default deployment):
 
 ```bash
@@ -136,7 +138,7 @@ LLAMACPP_MODEL_FILE=MiniCPM-V-4_6-Q4_K_M.gguf
 LLAMACPP_MMPROJ_FILE=mmproj-model-f16.gguf
 ```
 
-When the fine-tuned models are ready, replace `ZEROGPU_MODEL_ID` for the primary lane and the `LLAMACPP_*` variables for the optional GGUF lane. Do not commit model files to the Space git repo.
+When a new fine-tuned checkpoint is ready, replace `ZEROGPU_MODEL_ID` (or update `DEFAULT_HF_REPO` in `src/model_paths.py`) for the primary lane and the `LLAMACPP_*` variables for the optional GGUF lane. Do not commit model files to the Space git repo.
 
 This workflow should not be changed back to Docker unless the project intentionally gives up ZeroGPU.
 

RUNBOOK.md

@@ -9,7 +9,7 @@ This replaced the Docker + `llama-server` path because ZeroGPU is only available
 | Area | Current choice |
 |---|---|
 | Space SDK | `gradio` |
-| Default extraction | Transformers MiniCPM-V 4.6 (`EXTRACTOR_BACKEND=transformers`) |
+| Default extraction | Fine-tuned MiniCPM-V 4.6 (`build-small-hackathon/blood-test-minicpmv-4_6-medreason`) |
 | ZeroGPU worker | `@spaces.GPU` in `src/extraction/zerogpu_transformers.py` |
 | Optional llama.cpp lane | `EXTRACTOR_BACKEND=llamacpp-gpu` (+ `LLAMACPP_VISION=1` for PDF/images) |
 | Transformers variables | `ZEROGPU_MODEL_ID`, `ZEROGPU_MAX_NEW_TOKENS`, `ZEROGPU_DOWNSAMPLE_MODE` |
@@ -25,7 +25,7 @@ Do not switch the Space back to Docker unless the project intentionally gives up
 
 | Value | Behavior |
 |---|---|
-| `transformers` (default) | OpenBMB MiniCPM-V through Transformers vision |
+| `transformers` (default) | Fine-tuned MiniCPM-V through Transformers vision |
 | `auto`, `zerogpu`, `zero-gpu` | Same as `transformers` |
 | `llamacpp-gpu`, `llama-champion` | GGUF through `llama-cpp-python` |
 | `local`, `server` | Local `llama-server` HTTP backend |
@@ -36,10 +36,10 @@ Do not switch the Space back to Docker unless the project intentionally gives up
 
 ```bash
 EXTRACTOR_BACKEND=transformers
-ZEROGPU_MODEL_ID=openbmb/MiniCPM-V-4.6
+ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
 ```
 
-This is what the HF Space should use for PDF/image blood-test uploads.
+This is what the HF Space should use for PDF/image blood-test uploads. The env var is optional when it matches `DEFAULT_HF_REPO` in `src/model_paths.py`.
 
 ### Optional llama.cpp path
 
@@ -115,7 +115,7 @@ Primary lane:
 
 ```bash
 EXTRACTOR_BACKEND=transformers
-ZEROGPU_MODEL_ID=openbmb/MiniCPM-V-4.6
+ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
 ```
 
 Optional llama.cpp lane:
@@ -130,12 +130,14 @@ No model files are committed to the Space repo.
 
 ## Fine-Tuned Model Swap
 
-When the fine-tuned model is ready:
+Current default: [build-small-hackathon/blood-test-minicpmv-4_6-medreason](https://huggingface.co/build-small-hackathon/blood-test-minicpmv-4_6-medreason).
 
-1. Upload the fine-tuned Transformers checkpoint to a Hugging Face model repo for the primary lane.
+To publish a newer checkpoint:
+
+1. Upload the fine-tuned Transformers checkpoint to a Hugging Face model repo.
 2. Optionally convert/quantize it to GGUF (+ mmproj) for the llama.cpp lane.
 3. Keep the same Gradio architecture.
-4. Change only:
+4. Update `DEFAULT_HF_REPO` in `src/model_paths.py` and/or:
 
 ```bash
 ZEROGPU_MODEL_ID=<owner>/<fine-tuned-minicpm-v-transformers-repo>

app.py

@@ -210,7 +210,7 @@ def hero_hackathon_panel_html() -> str:
         (
             "🎯",
             "Well-Tuned",
-            "MiniCPM-V was fine-tuned on Modal and published on Hugging Face for lab report extraction.",
+            "MiniCPM-V was fine-tuned on Modal with MedReason-style SFT and published on Hugging Face for lab report extraction.",
         ),
         (
             "🎨",
@@ -276,7 +276,7 @@ def hero_attribution_html() -> str:
             "Enabled with OpenBMB",
             "OB",
             "openbmb.png",
-            "MiniCPM-V-4.6 reads uploaded lab reports and extracts marker values, units, and status flags.",
+            "Our fine-tuned MiniCPM-V-4.6 reads uploaded lab reports and extracts marker values, units, and status flags.",
         ),
         (
             "Modal",

docs/MESSAGE_TO_DIMITRIS.md

@@ -4,13 +4,13 @@ Hi Dimitris — here’s what’s left before submission. Full checklist for you
 
 **Priority order:** custom model → copy pass → KB + videos (agents) → article → demo video.
 
-1. **Custom model** — Publish/confirm the fine-tuned MiniCPM-V on Hub, set `ZEROGPU_MODEL_ID` on the Space, test real PDFs, run `modal_eval` for before/after numbers.
+1. **Custom model** — Fine-tuned repo is live on Hub and wired as the code default; confirm Space after redeploy, run `modal run train/modal_eval.py::compare` for before/after numbers.
 2. **Copy** — Tighten hero, trace steps, and README; fix badge claims (Well-Tuned only after model swap).
 3. **Knowledge graph** — Expand beyond 107 markers via `markers.py` + `expand_lab_knowledge_graph.py` (agent task).
 4. **Videos** — Replace reused YouTube URLs with marker/category-specific explainers (agent task).
 5. **Article** — Problem → architecture → fine-tune proof → limitations + Space link.
 6. **Demo video** — Laytimely-style: AI voice + screen recording + background music; record after 1–2 are done.
 
-**Current baseline:** Space runs base OpenBMB model; KG has 107 markers; only 2/13 real eval reports labeled; article and demo not started.
+**Current baseline:** App defaults to `build-small-hackathon/blood-test-minicpmv-4_6-medreason`; KG has 107 markers; only 2/13 real eval reports labeled; article and demo not started.
 
 Ping me when the model is on the Space or if you want me on copy/KB review.

docs/REMAINING_WORK.md

@@ -12,7 +12,7 @@
 
 | Area | Now |
 |---|---|
-| Space / app | Live on Transformers (`openbmb/MiniCPM-V-4.6`) |
+| Space / app | Fine-tuned Transformers (`build-small-hackathon/blood-test-minicpmv-4_6-medreason`) |
 | Knowledge graph | 107 markers in `kb/cbc_knowledge_graph.json` |
 | Marker videos | All 107 have `video_url`; ~44 unique YouTube IDs (many reused) |
 | Real eval labels | 2/13 reports fully labeled in `eval/data/real/labels.jsonl` |
@@ -25,18 +25,14 @@
 
 **Owner:** Dimitris (Modal + HF Space vars)
 
-- [ ] Confirm fine-tuned Transformers repo on Hub (e.g. `dimitriskalligaridis/blood-test-minicpmv-4_6`) loads with `transformers[torch]==5.7.0`
-- [ ] If not published yet: finish labeling → `modal run train/modal_finetune.py::main --real-labels eval/data/real/labels_train.jsonl` → `modal run train/modal_finetune.py::merge --repo-id <owner>/<name>`
-- [ ] Set HF Space variables:
-  ```bash
-  EXTRACTOR_BACKEND=transformers
-  ZEROGPU_MODEL_ID=<fine-tuned-repo>
-  ```
-- [ ] Rebuild Space; test 2–3 PDFs from `eval/data/real/`
-- [ ] Run before/after eval: `modal run train/modal_eval.py::compare --finetuned-id <repo>` → save `eval/before_after.json`
+- [x] Fine-tuned Transformers repo on Hub: `build-small-hackathon/blood-test-minicpmv-4_6-medreason`
+- [x] Code default in `src/model_paths.py` → `DEFAULT_HF_REPO`
+- [ ] Confirm Space loads the model after redeploy (2–3 PDFs from `eval/data/real/`)
+- [ ] Set HF Space variable if still on base model: `ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason` (optional when code default is deployed)
+- [ ] Run before/after eval: `modal run train/modal_eval.py::compare` → save `eval/before_after.json`
 - [ ] *(Optional, Llama badge only)* GGUF via `scripts/convert_to_gguf.sh` + `LLAMACPP_VISION=1` vars (see `README.md`)
 
-**Done when:** Space uses custom model; we have a before/after metric for the article.
+**Done when:** Space uses custom model in production; we have a before/after metric for the article.
 
 ---
 
@@ -47,7 +43,7 @@
 **Edit:** `app.py` (hero, upload hints, status, disclaimers), `src/pipeline_trace.py` (step copy), `README.md` (Space card)
 
 - [ ] One clear pitch: upload → extract → explain → prepare for clinician conversation
-- [ ] Badge claims match reality (Well-Tuned only after custom model is live)
+- [ ] Badge claims match reality (Well-Tuned reflects live fine-tuned model)
 - [ ] Consistent “educational, not diagnosis” disclaimer
 - [ ] Less dev jargon in user-facing text (“pipeline phase”, etc.)
 - [ ] Align hero badges with hackathon criteria (OpenBMB, Modal, HF, off-grid)
@@ -124,7 +120,7 @@
 
 ## Submission checklist
 
-- [ ] Custom model on Space (`ZEROGPU_MODEL_ID`)
+- [x] Custom model wired in code (`DEFAULT_HF_REPO`); [ ] confirm on live Space after deploy
 - [ ] Before/after eval documented
 - [ ] Copy + badges accurate
 - [ ] KG + videos polished

src/extraction/zerogpu_transformers.py

@@ -1,4 +1,4 @@
-"""ZeroGPU extraction backend using the official MiniCPM-V Transformers path."""
+"""ZeroGPU extraction backend using the fine-tuned MiniCPM-V Transformers path."""
 
 from __future__ import annotations
 
@@ -18,8 +18,6 @@ from src.openbmb_client import (
 
 from src.model_paths import TransformersModelSource, resolve_transformers_model_source
 
-DEFAULT_ZEROGPU_MODEL = "openbmb/MiniCPM-V-4.6"
-
 
 class ZeroGPUTransformersExtractor:
     """Extractor backed by local or Hub MiniCPM-V Transformers weights."""

src/model_paths.py

@@ -6,7 +6,10 @@ import os
 from dataclasses import dataclass
 from pathlib import Path
 
-DEFAULT_HF_REPO = "openbmb/MiniCPM-V-4.6"
+# Fine-tuned MiniCPM-V 4.6 for lab extraction (MedReason SFT).
+DEFAULT_HF_REPO = "build-small-hackathon/blood-test-minicpmv-4_6-medreason"
+# Upstream OpenBMB base — eval baselines and training scripts.
+BASE_HF_REPO = "openbmb/MiniCPM-V-4.6"
 
 
 @dataclass(frozen=True)

tests/test_model_paths.py

@@ -4,7 +4,12 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
-from src.model_paths import is_transformers_model_dir, resolve_transformers_model_source
+from src.model_paths import (
+    BASE_HF_REPO,
+    DEFAULT_HF_REPO,
+    is_transformers_model_dir,
+    resolve_transformers_model_source,
+)
 
 
 def test_resolve_uses_hub_download_when_no_local_weights(monkeypatch):
@@ -18,10 +23,42 @@ def test_resolve_uses_hub_download_when_no_local_weights(monkeypatch):
             lambda repo_id, hub_cache: None,
         )
 
-        source = resolve_transformers_model_source("openbmb/MiniCPM-V-4.6")
+        source = resolve_transformers_model_source(DEFAULT_HF_REPO)
         assert source.local_files_only is False
         assert source.origin == "hub-download"
-        assert source.model_id == "openbmb/MiniCPM-V-4.6"
+        assert source.model_id == DEFAULT_HF_REPO
+
+
+def test_resolve_defaults_to_finetuned_repo(monkeypatch):
+    with tempfile.TemporaryDirectory() as tmp:
+        empty_models = Path(tmp) / "models"
+        empty_models.mkdir()
+        monkeypatch.setenv("BTE_MODELS_DIR", str(empty_models))
+        monkeypatch.setenv("HF_HOME", str(Path(tmp) / "hf"))
+        monkeypatch.delenv("ZEROGPU_MODEL_ID", raising=False)
+        monkeypatch.setattr(
+            "src.model_paths.latest_complete_snapshot",
+            lambda repo_id, hub_cache: None,
+        )
+
+        source = resolve_transformers_model_source()
+        assert source.model_id == DEFAULT_HF_REPO
+        assert source.origin == "hub-download"
+
+
+def test_resolve_base_repo_for_eval_baseline(monkeypatch):
+    with tempfile.TemporaryDirectory() as tmp:
+        empty_models = Path(tmp) / "models"
+        empty_models.mkdir()
+        monkeypatch.setenv("BTE_MODELS_DIR", str(empty_models))
+        monkeypatch.setenv("HF_HOME", str(Path(tmp) / "hf"))
+        monkeypatch.setattr(
+            "src.model_paths.latest_complete_snapshot",
+            lambda repo_id, hub_cache: None,
+        )
+
+        source = resolve_transformers_model_source(BASE_HF_REPO)
+        assert source.model_id == BASE_HF_REPO
 
 
 def test_resolve_uses_local_dir_when_complete():
@@ -47,6 +84,8 @@ def test_is_transformers_model_dir_requires_weights():
 
 if __name__ == "__main__":
     test_resolve_uses_hub_download_when_no_local_weights()
+    test_resolve_defaults_to_finetuned_repo()
+    test_resolve_base_repo_for_eval_baseline()
     test_resolve_uses_local_dir_when_complete()
     test_is_transformers_model_dir_requires_weights()
     print("test_model_paths: ok")

train/modal_eval.py

@@ -5,7 +5,9 @@ field-level accuracy jump. The model runs through the same ZeroGPU/Transformers
 uses (here `@spaces.GPU` is a no-op because the `spaces` package isn't installed, so generation
 runs directly on the Modal GPU).
 
-    modal run train/modal_eval.py::compare --finetuned-id dimitriskalligaridis/blood-test-minicpmv-4_6
+    modal run train/modal_eval.py::compare
+
+    modal run train/modal_eval.py::compare --finetuned-id build-small-hackathon/blood-test-minicpmv-4_6-medreason
 
 Writes eval/before_after.json locally with the base vs fine-tuned metrics.
 """
@@ -97,7 +99,7 @@ def eval_model(model_id: str, labels_rel: str = "eval/data/real/labels.jsonl") -
 
 @app.local_entrypoint()
 def compare(
-    finetuned_id: str,
+    finetuned_id: str = "build-small-hackathon/blood-test-minicpmv-4_6-medreason",
     base_id: str = "openbmb/MiniCPM-V-4.6",
     labels_rel: str = "eval/data/real/labels.jsonl",
 ) -> None:

train/modal_finetune.py

@@ -170,7 +170,7 @@ def main(n: int = 2000, epochs: int = 1, lr: float = 2e-5, real_labels: str | No
     print(f"\nLoRA adapters saved to Modal volume 'blood-test-adapters' at {path}")
     print("Next: merge the adapter into the base model and push it to the Hub:")
     print("  modal run train/modal_finetune.py::merge --repo-id <owner>/<model-name>")
-    print("then set ZEROGPU_MODEL_ID=<owner>/<model-name> on the Space (Transformers path; no GGUF).")
+    print("then update DEFAULT_HF_REPO in src/model_paths.py (or ZEROGPU_MODEL_ID on the Space).")
 
 
 @app.function(
@@ -183,7 +183,7 @@ def main(n: int = 2000, epochs: int = 1, lr: float = 2e-5, real_labels: str | No
 def merge_and_push(repo_id: str, adapter_dir: str = "/adapters/minicpmv-lab-lora") -> str:
     """Merge the newest LoRA checkpoint into MiniCPM-V 4.6 and push the merged model to the Hub.
 
-    Deploy by setting ZEROGPU_MODEL_ID=<repo_id> on the Space (Transformers path; no GGUF needed).
+    Deploy by updating DEFAULT_HF_REPO in src/model_paths.py or setting ZEROGPU_MODEL_ID=<repo_id> on the Space.
     Requires a Modal secret named 'huggingface-secret' exposing HF_TOKEN with write access.
     """
     import glob
@@ -227,5 +227,5 @@ def merge_and_push(repo_id: str, adapter_dir: str = "/adapters/minicpmv-lab-lora
 @app.local_entrypoint()
 def merge(repo_id: str, adapter_dir: str = "/adapters/minicpmv-lab-lora") -> None:
     pushed = merge_and_push.remote(repo_id=repo_id, adapter_dir=adapter_dir)
-    print(f"\nDone. On the Space set:  ZEROGPU_MODEL_ID={pushed}")
-    print("Rebuild the Space -> the fine-tuned model is live (Well-Tuned badge).")
+    print(f"\nDone. Update DEFAULT_HF_REPO in src/model_paths.py to {pushed!r}")
+    print("(or set ZEROGPU_MODEL_ID on the Space), then redeploy.")