Update model card: real training details, file listing, corrected usage

README.md

@@ -11,12 +11,12 @@ tags:
   - fine-tuned
 ---
 
-# Qwen3-4B Back-Pain Coaching (LoRA fine-tune, fused)
+# Qwen3-4B Back-Pain Coaching (LoRA fine-tune)
 
-A LoRA fine-tune of `Qwen/Qwen3-4B-Instruct-2507`, fused into the base
-weights, specialized for back-pain coaching conversations: it asks
-structured intake questions, screens for red-flag symptoms, and otherwise
-suggests general exercises, stretches, and lifestyle/diet guidance.
+A LoRA fine-tune of `Qwen/Qwen3-4B-Instruct-2507`, specialized for
+back-pain coaching conversations: it asks structured intake questions,
+screens for red-flag symptoms, and otherwise suggests general exercises,
+stretches, and lifestyle/diet guidance.
 
 **This is not a diagnostic tool** and is not a substitute for professional
 medical advice.
@@ -45,17 +45,46 @@ repo below) that runs *before* the model is ever called and does not
 depend on model behavior. **Deploying this model without an equivalent
 independent safety layer is not the intended or recommended use.**
 
+## Files in this repo
+
+- `adapter_config.json` + `adapters.safetensors` — the trained LoRA
+  adapter (29MB), applied on top of the base model at load time (MLX) or
+  used to fuse/convert to another format
+- `qwen3-4b-instruct-2507-backpain-f16.gguf` — full-precision GGUF (~8GB)
+- `qwen3-4b-instruct-2507-backpain-q4_k_m.gguf` — quantized GGUF (~2.5GB),
+  the one this project actually serves via `llama-cpp-python`
+
+No full fused HF-`transformers`-format safetensors checkpoint is hosted
+here — the adapter was fused directly into an MLX checkpoint and converted
+straight to GGUF, skipping an intermediate HF-format export.
+
+```bash
+hf download ameowra/qwen3-4b-backpain-fused \
+  qwen3-4b-instruct-2507-backpain-q4_k_m.gguf --local-dir models/
+```
+
 ## Training
 
 - **Base model**: `Qwen/Qwen3-4B-Instruct-2507`
-- **Method**: LoRA fine-tuning via `mlx_lm.lora` (MLX, Apple Silicon),
-  fused into the base weights via `mlx_lm.fuse`
-- **Data**: 51 hand-authored chat-format examples across 5 categories —
-  structured intake, exercise/stretch recommendation, diet/lifestyle
-  guidance, red-flag referral, and medical-term explanation — grounded in
-  real sources (Mayo Clinic, NHS Inform, Kaiser, Arthritis UK, Spine
-  Health's glossary) collected via Firecrawl and paraphrased rather than
-  copied verbatim
+- **Method**: LoRA fine-tuning via `mlx_lm.lora` (MLX, Apple Silicon) —
+  rank 8, dropout 0.0, scale 20.0, 16 of 36 layers tuned (7.34M / 4022M
+  trainable params, 0.182%); adam optimizer, lr 1e-5 constant, batch size
+  4, max sequence length 2048; fused into the base weights and converted
+  to GGUF via `llama.cpp`
+- **Data**: 136 hand-authored chat-format examples (110 train / 26 valid,
+  ~27,470 tokens/epoch) across 6 categories — structured intake,
+  exercise/stretch recommendation, diet/lifestyle guidance, red-flag
+  referral, medical-term explanation, and back-muscle anatomy — grounded
+  in real sources (Mayo Clinic, NHS Inform, Kaiser, Arthritis UK, Spine
+  Health's glossary, NCBI StatPearls, TeachMeAnatomy) collected via
+  Firecrawl and paraphrased rather than copied verbatim
+- **Checkpoint selection**: trained for 430 of a nominal 1000 iterations on
+  an Apple M5 Max (~1.7 it/s, ~6 minutes wall clock); validation loss
+  bottomed out at iteration 100 (0.441) and rose steadily after while
+  train loss kept falling — plain overfitting on a small dataset, so
+  iteration 100 was selected rather than the final checkpoint. At this
+  dataset size, ~100-150 iterations is the useful range; a longer run
+  needs more data, not more patience.
 
 ## System prompt
 
@@ -79,8 +108,15 @@ general advice.
 
 ## Limitations
 
-- Small base model (4B parameters) and a small fine-tuning set (51
+- Small base model (4B parameters) and a small fine-tuning set (136
   examples) — expect narrower conversational range than a frontier model
+- Style transfer more than knowledge transfer: the adapter mainly changes
+  *how* the model responds (ask first, screen, defer, stay
+  non-prescriptive) rather than adding back-pain knowledge the base model
+  lacked
+- Single-turn training data — multi-turn conversations work if prior turns
+  are replayed as history, but every training example was one user turn
+  and one reply
 - English only
 - "Call 000" guidance is Australia-specific; adapt for other regions
 - General lifestyle advice only, not personalized clinical guidance
@@ -97,26 +133,32 @@ uv sync --extra inference
 uv run inference/serve.py
 ```
 
-Direct usage via `transformers`:
+Direct usage via MLX, applying the adapter on top of the base model:
 
 ```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+from mlx_lm import load, generate
+from mlx_lm.sample_utils import make_sampler
 
-repo_id = "ameowra/qwen3-4b-backpain-fused"
-tokenizer = AutoTokenizer.from_pretrained(repo_id)
-model = AutoModelForCausalLM.from_pretrained(repo_id)
+model, tokenizer = load(
+    "Qwen/Qwen3-4B-Instruct-2507",
+    adapter_path="path/to/downloaded/adapter_config.json's directory",
+)
 
 messages = [
     {"role": "system", "content": "<see System prompt section above>"},
     {"role": "user", "content": "My lower back has been aching for about a week."},
 ]
-inputs = tokenizer.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt")
-output = model.generate(inputs, max_new_tokens=512)
-print(tokenizer.decode(output[0][inputs.shape[-1]:], skip_special_tokens=True))
+prompt = tokenizer.apply_chat_template(messages, add_generation_prompt=True)
+print(generate(model, tokenizer, prompt=prompt, max_tokens=512,
+               sampler=make_sampler(temp=0.7, top_p=0.9)))
 ```
 
-A quantized GGUF build (for local CPU/GPU inference via `llama.cpp` /
-`llama-cpp-python`) is produced separately by the project pipeline — see
-the project repo for the full training-to-serving pipeline and the
-`ProjectScope.md` design rationale (structured intake, hardcoded safety
-layer, planned RAG grounding, fully local/offline deployment).
+There is no full fused HF-`transformers`-format checkpoint hosted in this
+repo (see "Files in this repo" above) — direct `transformers` usage would
+require fusing the adapter into the base weights yourself first (e.g. via
+`mlx_lm.fuse` then a HF-format export), or using one of the GGUF builds
+via `llama.cpp`/`llama-cpp-python` as shown above, which is what this
+project's own inference server actually does. See the project repo for
+the full training-to-serving pipeline and the `ProjectScope.md` design
+rationale (structured intake, hardcoded safety layer, planned RAG
+grounding, fully local/offline deployment).