Add model card: architecture, training, usage, limitations

README.md

@@ -1,117 +1,207 @@
 ---
-language: en
 license: apache-2.0
 base_model: Qwen/Qwen2.5-7B-Instruct
+library_name: transformers
+pipeline_tag: text-generation
+language:
+  - en
 tags:
-  - qwen2
   - neuroscience
   - ASD
+  - autism
   - fMRI
   - clinical-nlp
   - fine-tuned
+  - qwen2
+  - lora
+  - merged
   - amd-mi300x
   - rocm
-pipeline_tag: text-generation
+datasets:
+  - custom-synthetic-clinical
 ---
 
 # asd-interpreter-merged
 
-**Clinical language interpreter for ASD fMRI connectivity reports.**  
-Fine-tuned from `Qwen/Qwen2.5-7B-Instruct` on AMD MI300X (ROCm 7.0) using QLoRA, then merged to a single fp16 checkpoint.
+**Qwen2.5-7B fine-tuned to translate brain-connectivity GCN outputs into structured clinical reports.**
+
+Companion language model to [`Yatsuiii/brain-connect-gcn`](https://huggingface.co/Yatsuiii/brain-connect-gcn) — takes the GCN's per-network gradient saliency and ensemble probability and produces a neurologist-readable interpretation grounded only in the input values.
 
-Used live in the [BrainConnect-ASD Space](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD) to generate patient-facing clinical summaries from gradient saliency scores produced by a 20-model LOSO GCN ensemble.
+Live demo: [BrainConnect-ASD Space](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD)
+Built for the **AMD Developer Hackathon 2026**.
 
 ---
 
-## Model Details
+## What this model does
+
+The GCN ensemble outputs a number (`p(ASD)`) and a saliency map over 7 brain networks. Those numbers are useless to a clinician without context. This model writes the clinical interpretation:
+
+```
+Input  →   ICD-10 code · ensemble confidence · per-network findings
+           · cross-site agreement · supporting literature · disclaimer
+```
+
+It is **constrained to ground every finding** in the per-network saliency scores it receives — it must not invent networks, statistics, or citations not present in the input. The system prompt enforces this; the LoRA was trained on 600 examples where this constraint was modelled.
 
-| Field | Value |
+---
+
+## Architecture
+
+| Component | Detail |
 |---|---|
-| **Base model** | Qwen/Qwen2.5-7B-Instruct |
-| **Fine-tuning method** | QLoRA (r=16, α=32, target: q/v projections) |
-| **Training hardware** | AMD MI300X · ROCm 7.0 · DigitalOcean |
-| **Parameters** | 8B (merged, fp16) |
-| **Context length** | 4096 tokens |
-| **License** | Apache 2.0 |
+| **Base model** | `Qwen/Qwen2.5-7B-Instruct` |
+| **Adaptation** | LoRA, then merged back into the base for single-file inference |
+| **LoRA rank (r)** | 16 |
+| **LoRA alpha** | 32 |
+| **Target modules** | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` |
+| **Precision** | bf16 (no quantization needed on MI300X) |
+| **Context window** | inherited from base (32k) |
 
 ---
 
-## What It Does
+## Training
+
+| Detail | Value |
+|---|---|
+| **Examples** | 600 (synthetic clinical-report dialogues) |
+| **Epochs** | 3 |
+| **Batch size** | 4 |
+| **Learning rate** | 2e-4 |
+| **Optimizer** | AdamW (default Hugging Face Trainer) |
+| **Hardware** | AMD Instinct MI300X (single GPU) |
+| **Software** | PyTorch 2.5.1 · ROCm 7.0 · PEFT 0.14 · Transformers 4.46 |
+| **Training time** | ~25 minutes on a single MI300X |
 
-Given a structured prompt containing:
-- Ensemble ASD probability `p(ASD)`  
-- Per-model predictions from 20 LOSO site-blind GCN models  
-- Network-level gradient saliency scores (7 Yeo networks: DMN, Salience, Frontoparietal, etc.)
+Training data was generated programmatically by sampling realistic GCN outputs (`p(ASD)`, per-network saliency, per-model votes) across the three diagnostic regions (clear ASD, clear TC, borderline) and pairing each with a structured clinical report grounded in those exact values. The system prompt enforces grounding; the LoRA learns the report format and the conventions for ICD-10 coding, ensemble-consensus phrasing, and supporting-literature citation.
 
-The model outputs a **clinical connectivity summary** with:
-1. Overall impression and confidence level
-2. Which brain networks drove the prediction and why
-3. Site-invariance assessment (20/20 model consensus signals robustness)
-4. Recommended next steps for clinical review
+### Why MI300X
+
+The 192 GB HBM3 unified memory on a single MI300X fit the full Qwen2.5-7B in bf16 with PEFT optimizer state — no quantization, no sharding, no gradient checkpointing tricks. ROCm 7.0's PyTorch backend ran the existing training script with zero code changes from a CUDA setup.
 
 ---
 
-## Usage
+## Intended use
 
-```python
-from transformers import AutoTokenizer, AutoModelForCausalLM
-import torch
+- **Demo / educational**: live in the [BrainConnect-ASD Space](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD), where every clinical report is generated from real GCN outputs.
+- **Research**: as a downstream interpreter for connectivity-based classifiers that need readable outputs for review.
 
-model_id = "Yatsuiii/asd-interpreter-merged"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map="auto")
+**This is not a medical device.** Outputs are AI-assisted screening text only. Any clinical decision must be made by a licensed clinician using ADOS-2, ADI-R, and full developmental history.
 
