docs/REMAINING_WORK.md

Blood Test Explainer — Remaining Work

For: Dimitris + agents
Repo: r0m4k/blood-test-explainer
Space: build-small-hackathon/blood-test-explainer
Last updated: 2026-06-13
Suggested order: 1 → 2 → 3 & 4 (parallel) → 5 → 6

---

Status snapshot

Area	Now
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
Fine-tune pipeline	train/modal_finetune.py → merge → Hub push
Article / demo video	Not started

---

1. Insert the custom model

Owner: Dimitris (Modal + HF Space vars)

• Fine-tuned Transformers repo on Hub: build-small-hackathon/blood-test-minicpmv-4_6-medreason
• 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 in production; we have a before/after metric for the article.

---

2. Fine-tune app wording

Owner: Dimitris or copy agent

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 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)

Done when: Hero + upload + report readable in under 60 seconds.

---

3. Enlarge the knowledge graph

Owner: Agent task (Dimitris to review)

Tools: src/markers.py, kb/knowledge_base.py, scripts/expand_lab_knowledge_graph.py, kb/cbc_knowledge_graph.json

• Expand canonical markers in src/markers.py (target: 150–200 common lab markers)
• For each marker: description, importance, food/exercise/supplement guidance, age/sex stats (cite MedlinePlus / kb/references/)
• Add IDs to MARKER_IDS in scripts/expand_lab_knowledge_graph.py
• Run python scripts/expand_lab_knowledge_graph.py
• Run pytest tests/test_report_pipeline.py
• Spot-check 10 markers in UI after a real PDF upload

Done when: KG covers target marker list; multi-panel PDFs enrich correctly.

---

4. Marker video review (per marker)

Owner: Agent task (Dimitris to review)

Tools: kb/marker_videos.json, scripts/expand_lab_knowledge_graph.py, app.py (_youtube_embed_html)

• Replace generic reused YouTube URLs with marker- or category-specific explainers
• Prefer: MedlinePlus, NHS, Cleveland Clinic, Osmosis-style education
• Avoid: treatment promises, irrelevant content
• Use category fallback when no single-marker video exists (CBC, liver, lipids, thyroid, etc.)
• Regenerate graph; QA embeds on high / low / normal marker cards

Done when: ≥80% markers have unique or category-specific videos; no empty video_url.

---

5. Create an article

Owner: Dimitris (+ Roman review)

Publish to: HF blog / Devpost / LinkedIn (pick one primary)

• Problem → approach (vision extract + deterministic KB, not LLM medical facts)
• Fine-tune story + before/after numbers from eval/before_after.json
• Architecture: Gradio + ZeroGPU, no hosted API
• 2 screenshots + Space link
• Limitations + disclaimer
• Links: Space, model repo, GitHub

Blocked by: #1 (custom model live), #2 (copy pass), metrics from eval.

---

6. Demo video (Laytimely-style)

Owner: Dimitris

• Script (~400–600 words): hook → upload → trace → report → one marker → disclaimer
• AI voiceover (same stack as Laytimely)
• Screen record Space or local app; strong PDF (02_cbc_umc_johndoe.pdf or 06_drlogy_cbc.pdf)
• Show trace hover, marker card, embedded YouTube
• Royalty-free background music under voice (−18 to −24 dB)
• Captions + title/end cards with Space URL
• Publish (YouTube unlisted or HF README embed); link in article + submission

Blocked by: #1, #2, ideally #3/#4 so demo looks polished.

---

Submission checklist

• Custom model wired in code (DEFAULT_HF_REPO); [ ] confirm on live Space after deploy
• Before/after eval documented
• Copy + badges accurate
• KG + videos polished
• Article published
• Demo video with AI voice + music
• README / Space card matches final story

---

Key paths

Path	Purpose
train/modal_finetune.py	LoRA train + merge + Hub push
train/modal_eval.py	Base vs fine-tuned comparison
eval/data/real/	Real PDFs + labels
scripts/expand_lab_knowledge_graph.py	Regenerate KB JSON
kb/marker_videos.json	Video catalog
README.md, RUNBOOK.md, DEPLOY.md	Deployment + llama.cpp docs

Agent notes

• Default extraction: EXTRACTOR_BACKEND=transformers — do not change unless badge work requires llama.cpp.
• Do not commit model weights, tokens, or PHI.
• Push to origin (GitHub) and space (HF) after merged changes on main.
• Workflow details: RUNBOOK.md