Add Modal LoRA training launcher

Co-authored-by: Codex <codex@openai.com>

FIELD_NOTES.md

@@ -82,3 +82,9 @@ Deployment rule: publish or deploy a LoRA adapter only if it improves valid JSON
 Latest Discord discussion surfaced MiniCPM4.1 Transformers issues around SDPA attention masks and gibberish output. Jawbreaker now defaults `JAWBREAKER_ATTENTION_IMPLEMENTATION=eager` for the MiniCPM path, and keeps fallback analysis visible in the documentation.
 
 Guardrail: winning matters, but not by overclaiming. The project should not claim Well-Tuned, real user validation, Modal usage, or llama.cpp deployment unless those things are actually completed and documented.
+
+## 2026-06-06 Modal Training Plan
+
+Modal credits are the right place to run the MiniCPM LoRA job. Added `training/modal_train.py` so the same generated train/dev split can run on an A100 with outputs stored in a Modal volume.
+
+Claim rule: Modal usage becomes a submission claim only after a real Modal run completes. Well-Tuned becomes a claim only after the resulting adapter is published and beats the base model or fallback on eval.

HONEST_SUBMISSION.md

@@ -30,6 +30,7 @@ Jawbreaker should compete hard without gaming the hackathon.
 - `training/data/test.jsonl` and `eval/generated_eval.jsonl` are holdout data and should not be used for LoRA training.
 - A LoRA adapter should only be deployed if it improves valid JSON and safety metrics without increasing dangerous false negatives.
 - If synthetic training mostly teaches format-following, say that. Do not describe it as learning from real scam victims.
+- If Modal is used, include the Modal command, training output, and whether an adapter was actually published.
 
 ## Demo Rules
 

requirements-train.txt

@@ -1,5 +1,6 @@
 accelerate==1.12.0
 datasets>=4.4.0,<5.0
+modal>=1.0.0,<2.0
 peft>=0.18.0,<1.0
 torch==2.9.1
 transformers==4.57.3

training/README.md

@@ -66,6 +66,39 @@ python3 training/train_lora.py \
   --output-dir training/output/jawbreaker-minicpm-lora
 ```
 
+## Fine-Tune on Modal
+
+Modal is the preferred training path because the hackathon gives Modal credits and MiniCPM4.1-8B should be trained on real GPU hardware, not inside the Hugging Face Space runtime.
+
+One-time local setup:
+
+```bash
+pip install modal
+modal setup
+```
+
+Create a Modal secret named `huggingface-secret` with an `HF_TOKEN` value that can read the base model and push to your Hugging Face account:
+
+```bash
+modal secret create huggingface-secret HF_TOKEN=hf_...
+```
+
+Run training on Modal:
+
+```bash
+modal run training/modal_train.py
+```
+
+Publish the adapter for the Well-Tuned badge only after eval says it is better:
+
+```bash
+modal run training/modal_train.py \
+  --push-to-hub \
+  --hub-model-id gowtham0992/jawbreaker-minicpm-lora
+```
+
+The Modal job writes checkpoints to the `jawbreaker-training` Modal volume under `/outputs`.
+
 To publish the adapter for the Well-Tuned badge:
 
 ```bash

training/modal_train.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import modal
+
+
+APP_NAME = "jawbreaker-minicpm-lora"
+REMOTE_ROOT = Path("/workspace")
+REMOTE_OUTPUT = Path("/outputs")
+LOCAL_ROOT = Path(__file__).resolve().parents[1]
+
+
+image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .pip_install(
+        "accelerate==1.12.0",
+        "datasets>=4.4.0,<5.0",
+        "huggingface-hub>=0.34.0,<1.0",
+        "peft>=0.18.0,<1.0",
+        "sentencepiece>=0.2.0,<1.0",
+        "torch==2.9.1",
+        "transformers==4.57.3",
+    )
+    .add_local_dir(LOCAL_ROOT / "jawbreaker", remote_path=REMOTE_ROOT / "jawbreaker")
+    .add_local_dir(LOCAL_ROOT / "training", remote_path=REMOTE_ROOT / "training")
+    .add_local_dir(LOCAL_ROOT / "eval", remote_path=REMOTE_ROOT / "eval")
+)
+
+app = modal.App(APP_NAME, image=image)
+volume = modal.Volume.from_name("jawbreaker-training", create_if_missing=True)
+
+
+@app.function(
+    gpu="A100",
+    timeout=6 * 60 * 60,
+    volumes={REMOTE_OUTPUT: volume},
+    secrets=[modal.Secret.from_name("huggingface-secret", required_keys=["HF_TOKEN"])],
+)
+def train_lora(
+    model_id: str = "openbmb/MiniCPM4.1-8B",
+    output_name: str = "jawbreaker-minicpm-lora",
+    epochs: float = 1.0,
+    push_to_hub: bool = False,
+    hub_model_id: str | None = None,
+) -> None:
+    import os
+    import subprocess
+
+    os.chdir(REMOTE_ROOT)
+    output_dir = REMOTE_OUTPUT / output_name
+    cmd = [
+        "python",
+        "training/train_lora.py",
+        "--model-id",
+        model_id,
+        "--train-file",
+        "training/data/train.jsonl",
+        "--dev-file",
+        "training/data/dev.jsonl",
+        "--output-dir",
+        str(output_dir),
+        "--epochs",
+        str(epochs),
+    ]
+    if push_to_hub:
+        cmd.append("--push-to-hub")
+        if hub_model_id:
+            cmd.extend(["--hub-model-id", hub_model_id])
+
+    subprocess.run(cmd, check=True)
+    volume.commit()
+
+
+@app.local_entrypoint()
+def main(
+    model_id: str = "openbmb/MiniCPM4.1-8B",
+    output_name: str = "jawbreaker-minicpm-lora",
+    epochs: float = 1.0,
+    push_to_hub: bool = False,
+    hub_model_id: str | None = None,
+) -> None:
+    train_lora.remote(
+        model_id=model_id,
+        output_name=output_name,
+        epochs=epochs,
+        push_to_hub=push_to_hub,
+        hub_model_id=hub_model_id,
+    )