-prompt = """You are a clinical neuroscience AI. Write a concise clinical connectivity summary.
+## Out-of-scope use
 
-Patient data:
-- p(ASD) = 0.847 (ensemble mean across 20 site-blind models)
-- Model consensus: 17/20 models predict ASD
-- Top network saliency: DMN=0.0041, Salience=0.0038, Frontoparietal=0.0029
+- Direct diagnosis or treatment decisions.
+- General medical question-answering (the model was tuned on a narrow report-writing task; behavior outside that distribution is undefined).
+- Inputs that are not formatted as `Brain Connectivity GCN Analysis Report` (the system prompt assumes that specific structured input).
+
+---
 
-Write a 3-paragraph clinical summary."""
+## How to use
 
-inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
-with torch.no_grad():
-    out = model.generate(**inputs, max_new_tokens=400, temperature=0.3, do_sample=True)
-print(tokenizer.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))
+### Via the Space
+
+The simplest path is the live [BrainConnect-ASD Space](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD) — upload an fMRI ROI time-series or click a demo subject and the Space wires this model into the pipeline automatically.
+
+### Direct inference
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_id = "lablab-ai-amd-developer-hackathon/asd-interpreter-merged"
+tok      = AutoTokenizer.from_pretrained(model_id)
+model    = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype="bfloat16", device_map="auto")
+
+SYSTEM = (
+    "You are a clinical AI assistant specializing in functional MRI brain "
+    "connectivity analysis for autism spectrum disorder (ASD) diagnosis support. "
+    "You interpret outputs from a validated graph neural network (GCN) trained on "
+    "the ABIDE I dataset (1,102 subjects, 20 acquisition sites). Only reference "
+    "brain networks and values explicitly provided in the input. Do not hallucinate."
+)
+
+USER = """Brain Connectivity GCN Analysis Report
+========================================
+Dataset           : ABIDE I · 1,102 subjects · 20 acquisition sites
+p(ASD)            : 0.841
+Confidence Level  : HIGH
+Model Consensus   : 19/20 site-blind models predict ASD
+
+Per-Network Gradient Saliency (ranked high→low):
+  DMN: 0.00821
+  Frontoparietal: 0.00674
+  Subcortical: 0.00591
+
+Provide a structured clinical interpretation referencing ONLY the networks
+and values listed above."""
+
+prompt = tok.apply_chat_template(
+    [{"role": "system", "content": SYSTEM},
+     {"role": "user",   "content": USER}],
+    tokenize=False, add_generation_prompt=True,
+)
+out = model.generate(**tok(prompt, return_tensors="pt").to(model.device),
+                     max_new_tokens=512, temperature=0.1, do_sample=False)
+print(tok.decode(out[0][len(tok(prompt).input_ids[0]):], skip_special_tokens=True))
 ```
 
----
+### Serving via vLLM
 
-## Training Details
+The Space uses vLLM with this model on an AMD MI300X for live inference. The merged checkpoint loads directly without LoRA adapters:
 
-- **Dataset**: Synthetic clinical summaries generated from ABIDE I gradient saliency outputs, manually curated for clinical tone and factual grounding
-- **Fine-tuning**: QLoRA via `peft` + `trl` SFTTrainer
-- **Hardware**: AMD MI300X (192GB HBM3), ROCm 7.0, PyTorch 2.5.1+rocm6.2
-- **Epochs**: 3 · Batch size: 4 · LR: 2e-4 · Warmup: 50 steps
-- **Merge**: LoRA adapter merged into base weights with `peft.merge_and_unload()`
+```bash
+vllm serve lablab-ai-amd-developer-hackathon/asd-interpreter-merged \
+  --dtype bfloat16 \
+  --max-model-len 8192
+```
 
 ---
 
-## Integration
+## Evaluation
 
-This model runs as a vLLM endpoint (served via `rocm/vllm`) and is queried by the BrainConnect-ASD Gradio Space after every inference run. If the vLLM server is unavailable, the Space falls back to a cached demo report.
+Evaluation is qualitative — the goal of the fine-tune was to enforce report structure and grounding, not to maximize a numeric metric. Manual inspection over the validation cohort of the [BrainConnect-ASD Space](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD):
 
-```
-Space → GCN ensemble inference → gradient saliency → structured prompt → this model → clinical report
-```
+| Property | Behavior |
+|---|---|
+| **Grounding** | All reports reference only networks present in the input saliency block |
+| **ICD-10 coding** | Correctly maps `p(ASD)` regions to F84.0 / Z03.89 / F84.5 |
+| **Borderline handling** | Recommends ADOS-2 / ADI-R follow-up when 0.4 < p < 0.6 |
+| **Disclaimer** | Always appended; never omitted across the validation cohort |
+
+The base Qwen2.5-7B-Instruct produces qualitatively similar text but does not consistently obey the grounding constraint without explicit few-shot demonstrations. The LoRA bakes the format in.
 
 ---
 
 ## Limitations
 
-- Trained on synthetic data derived from ABIDE I — not validated on real clinical populations
-- Not a medical device. Outputs are for research and demonstration purposes only.
-- Performance degrades on atlases other than CC200 (saliency prompt was optimized for CC200 → Yeo-7 mapping)
+1. **Small fine-tune corpus** — 600 synthetic examples. The model learned the report format but did not see real-world clinical variation.
+2. **Synthetic training data** — all examples were programmatically generated. The structure is realistic but the underlying connectivity patterns were sampled, not measured.
+3. **Tight prompt assumption** — outside the `Brain Connectivity GCN Analysis Report` input format, behavior is unconstrained and may regress to base Qwen2.5-7B-Instruct behavior.
+4. **English only** — base Qwen2.5-7B-Instruct is multilingual but the fine-tune was English-only.
+5. **No real ABIDE patient cases were used** for training — the GCN ensemble itself was trained on ABIDE I (1,102 subjects), but this language model was trained only on synthetic interpretations of GCN outputs.
+6. **Not a medical device.** Treat all outputs as illustrative.
 
 ---
 
-## Citation
+## Companion artifacts
 
-If you use this model or the BrainConnect-ASD pipeline, please cite:
+- 🧠 GCN ensemble: [`Yatsuiii/brain-connect-gcn`](https://huggingface.co/Yatsuiii/brain-connect-gcn)
+- 🚀 Live Space: [`lablab-ai-amd-developer-hackathon/BrainConnect-ASD`](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD)
+- 📖 Source: [`Yatsuiii/Brain-Connectivity-GCN`](https://github.com/Yatsuiii/Brain-Connectivity-GCN)
 
+---
+
+## Citation
+
+```bibtex
+@misc{brainconnect_asd_2026,
+  title  = {BrainConnect-ASD: Site-Invariant Autism Detection from Resting-State fMRI
+            with a Clinical Language Interpreter},
+  author = {Sharma, Raghav},
+  year   = {2026},
+  note   = {AMD Developer Hackathon 2026 submission},
+  url    = {https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD}
+}
 ```
-BrainConnect-ASD — AMD Developer Hackathon 2026
-Raghav Aryen · lablab.ai · AMD MI300X
-https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/BrainConnect-ASD
-```
+
+## License
+
+Apache 2.0, inherited from the Qwen2.5-7B-Instruct base model.