feat: Well-Tuned + Llama Champion groundwork

- finetune/train_modal.py: QLoRA fine-tune of MiniCPM4-8B on SQuAD pairs
formatted with the production prompt, merged and pushed to the Hub
- finetune/convert_gguf_modal.py: GGUF f16 + Q4_K_M conversion of the
fine-tuned model, pushed to a -GGUF repo
- model/llm.py: llama.cpp runtime backend (LlamaCppLLM) selected via
PAPERPROF_RUNTIME=llamacpp, transformers stays the default

finetune/convert_gguf_modal.py

@@ -0,0 +1,121 @@
+"""
+finetune/convert_gguf_modal.py — Convert the fine-tuned model to GGUF for llama.cpp.
+
+Pulls build-small-hackathon/MiniCPM4-8B-PaperProf, converts to GGUF f16 with
+llama.cpp's convert script, quantizes to Q4_K_M, and pushes both files to
+build-small-hackathon/MiniCPM4-8B-PaperProf-GGUF.
+
+Run (after the fine-tune has been pushed):
+    modal run finetune/convert_gguf_modal.py
+"""
+
+import modal
+
+SRC_REPO = "build-small-hackathon/MiniCPM4-8B-PaperProf"
+GGUF_REPO = "build-small-hackathon/MiniCPM4-8B-PaperProf-GGUF"
+
+app = modal.App("paperprof-gguf")
+
+image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .apt_install("git", "cmake", "build-essential", "curl")
+    .run_commands(
+        "git clone --depth 1 https://github.com/ggml-org/llama.cpp /llama.cpp",
+        "cmake -S /llama.cpp -B /llama.cpp/build -DGGML_NATIVE=OFF",
+        "cmake --build /llama.cpp/build --target llama-quantize -j",
+    )
+    .pip_install(
+        "torch==2.6.0",
+        "transformers==4.57.1",
+        "sentencepiece",
+        "huggingface_hub",
+    )
+    .run_commands("pip install -r /llama.cpp/requirements/requirements-convert_hf_to_gguf.txt")
+)
+
+MODEL_CARD = f"""---
+license: apache-2.0
+base_model: {SRC_REPO}
+tags:
+  - gguf
+  - llama.cpp
+  - question-generation
+  - education
+  - paperprof
+language:
+  - en
+---
+
+# MiniCPM4-8B-PaperProf-GGUF
+
+GGUF quantizations of [{SRC_REPO}](https://huggingface.co/{SRC_REPO}),
+the fine-tuned exam-question generator behind
+[PaperProf](https://huggingface.co/spaces/build-small-hackathon/PaperProf).
+
+| File | Quant | Size | Use |
+|---|---|---|---|
+| `minicpm4-8b-paperprof-Q4_K_M.gguf` | Q4_K_M | ~4.9 GB | recommended, used by the Space |
+| `minicpm4-8b-paperprof-f16.gguf` | F16 | ~16 GB | full precision reference |
+
+## Usage with llama.cpp
+
+```bash
+llama-cli -hf {GGUF_REPO} -p "your prompt"
+```
+
+## Usage with llama-cpp-python
+
+```python
+from llama_cpp import Llama
+llm = Llama.from_pretrained("{GGUF_REPO}", filename="*Q4_K_M.gguf", n_gpu_layers=-1)
+```
+
+Built for the Build Small Hackathon, June 2026, by Team PaperProf (EPITA).
+"""
+
+
+@app.function(
+    image=image,
+    timeout=2 * 60 * 60,
+    cpu=8,
+    memory=65536,
+    ephemeral_disk=120 * 1024,
+    secrets=[modal.Secret.from_name("paperprof-hf")],
+)
+def convert():
+    import os
+    import subprocess
+    from huggingface_hub import snapshot_download, HfApi
+
+    token = os.environ["HF_TOKEN"]
+    api = HfApi(token=token)
+
+    print(f"[pull] downloading {SRC_REPO}…")
+    src = snapshot_download(SRC_REPO, token=token, local_dir="/tmp/src")
+
+    f16 = "/tmp/minicpm4-8b-paperprof-f16.gguf"
+    q4 = "/tmp/minicpm4-8b-paperprof-Q4_K_M.gguf"
+
+    print("[convert] HF → GGUF f16…")
+    subprocess.run(
+        ["python", "/llama.cpp/convert_hf_to_gguf.py", src, "--outfile", f16, "--outtype", "f16"],
+        check=True,
+    )
+
+    print("[quantize] f16 → Q4_K_M…")
+    subprocess.run(
+        ["/llama.cpp/build/bin/llama-quantize", f16, q4, "Q4_K_M"],
+        check=True,
+    )
+
+    print(f"[push] uploading to {GGUF_REPO}…")
+    api.create_repo(GGUF_REPO, exist_ok=True)
+    api.upload_file(path_or_fileobj=q4, path_in_repo=os.path.basename(q4), repo_id=GGUF_REPO)
+    api.upload_file(path_or_fileobj=f16, path_in_repo=os.path.basename(f16), repo_id=GGUF_REPO)
+    api.upload_file(path_or_fileobj=MODEL_CARD.encode(), path_in_repo="README.md", repo_id=GGUF_REPO)
+    print(f"[done] https://huggingface.co/{GGUF_REPO}")
+
+
+@app.local_entrypoint()
+def main():
+    convert.remote()

