README.md

---
title: Medical Notes Using Google MedGemma and MedASR
emoji: 🩺
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "6.20.0"
app_file: app.py
pinned: false
short_description: Turns a raw clinical recording into a structured SOAP note.
---

# Medical Notes Using Google MedGemma and MedASR

Pipeline: audio file -> MedASR (transcription) -> MedGemma 4B, `google/medgemma-4b-it`
(SOAP note) -> Gradio UI.

This takes a raw clinical recording and turns it into a structured SOAP
note, attributed by speaker, without inventing anything that wasn't
actually said.

> **Not a diagnostic tool.** For demonstration/research use only — don't
> upload real patient data.

Both models are gated on the Hugging Face Hub, so whichever environment runs
this needs an HF token with access to `google/medasr` and `google/medgemma-4b-it`.

## Setup (local)

```bash
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
hf auth login   # token needs access to the gated google/medasr and google/medgemma-4b-it repos
```

Model weights are pulled straight from the Hub on first run (no local
`models/` download step needed anymore). To point at a local copy instead,
set `MEDASR_MODEL_ID` / `MEDGEMMA_MODEL_ID` to a local directory.

## Run (local)

```bash
python app.py
```

Opens a local Gradio app: pick a wav/mp3 file, click Run, see the MedASR
transcript, the generated SOAP note, and per-step timing.

## Deploying to Hugging Face Spaces (ZeroGPU)

1. Create a Space with SDK "Gradio" and hardware "ZeroGPU".
2. Push this repo's contents to the Space: `app.py`, `llm.py`,
   `requirements.txt`, `README.md`, `test_audio/clips/*.wav`.
3. In the Space's Settings -> Variables and secrets, add a secret `HF_TOKEN`
   set to a token with access to the gated `google/medasr` and
   `google/medgemma-4b-it` repos. `huggingface_hub` reads this automatically.
4. `llm.py`'s `run_pipeline` is decorated with `@spaces.GPU`, so ZeroGPU
   attaches a GPU only for the duration of that call; both the ASR and
   SOAP-note models load lazily on first invocation.