---
language:
- en
license: mit
base_model: microsoft/Phi-3.5-mini-instruct
library_name: peft
pipeline_tag: text-generation
datasets:
- AiLLMBS/medquad-patient-friendly-rewrites
tags:
- peft
- lora
- qlora
- phi-3.5
- medquad
- biomedical-nlp
- patient-education
- plain-language
- source-grounded
---

# Phi-3.5 MedQuAD Patient-Friendly Explanation LoRA

This repository contains a LoRA adapter fine-tuned from
[`microsoft/Phi-3.5-mini-instruct`](https://huggingface.co/microsoft/Phi-3.5-mini-instruct)
for **source-grounded patient-friendly rewriting** of medical question-answer content.

The user supplies both a medical question and a source/reference answer. The
adapter rewrites the supplied source answer in clearer language and adds a
standardized educational safety note.

## Important Scope

This is an educational and portfolio model. It is **not** intended for:

- diagnosis;
- treatment recommendation;
- clinical decision support;
- emergency medical advice;
- replacing a healthcare professional;
- answering medical questions without a supplied source answer;
- unsupervised patient communication;
- processing PHI or private medical records.

## Base Model and Adapter

- Base model: `microsoft/Phi-3.5-mini-instruct`
- Adapter type: LoRA / QLoRA-style training
- LoRA rank: `16`
- LoRA alpha: `32`
- LoRA dropout: `0.05`
- Target modules: `down_proj, gate_up_proj, o_proj, qkv_proj`
- Trainable adapter parameters: approximately 25.2 million
- Selected checkpoint: step 200
- Hardware: NVIDIA RTX 5090 32 GB

This repository contains the adapter, tokenizer metadata, and chat template. It
does not contain the full Phi-3.5 base-model weights.

## Dataset

Formatted dataset:

[`AiLLMBS/medquad-patient-friendly-rewrites`](https://huggingface.co/datasets/AiLLMBS/medquad-patient-friendly-rewrites)

The dataset was derived from
[`lavita/MedQuAD`](https://huggingface.co/datasets/lavita/MedQuAD).
Source answers were converted into patient-friendly rewrite targets, then
cleaned and filtered for:

- source keyword retention;
- low verbatim-copy similarity;
- complete answer structure;
- a standardized safety note;
- minimum response length.

Final local split used for training and evaluation:

- Training examples: **895**
- Held-out evaluation examples: **99**
- Total retained examples: **994**

Dataset audit:

- Average target keyword coverage: **64.57%**
- Average target copy ratio: **6.36%**
- Safety-note rate: **100.00%**
- Incomplete-answer count: **0**
- Low-coverage count after filtering: **0**
- Copy-heavy count after filtering: **0**

## Base Model vs LoRA Evaluation

Both variants were evaluated on the same **99**
held-out examples with identical prompts and deterministic decoding.

| Metric | Base Phi-3.5 | LoRA |
|---|---:|---:|
| Source keyword coverage | 71.02% | 58.39% |
| Copy ratio | 5.53% | 6.48% |
| Safety-note rate | 84.85% | 97.98% |
| Exact `Plain-language answer:` header rate | 0.00% | 100.00% |
| Strict structured pass rate | 0.00% | 67.68% |
| Average output characters | 1225.8 | 841.2 |

The LoRA increased safety-note inclusion and exact format compliance, and
reduced average answer length by approximately **31.38%**.
The base model retained more literal source keywords.

### Evaluation Caveat

The strict structured pass rate requires all of the following:

1. source keyword coverage of at least 55%;
2. copy ratio no greater than 90%;
3. a detected safety note; and
4. the exact trained `Plain-language answer:` section header.

Because the base model was not explicitly required to emit that exact header,
the strict pass rate should be interpreted as **structured task compliance**,
not as a measure of clinical correctness or general medical quality.

Keyword overlap is also an imperfect proxy for semantic faithfulness. A valid
paraphrase may receive a lower overlap score, while an unsupported statement can
still share source words.

Detailed aggregate artifacts are included under `evaluation/`.

## Example Input

```text
Medical question:
What are the symptoms of asthma?

Source answer:
Asthma symptoms include wheezing, coughing, chest tightness, and shortness of
breath. Symptoms can vary over time and may be triggered by exercise, allergens,
cold air, or respiratory infections.

Task:
Rewrite the source answer in clear, patient-friendly language. Use only the
provided source answer. Do not add new medical claims. Use short sentences and
include a short safety note.
```

## Example Output

```text
Plain-language answer:
Asthma can cause wheezing, coughing, a tight feeling in the chest, and trouble breathing. These symptoms may come and go. They can become more noticeable during exercise, around allergens, in cold air, or during a respiratory infection.

Important note:
This is educational information, not a diagnosis or treatment plan. Please talk with a qualified healthcare professional about personal medical concerns.
```

## Loading the Adapter

```python
import torch
from peft import PeftModel
from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    BitsAndBytesConfig,
)

base_model_id = "microsoft/Phi-3.5-mini-instruct"
adapter_id = "AiLLMBS/phi35-medquad-patient-explainer-lora"

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
)

tokenizer = AutoTokenizer.from_pretrained(adapter_id)

base_model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    quantization_config=quantization_config,
    device_map="auto",
    dtype=torch.bfloat16,
    attn_implementation="eager",
    trust_remote_code=False,
)

model = PeftModel.from_pretrained(base_model, adapter_id)
model.eval()
```

## Limitations

The adapter may:

- omit source details;
- simplify away important nuance;
- strengthen or narrow a source claim;
- introduce unsupported specificity;
- produce an incomplete answer when generation is truncated;
- perform poorly on questions outside the training distribution.

For example, a source phrase such as `coughing` may be strengthened to `a cough
that doesn't go away`, which adds a duration claim that was not explicitly
provided.

All outputs should be checked against the source answer. This model has not been
clinically validated.

## Responsible Use

Use this adapter only for source-grounded educational rewriting. Do not use it
as an independent medical knowledge system. A qualified professional should
review any output before it is shown to patients or used in healthcare
communication.