finetune/train_modal.py

@@ -0,0 +1,224 @@
+"""
+finetune/train_modal.py — QLoRA fine-tune of MiniCPM4-8B for PaperProf.
+
+Task: exam-question generation. The training data is SQuAD passages and
+questions reformatted into the EXACT production prompt used by
+core/questioner.py, so the model learns PaperProf's task, not generic QA.
+
+Run:
+    modal run finetune/train_modal.py
+
+Output:
+    Merged bf16 model pushed to hf.co/build-small-hackathon/MiniCPM4-8B-PaperProf
+"""
+
+import modal
+
+APP_NAME = "paperprof-finetune"
+BASE_MODEL = "openbmb/MiniCPM4-8B"
+HUB_REPO = "build-small-hackathon/MiniCPM4-8B-PaperProf"
+N_SAMPLES = 3000
+MAX_LEN = 1024
+
+app = modal.App(APP_NAME)
+
+image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .pip_install(
+        "torch==2.6.0",
+        "transformers==4.57.1",
+        "datasets==3.2.0",
+        "peft==0.14.0",
+        "bitsandbytes==0.46.0",
+        "accelerate>=1.8.0",
+        "huggingface_hub",
+        "sentencepiece",
+    )
+)
+
+# Mirror of core/questioner.py _PROMPT_TEMPLATE (Normal difficulty)
+PROMPT_TEMPLATE = """\
+You are a university professor creating exam questions.
+Given the following excerpt from a course, write ONE focused question.
+
+Difficulty — Ask for conceptual understanding (Explain X. Why does X happen?).
+
+Rules:
+- ONE question only, on ONE concept
+- Maximum 25 words
+- No sub-questions, no "and", no compound questions
+- IMPORTANT: Always write the question in English, even if the source text is in another language
+- Output only the question, nothing else
+
+Excerpt:
+{chunk}
+
+Question:"""
+
+MODEL_CARD = f"""---
+license: apache-2.0
+base_model: {BASE_MODEL}
+tags:
+  - question-generation
+  - education
+  - lora
+  - paperprof
+datasets:
+  - squad
+language:
+  - en
+---
+
+# MiniCPM4-8B-PaperProf
+
+Fine-tuned from [{BASE_MODEL}](https://huggingface.co/{BASE_MODEL}) for
+**exam-question generation** in [PaperProf](https://huggingface.co/spaces/build-small-hackathon/PaperProf),
+an AI study buddy that turns course PDFs into interactive quiz sessions.
+
+## Training
+
+- **Method:** QLoRA (4-bit NF4, r=16, alpha=32, all-linear targets), merged to bf16
+- **Data:** {N_SAMPLES} SQuAD passage/question pairs reformatted into PaperProf's
+  production prompt template, so the model is optimized for the exact task it
+  serves: one focused, concise exam question per course excerpt.
+- **Epochs:** 1, lr 2e-4 cosine, bf16 compute
+
+## Usage
+
+Drop-in replacement for the base model:
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+tok = AutoTokenizer.from_pretrained("{HUB_REPO}", trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained("{HUB_REPO}", trust_remote_code=True, torch_dtype="bfloat16")
+```
+
+Built for the Build Small Hackathon, June 2026, by Team PaperProf (EPITA).
+"""
+
+
+@app.function(
+    image=image,
+    gpu="A100-80GB",
+    timeout=3 * 60 * 60,
+    secrets=[modal.Secret.from_name("paperprof-hf")],
+)
+def train():
+    import os
+    import torch
+    from datasets import load_dataset
+    from transformers import (
+        AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig,
+        Trainer, TrainingArguments, DataCollatorForLanguageModeling,
+    )
+    from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
+    from huggingface_hub import HfApi
+
+    token = os.environ["HF_TOKEN"]
+
+    # ── Data: SQuAD → production prompt format ────────────────────────────
+    print("[data] loading SQuAD…")
+    ds = load_dataset("squad", split="train")
+    seen, rows = set(), []
+    for ex in ds:
+        ctx = ex["context"].strip()
+        if not (300 <= len(ctx) <= 1500) or ctx in seen:
+            continue
+        seen.add(ctx)
+        q = ex["question"].strip()
+        if not q.endswith("?") or len(q.split()) > 25:
+            continue
+        rows.append({"chunk": ctx, "question": q})
+        if len(rows) >= N_SAMPLES:
+            break
+    print(f"[data] {len(rows)} training pairs")
+
+    tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True, token=token)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    def to_text(row):
+        messages = [
+            {"role": "user", "content": PROMPT_TEMPLATE.format(chunk=row["chunk"])},
+            {"role": "assistant", "content": row["question"]},
+        ]
+        return tokenizer.apply_chat_template(messages, tokenize=False)
+
+    texts = [to_text(r) for r in rows]
+
+    def tokenize(batch):
+        return tokenizer(batch["text"], truncation=True, max_length=MAX_LEN, padding=False)
+
+    from datasets import Dataset
+    train_ds = Dataset.from_dict({"text": texts}).map(
+        tokenize, batched=True, remove_columns=["text"]
+    )
+
+    # ── Model: 4-bit base + LoRA ──────────────────────────────────────────
+    print("[model] loading base in 4-bit…")
+    bnb = BitsAndBytesConfig(
+        load_in_4bit=True,
+        bnb_4bit_quant_type="nf4",
+        bnb_4bit_compute_dtype=torch.bfloat16,
+        bnb_4bit_use_double_quant=True,
+    )
+    model = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL, quantization_config=bnb, device_map="auto",
+        trust_remote_code=True, token=token,
+    )
+    model = prepare_model_for_kbit_training(model)
+    lora = LoraConfig(
+        r=16, lora_alpha=32, lora_dropout=0.05,
+        target_modules="all-linear", task_type="CAUSAL_LM",
+    )
+    model = get_peft_model(model, lora)
+    model.print_trainable_parameters()
+
+    # ── Train ─────────────────────────────────────────────────────────────
+    args = TrainingArguments(
+        output_dir="/tmp/out",
+        num_train_epochs=1,
+        per_device_train_batch_size=4,
+        gradient_accumulation_steps=4,
+        learning_rate=2e-4,
+        lr_scheduler_type="cosine",
+        warmup_ratio=0.03,
+        bf16=True,
+        logging_steps=10,
+        save_strategy="no",
+        report_to=[],
+        gradient_checkpointing=True,
+    )
+    collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)
+    trainer = Trainer(model=model, args=args, train_dataset=train_ds, data_collator=collator)
+    print("[train] starting…")
+    trainer.train()
+
+    # ── Merge LoRA into bf16 base and push ───────────────────────────────
+    print("[merge] reloading base in bf16 and merging adapter…")
+    model.save_pretrained("/tmp/adapter")
+    del model, trainer
+    torch.cuda.empty_cache()
+
+    from peft import PeftModel
+    base = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL, torch_dtype=torch.bfloat16, device_map="auto",
+        trust_remote_code=True, token=token,
+    )
+    merged = PeftModel.from_pretrained(base, "/tmp/adapter")
+    merged = merged.merge_and_unload()
+
+    print(f"[push] uploading to {HUB_REPO}…")
+    merged.push_to_hub(HUB_REPO, token=token, private=False)
+    tokenizer.push_to_hub(HUB_REPO, token=token)
+    HfApi(token=token).upload_file(
+        path_or_fileobj=MODEL_CARD.encode(),
+        path_in_repo="README.md",
+        repo_id=HUB_REPO,
+    )
+    print(f"[done] https://huggingface.co/{HUB_REPO}")
+
+
+@app.local_entrypoint()
+def main():
+    train.remote()

model/llm.py

@@ -12,9 +12,13 @@ Model choice:
     Requires transformers >= 4.50.0.
 
 Environment variables:
-    PAPERPROF_MODEL   Override the default model ID (e.g. "openbmb/MiniCPM3-4B"
-                      for a smaller fallback during local testing).
-    PAPERPROF_DEVICE  "cuda", "mps", or "cpu" (default: auto-detected).
+    PAPERPROF_MODEL      Override the default model ID (e.g. "openbmb/MiniCPM3-4B"
+                         for a smaller fallback during local testing).
+    PAPERPROF_DEVICE     "cuda", "mps", or "cpu" (default: auto-detected).
+    PAPERPROF_RUNTIME    "transformers" (default) or "llamacpp" to run the GGUF
+                         model through the llama.cpp runtime instead.
+    PAPERPROF_GGUF_REPO  GGUF repo for the llamacpp runtime
+                         (default: build-small-hackathon/MiniCPM4-8B-PaperProf-GGUF).
 
 Public API:
     get_llm() -> LLM          — return the singleton instance
@@ -101,9 +105,41 @@ class LLM:
         return output[0]["generated_text"]
 
 
+DEFAULT_GGUF_REPO = "build-small-hackathon/MiniCPM4-8B-PaperProf-GGUF"
+
+
+class LlamaCppLLM:
+    """Same .generate() interface as LLM, backed by the llama.cpp runtime."""
+
+    def __init__(self, repo_id: str):
+        from llama_cpp import Llama
+
+        n_gpu_layers = -1 if torch.cuda.is_available() else 0
+        print(f"[LlamaCppLLM] loading {repo_id} (n_gpu_layers={n_gpu_layers})")
+        self._llm = Llama.from_pretrained(
+            repo_id=repo_id,
+            filename="*Q4_K_M.gguf",
+            n_gpu_layers=n_gpu_layers,
+            n_ctx=4096,
+            verbose=False,
+        )
+
+    def generate(self, prompt: str, max_new_tokens: int = DEFAULT_MAX_NEW_TOKENS) -> str:
+        out = self._llm.create_chat_completion(
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=max_new_tokens,
+            temperature=0.0,
+        )
+        return out["choices"][0]["message"]["content"]
+
+
 @lru_cache(maxsize=1)
-def get_llm() -> LLM:
+def get_llm():
     """Return the singleton LLM, loading the model on first call."""
+    runtime = os.environ.get("PAPERPROF_RUNTIME", "transformers").lower()
+    if runtime == "llamacpp":
+        repo_id = os.environ.get("PAPERPROF_GGUF_REPO", DEFAULT_GGUF_REPO)
+        return LlamaCppLLM(repo_id=repo_id)
     model_id = os.environ.get("PAPERPROF_MODEL", DEFAULT_MODEL_ID)
     device = os.environ.get("PAPERPROF_DEVICE", "auto")
     return LLM(model_id=model_id, device=device)