all done

.env.example

@@ -0,0 +1,13 @@
+# Google AI Studio API key for cloud Gemma 4
+# Get yours at https://aistudio.google.com
+GEMINI_API_KEY=your_api_key_here
+
+# Whisper model size: tiny, base, small, medium, large-v3
+WHISPER_MODEL=base
+
+# Ollama local model for symptom extraction
+OLLAMA_MODEL=gemma4:e2b
+
+# Cloud Gemma model for SOAP notes, summary, translation
+# Available: gemma-4-26b-a4b-it (faster MoE) or gemma-4-31b-it (most capable)
+CLOUD_MODEL=gemma-4-26b-a4b-it

.gitignore

@@ -0,0 +1,12 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.db
+*.sqlite
+.DS_Store
+venv/
+.venv/
+dist/
+*.egg-info/
+chroma_db/

DEMO_SCRIPT.md

@@ -0,0 +1,238 @@
+# Hospital Copilot — Demo Video Script
+## "The Last Patient"
+
+**Hackathon:** Gemma 4 for Good  
+**Video target runtime:** 3 minutes 30 seconds  
+**Tone:** Emotional, human, hopeful
+
+---
+
+## Logline
+
+> *"In Ghana, one doctor serves an average of 10,000 patients.  
+> After seeing 40 patients, the last one should not get less care than the first."*
+
+---
+
+## Characters
+
+| Role | Description |
+|---|---|
+| **Dr. Kwame Mensah** | Young district hospital doctor, mid-30s, visibly exhausted at end of shift |
+| **Maame Akosua** | Elderly woman, 68, from a rural village, brought in by her grandson |
+| **Kofi** | Grandson, 20s, worried, occasionally translates for his grandmother |
+
+---
+
+## Setting
+
+**Location:** Small district hospital consultation room  
+**Time of day:** Late afternoon — warm golden light, end of a long day  
+**Props needed:**
+- Desk with laptop showing Hospital Copilot
+- Stethoscope, BP cuff
+- Stack of paper files (the visual symbol of burnout)
+- Small fan, pen holder, basic clinic decor
+- Waiting room shot (even 5 people reads as "busy" on camera)
+
+---
+
+## Scene-by-Scene Breakdown
+
+---
+
+### SCENE 1 — The Weight
+**Duration:** 30 seconds | **No dialogue**
+
+> Camera opens on a wall clock: **4:47 PM**
+>
+> Dr. Mensah is hunched over his desk, hand-writing notes from a thick stack of paper files.
+> His eyes are tired. His hand moves slowly.
+>
+> A nurse opens the door:
+> **Nurse:** *"Doctor, one more patient."*
+>
+> He pauses. Looks at the unfinished stack. Then nods.
+> **Dr. Mensah:** *"Send them in."*
+
+**Director note:** Linger on the paper stack. That stack = the problem Hospital Copilot solves.
+
+---
+
+### SCENE 2 — The Patient Arrives
+**Duration:** 20 seconds
+
+> Maame Akosua shuffles in slowly, supported by Kofi.
+> She looks unwell. A little frightened. Out of place.
+>
+> Dr. Mensah stands to greet her warmly — despite his exhaustion.
+> He quietly opens Hospital Copilot on his laptop.
+> He clicks **▶ Start Consultation.**
+>
+> The mic activates. He turns his full attention to her.
+> The laptop screen is visible in the background — words beginning to appear.
+
+**Director note:** The app should be visible but not the focus. The focus is the human connection.
+
+---
+
+### SCENE 3 — The Consultation
+**Duration:** 90 seconds
+
+> Dr. Mensah and Maame Akosua speak. Kofi occasionally translates.
+> The conversation flows naturally — unhurried, warm.
+
+**CONSULTATION SCRIPT:**
+
+> **Doctor:** Good afternoon Maame. How have you been since your last visit?
+>
+> **Patient (Kofi translating):** She says not too well. She has been having headaches every morning for two weeks. Especially at the back of her head.
+>
+> **Doctor:** Has she been taking her blood pressure medication?
+>
+> **Kofi:** She finished her Amlodipine two weeks ago. She could not afford to buy more.
+>
+> **Doctor:** I understand. Let me check her pressure now.
+> *(places BP cuff, reads monitor)*
+> It is 162 over 98 — that is quite high. The headaches are from the blood pressure.
+> Any dizziness? Blurred vision?
+>
+> **Kofi:** Sometimes dizzy when she stands up. No problem with vision.
+>
+> **Doctor:** Any chest pain or shortness of breath?
+>
+> **Kofi:** No.
+>
+> **Doctor:** Good. She needs to restart her Amlodipine — five milligrams every morning.
+> I am also adding Lisinopril, ten milligrams once a day.
+> She must reduce salt, avoid alcohol, walk thirty minutes daily.
+> Come back in two weeks. If she gets severe headache or chest pain — come immediately.
+>
+> **Kofi (to grandmother in Twi):** *...translates...*
+>
+> **Maame Akosua (nodding slowly):** *"Yoo, medaase."* (Okay, thank you.)
+
+**Camera cuts during this scene:**
+- Close-up on Maame Akosua's face — worried but trusting
+- Laptop screen in background: words streaming into transcript in real time
+- Dr. Mensah's hands on the BP cuff — competent, caring
+- The paper stack on the desk — untouched, waiting
+
+---
+
+### SCENE 4 — The Wow Moment
+**Duration:** 60 seconds
+
+> Consultation ends. Dr. Mensah clicks **⏹ End Consultation.**
+>
+> He looks at Maame Akosua kindly while the screen processes.
+> Then clicks **⚡ Generate Notes.**
+>
+> **Camera slowly pushes in on the laptop screen:**
+>
+> — Transcript appears with speaker labels:
+>   *"Doctor: Her pressure is 162 over 98..."*
+>   *"Patient: Sometimes dizzy when she stands up..."*
+>
+> — ICD-10 panel populates:
+>   *"I10 — Essential (primary) hypertension *(confidence: 0.94)*"*
+>
+> — Drug reference appears:
+>   *"Amlodipine (Calcium Channel Blocker) — 5mg once daily..."*
+>   *"Lisinopril (ACE Inhibitor) — 10mg once daily..."*
+>
+> — SOAP note renders, fully formatted with bold section headers
+>
+> — Patient Summary appears in plain English
+>
+> **Dr. Mensah reads the patient summary aloud, slowly, to Kofi:**
+> *"Your grandmother has high blood pressure. She needs to take one tablet every morning.
+> Reduce salt in her food. Walk a little every day.
+> Come back in two weeks. If she gets a very bad headache or chest pain, come immediately."*
+>
+> Kofi translates quietly into Twi.
+>
+> Maame Akosua looks up. For the first time — she understands her own diagnosis.
+> She nods. A small, relieved smile.
+>
+> **Kofi (softly, to Dr. Mensah):** *"She says... thank you for explaining. The other doctors never explained."*
+>
+> Dr. Mensah nods quietly. No words needed.
+
+**Director note:** Hold on Maame Akosua's face when she smiles. This is the emotional peak of the video.
+
+---
+
+### SCENE 5 — The Contrast
+**Duration:** 20 seconds | **No dialogue**
+
+> Dr. Mensah closes the consultation on his laptop. The notes are saved.
+> He looks at the paper stack. Picks up one file — and closes it.
+> The work is done.
+>
+> He looks at the clock: **5:03 PM.**
+>
+> He stands. Puts on his jacket. Turns off the desk lamp.
+> He walks out — on time, for once.
+>
+> Final shot: the empty chair where Maame Akosua sat.
+> The laptop screen still glowing softly.
+
+---
+
+### SCENE 6 — Title Card
+**Duration:** 10 seconds | **Music swells**
+
+```
+Hospital Copilot
+
+Built for doctors who see 40 patients a day.
+So the last patient gets the same care as the first.
+
+─────────────────────────────────────────
+Powered by Gemma 4  ·  Built for Ghana
+Gemma 4 for Good Hackathon 2026
+```
+
+---
+
+## Why This Lands With Judges
+
+| Story element | What it communicates |
+|---|---|
+| Clock at 4:47 PM + paper stack | The problem is real, visible, universal |
+| Doctor still standing up to greet her | He is a good doctor being let down by a broken system |
+| AI invisible while doctor talks | Correct human-AI relationship — AI serves, human cares |
+| ICD codes + dosages appearing | Clinical credibility — this is not a chatbot, it's a medical tool |
+| Patient finally understanding her diagnosis | The mission of the whole project in one moment |
+| "The other doctors never explained" | Indicts the old system without saying a word about AI |
+| Doctor going home on time | The promise: better system = better life for everyone |
+
+---
+
+## Filming Checklist
+
+- [ ] Clinic room location secured
+- [ ] Laptop positioned so screen is visible in background shots
+- [ ] Hospital Copilot running and tested before filming
+- [ ] BP cuff and stethoscope as props
+- [ ] Paper file stack prepared
+- [ ] Scene 4 filmed with real app — let notes generate live, do not fake it
+- [ ] Maame Akosua's smile — hold for 3 seconds minimum
+- [ ] Background music: soft, warm, instrumental — swell on Scene 6
+
+---
+
+## Consultation Script (Standalone — for practising)
+
+> Doctor: Good afternoon Maame. How have you been since your last visit?
+> Patient: Not too well. I have been having headaches every morning. At the back of my head.
+> Doctor: Have you been taking your blood pressure medication?
+> Patient: I finished my Amlodipine two weeks ago. I could not afford to buy more.
+> Doctor: I see. Let me check your pressure. It is 162 over 98 — quite high. Any dizziness or blurred vision?
+> Patient: Sometimes dizzy when I stand up quickly. No problem with vision.
+> Doctor: Any chest pain or shortness of breath?
+> Patient: No, nothing like that.
+> Doctor: Good. You need to restart your Amlodipine — five milligrams every morning. I am also adding Lisinopril, ten milligrams once a day. Reduce salt in your food, avoid alcohol, and walk thirty minutes daily. Come back in two weeks. If you get a severe headache or chest pain — come in immediately.
+> Patient: Okay doctor. I will take the medication every day this time.
+> Doctor: Good. And please do not stop without telling me first.

DEVLOG.md

@@ -0,0 +1,256 @@
+# Hospital Copilot — Development Log
+
+**Hackathon:** Gemma 4 for Good  
+**Team:** Ricky (fredrickandoh17@gmail.com)  
+**Stack:** Python · Gradio · Gemma 4 · faster-whisper · ChromaDB · SQLite  
+**Started:** 2026-05-16
+
+---
+
+## Project Goal
+
+Build an AI clinical assistant that listens to doctor-patient consultations and automatically produces:
+- Live transcription of the conversation
+- Structured symptom extraction (symptoms, medications, duration, allergies, follow-up actions)
+- SOAP notes grounded with real ICD-10 codes and drug dosages
+- Plain-language patient summary
+- Structured patient records saved to a local database
+
+**Why:** Reduce doctor burnout from paperwork, improve care quality, and support healthcare workers in low-resource settings like Ghana.
+
+---
+
+## Architecture Overview
+
+```
+Microphone
+  └─► faster-whisper (STT, local CPU)       → raw transcript
+        └─► Gemma 4 26B cloud (speaker labelling) → Doctor:/Patient: transcript
+              ├─► Gemma 4 E2B via Ollama (symptom JSON)  → local CPU
+              └─► ChromaDB + MiniLM (RAG retrieval)      → ICD-10 codes + drug info
+                    └─► Gemma 4 26B cloud (SOAP note, patient summary)
+                          └─► SQLite (patients, sessions, notes, symptoms)
+                                └─► Gradio UI
+```
+
+---
+
+## Features Implemented
+
+### Core Pipeline
+| Feature | Status | Implementation |
+|---|---|---|
+| Live mic transcription | ✅ | faster-whisper `small` model, 3s chunks, VAD filter |
+| Speaker diarization | ✅ | Gemma 4 post-hoc Doctor:/Patient: labelling |
+| Symptom extraction | ✅ | Gemma 4 E2B via Ollama — JSON: chief complaint, symptoms, duration, severity, medications, allergies, vitals, history, follow-up actions |
+| RAG ICD-10 retrieval | ✅ | ChromaDB + all-MiniLM-L6-v2, 90+ Ghana-relevant codes |
+| RAG drug grounding | ✅ | ChromaDB, 40+ WHO Essential Medicines with dosages |
+| SOAP note generation | ✅ | Gemma 4 26B cloud, RAG context injected into prompt |
+| Patient summary | ✅ | Gemma 4 26B cloud, plain English |
+| Patient records (SQLite) | ✅ | patients, sessions, notes, symptoms tables |
+| Patient registration | ✅ | Name, DOB, gender, phone |
+| Records viewer | ✅ | Load any patient's most recent session |
+
+### Translation (Twi/Akan)
+| Status | Note |
+|---|---|
+| ⏸️ Paused | Gemma 4 returned 500 INTERNAL errors on Twi translation. Identified root cause: Twi is a low-resource language and Gemma 4 is not purpose-built for it. Decision: implement NLLB-200 (Meta's No Language Left Behind model) which was specifically trained on Akan/Twi. Deferred until core pipeline is stable. |
+
+### Gemma 4 Advanced Features (Added 2026-05-18)
+| Feature | Status | Implementation |
+|---|---|---|
+| **Reasoning mode (thinking)** | ✅ | `ThinkingConfig(thinking_budget=2048, include_thoughts=False)` on SOAP generation — Gemma 4 reasons step-by-step internally before writing the note |
+| **Function calling (symptom extraction)** | ✅ | `FunctionDeclaration` schema with `FunctionCallingMode.ANY` — guaranteed valid structured output, no JSON parsing |
+| **Multimodal image/document analysis** | ✅ | `Part.from_bytes()` with lab result / prescription images — extracted findings injected into SOAP context |
+
+---
+
+## Technical Decisions
+
+### 1. Multi-agent Gemma 4 architecture
+**Decision:** Use multiple specialised Gemma 4 instances rather than one large model for everything.  
+**Reasoning:** Different tasks have different speed/accuracy requirements:
+- Symptom extraction: needs to be fast, structured JSON → small local model (E2B)
+- SOAP notes: needs medical reasoning and long output → large cloud model (26B)
+- Speaker labelling: needs language understanding → cloud model
+- Embeddings: needs speed, runs every session → lightweight MiniLM locally
+
+### 2. Local vs cloud split
+**Decision:** Run small models locally (Ollama E2B, Whisper, MiniLM, ChromaDB), large inference on cloud API.  
+**Reasoning:** User has no GPU. CPU-only local inference is viable for small quantised models (Q4_K_M gemma4:e2b runs at ~5-10 tok/s). Large models (26B+) are impractical on CPU — cloud API provides them at acceptable latency.
+
+### 3. RAG with ChromaDB + MiniLM
+**Decision:** Use local vector store over calling the cloud model with full knowledge base in prompt.  
+**Reasoning:**
+- Injecting 70k ICD-10 codes into every prompt would exceed context limits and cost tokens
+- Local ChromaDB persists to disk, zero latency after first build
+- MiniLM-L6-v2 (~80MB) gives good semantic similarity for medical terms on CPU
+- Retrieves top-5 most relevant codes per consultation — keeps prompt tight and accurate
+
+### 4. Gradio over Streamlit
+**Decision:** Use Gradio for the UI.  
+**Reasoning:** Gradio has better support for streaming, audio, and timer-based polling. Streamlit's re-run model makes real-time transcript updates difficult. Gradio's `gr.Timer` makes 2-second polling trivial.
+
+### 5. Gemma 4 reasoning mode — temperature requirement
+**Decision:** Set `temperature=1.0` when `thinking_config` is enabled, not `0.3`.
+**Reasoning:** Google's API requires temperature=1.0 when using ThinkingConfig — lower values raise an error. The thinking process itself introduces determinism so output quality is not degraded. Added graceful fallback: if the model doesn't support thinking (e.g. older model version), retry without `thinking_config`.
+
+### 6. Function calling mode = ANY
+**Decision:** Use `FunctionCallingMode.ANY` (force the model to always call the function) rather than `AUTO`.
+**Reasoning:** `AUTO` mode allows the model to optionally use the function or just return text — unreliable for extraction tasks. `ANY` mode guarantees the model returns a structured function call every time, eliminating the JSON parse errors we had with the prompt-based approach.
+
+### 7. Symptom extraction: local first, cloud fallback
+**Decision:** Keep Gemma 4 E2B (Ollama, local) as primary for symptom extraction, cloud function calling as fallback.
+**Reasoning:** Preserves the "local AI, privacy-preserving" story for the hackathon. Cloud fallback ensures reliability when Ollama returns malformed JSON or fails. Both paths return the same dict structure.
+
+### 8. Transcript repair before downstream processing
+**Problem:** faster-whisper `small` on CPU makes errors — mishears medical terms, missing punctuation, run-on sentences. Downstream models (symptom extraction, SOAP generation) produce lower quality output when given a garbled transcript.
+**Decision:** Add a `clean_and_label_transcript()` step using Gemma 4 cloud that simultaneously repairs ASR errors AND labels speakers in one API call. This runs after `stop_consultation()` before any downstream processing.
+**What it fixes:** Incorrect drug names, missing punctuation, filler words (um/uh), run-on sentences, garbled medical terminology.
+**What it preserves:** All clinical facts — symptoms, medications, durations, dosages. Never adds or invents information.
+**Why one call:** Combining repair + labelling saves one API round-trip and is cheaper than two separate calls.
+
+### 9. Speaker diarization: Gemma 4 post-hoc vs pyannote-audio
+**Decision:** Use Gemma 4 cloud to infer Doctor/Patient labels from transcript text.  
+**Reasoning:**
+- `pyannote-audio` requires HuggingFace account, model license acceptance, and token setup
+- For a hackathon demo, Gemma 4 inference from linguistic context is good enough
+- Doctors and patients have very different speech patterns (questions vs symptom descriptions) that Gemma 4 reliably distinguishes
+- Can always upgrade to pyannote later
+
+### 6. SQLite for storage
+**Decision:** Local SQLite over PostgreSQL or cloud database.  
+**Reasoning:** Desktop app, no server, no network dependency. SQLite is reliable, zero-config, and sufficient for demo-scale data. Schema: patients → sessions → notes + symptoms.
+
+### 7. Whisper model: small over base
+**Decision:** Upgrade from `base` to `small` Whisper model.  
+**Reasoning:** `base` had poor accuracy on real speech, especially medical terminology. `small` is ~4x more accurate on medical vocabulary and still runs acceptably on CPU (~2-3x slower than base but real-time viable with 3-second chunking). `medium` was considered but too slow for live demo.
+
+---
+
+## Issues Encountered & Resolutions
+
+### Issue 1: `google-generativeai` deprecated
+**Error:** `FutureWarning: All support for the google.generativeai package has ended`  
+**Root cause:** Google deprecated the old `google-generativeai` SDK in favour of `google-genai`  
+**Resolution:** Replaced `google-generativeai` with `google-genai>=1.0.0` in requirements. Updated `cloud_agents.py` to use `from google import genai` and `genai.Client()` pattern.
+
+### Issue 2: Wrong Gemma 4 cloud model name
+**Error:** `404 NOT_FOUND: models/gemma-4-27b-it is not found`  
+**Root cause:** Model name `gemma-4-27b-it` does not exist on Google AI Studio API.  
+**Resolution:** Listed available models via API (`client.models.list()`). Correct names are:
+- `gemma-4-26b-a4b-it` (26B MoE, faster)
+- `gemma-4-31b-it` (31B dense, most capable)
+Updated default in `cloud_agents.py` and `.env`.
+
+### Issue 3: Twi translation 500 INTERNAL error
+**Error:** `500 INTERNAL: Internal error encountered` on `translate_to_twi()`  
+**Root cause:** Gemma 4 struggles with Twi (Akan) — a low-resource language with limited training data. The model likely has insufficient Twi coverage to translate medical content reliably, causing server-side failures.  
+**Resolution (temporary):** Removed Twi translation from the pipeline. Added try/except guards around all cloud agent calls so one failure doesn't break the entire `generate_notes()` flow.  
+**Planned fix:** Integrate NLLB-200 (`facebook/nllb-200-distilled-600M`) — Meta's purpose-built model for 200 low-resource languages including Akan/Twi.
+
+### Issue 4: Ollama version too old for Gemma 4
+**Error:** `Error: pull model manifest: 412: The model you are attempting to pull requires a newer version of Ollama`  
+**Root cause:** System Ollama was v0.19.0. Gemma 4 requires a newer version.  
+**Resolution:** Reinstall Ollama via the official install script: `curl -fsSL https://ollama.com/install.sh | sh` then `sudo systemctl restart ollama`. Note: Linux package managers (snap, apt) ship outdated Ollama versions — always use the curl script.
+
+### Issue 5: `chromadb.PersistentClient | None` TypeError
+**Error:** `TypeError: unsupported operand type(s) for |: 'function' and 'NoneType'`  
+**Root cause:** `chromadb.PersistentClient` is a factory function, not a class. Using it in a `X | None` type annotation evaluates at runtime and fails.  
+**Resolution:** Added `from __future__ import annotations` to `rag/retriever.py` — this makes all annotations lazy (strings at runtime), bypassing the evaluation issue.
+
+### Issue 6: White empty boxes in UI (RAG panels)
+**Issue:** `gr.Markdown` components rendered as white boxes on dark Gradio theme, even when empty.  
+**Root cause:** Gradio's default light background on Markdown components clashes with the dark theme. Empty panels had no content but still showed as white rectangles.  
+**Resolution:** Moved RAG panels (ICD-10, Drug Reference, Symptoms) into `gr.Accordion` components. Accordions collapse when not needed and have theme-consistent styling. Also added CSS `background: transparent` for markdown panels.
+
+### Issue 9: Gemma 4 image input — wrong contents structure
+**Error:** `500 INTERNAL` then `Part.from_text() takes 1 positional argument but 2 were given`
+**Root cause:** Two sequential mistakes in the multimodal contents format:
+  1. First attempt wrapped parts in `types.Content(role="user", parts=[...])` — not needed
+  2. Used `types.Part.from_text(IMAGE_PROMPT)` — this method does not exist in the SDK
+**Resolution:** Per official Gemma 4 docs (philschmid.de/gemma-4-gemini-api), the correct format is a plain list mixing `Part.from_bytes()` and a raw string:
+```python
+contents=[
+    types.Part.from_bytes(data=file_bytes, mime_type=mime_type),
+    IMAGE_PROMPT,   # plain string, not Part.from_text()
+]
+```
+All Gemma 4 models (including 26B and 31B) are fully multimodal. The initial 500 error was caused by the wrong content structure, not a model limitation.
+
+### Issue 10: pyannote-audio abandoned in favour of Gemma 4
+**Decision made:** Started implementing pyannote-audio for speaker diarization, then stopped.
+**Reason:** User confirmed Gemma 4 post-hoc labelling is sufficient for the demo. pyannote requires HuggingFace account, model license acceptance, and heavy torch dependency. Gemma 4 language-based inference is actually more reliable for medical conversations because it uses *context* (doctors ask questions, patients describe symptoms) rather than raw audio signal (which can fail when two speakers have similar voices).
+
+### Issue 10: Gradio CSS parameter deprecation warning
+**Warning:** `UserWarning: The parameters have been moved from the Blocks constructor to the launch() method`  
+**Root cause:** Gradio 6.0 moved `css` parameter from `gr.Blocks(css=...)` to `demo.launch(css=...)`.  
+**Resolution:** Moved `css=CSS` to `demo.launch(...)`.
+
+### Issue 8: uv installing to wrong Python version
+**Issue:** `chromadb` and `sentence-transformers` installed but not importable from venv.  
+**Root cause:** The venv was created with Python 3.11 (via uv) but system also has Python 3.12. Running `uv pip install` without specifying the environment installed to the wrong location.  
+**Resolution:** Used `VIRTUAL_ENV=/path/to/.venv uv pip install ...` to target the correct venv, or used `/path/to/.venv/bin/python -m pip install ...`.
+
+---
+
+## What Was Considered and Rejected
+
+| Option | Rejected because |
+|---|---|
+| Streamlit UI | Real-time transcript polling is awkward in Streamlit's re-run model |
+| PostgreSQL storage | Overkill for desktop demo; SQLite is zero-config |
+| pyannote-audio diarization | Requires HF account + model license; too much setup for hackathon timeline |
+| Full 70k ICD-10 dataset | Too large to embed in demo time; curated Ghana-relevant subset is more impactful |
+| Running everything on cloud API | Wanted to demonstrate hybrid local+cloud multi-agent architecture |
+| Whisper `large-v3` | Too slow on CPU for real-time; `small` is the sweet spot |
+| Gemma 4 for Twi translation | Low-resource language; model returned 500 errors. NLLB-200 is the right tool |
+
+---
+
+## Remaining Work / Roadmap
+
+- [ ] **Twi translation via NLLB-200** — integrate `facebook/nllb-200-distilled-600M` locally
+- [ ] **PDF export** — export SOAP note + patient summary as printable PDF (fpdf2 already in deps)
+- [ ] **Multi-session history** — view all past sessions for a patient, not just the most recent
+- [ ] **Upgrade to Whisper `medium`** if demo machine is fast enough
+- [ ] **ICD-10 code expansion** — add full 70k code dataset for production use
+- [ ] **MedGemma** — self-host `medgemma-4b-it` or `medgemma-27b-it` for higher-accuracy medical image analysis
+- [ ] **Long-context patient history** — load all previous session notes into SOAP prompt for longitudinal care reasoning
+
+---
+
+## File Structure
+
+```
+hosptial_copilot/
+├── app.py                          Main Gradio app + UI
+├── agents/
+│   ├── cloud_agents.py             Gemma 4 cloud: SOAP, summary, speaker labelling
+│   └── symptom_agent.py            Gemma 4 E2B local: symptom JSON extraction
+├── transcription/
+│   └── transcriber.py              faster-whisper live mic streaming
+├── rag/
+│   ├── retriever.py                ChromaDB + MiniLM embedding + retrieval
+│   └── data/
+│       ├── icd10_common.json       90+ ICD-10 codes (Ghana-relevant)
+│       └── essential_medicines.json 40+ WHO Essential Medicines
+├── database/
+│   └── db.py                       SQLite schema + helpers
+├── requirements.txt
+├── .env.example
+├── .gitignore
+├── README.md
+└── DEVLOG.md                       This file
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `GEMINI_API_KEY` | — | Google AI Studio API key (required) |
+| `WHISPER_MODEL` | `small` | Whisper model size: tiny/base/small/medium/large-v3 |
+| `OLLAMA_MODEL` | `gemma4:e2b` | Local Ollama model for symptom extraction |
+| `CLOUD_MODEL` | `gemma-4-26b-a4b-it` | Google AI Studio model name |

INTRO_VIDEO_SCRIPT.md

@@ -0,0 +1,239 @@
+# Hospital Copilot — Introductory Video Script
+### "Before the Last Patient"
+
+**Hackathon:** Gemma 4 for Good · 2026
+**Format:** Narrated short film with text overlays
+**Runtime:** 90–120 seconds
+**Tone:** Honest, grounded, emotional
+
+---
+
+## PURPOSE OF THIS VIDEO
+
+This is the introductory video that plays BEFORE the demo.
+It establishes the problem emotionally, introduces the solution, and honestly
+frames what the viewer is about to see as a proof of concept — not a live
+hospital deployment, but a fully functional system that would work identically
+in a real clinical setting.
+
+---
+
+## SCENE-BY-SCENE SCRIPT
+
+---
+
+### SCENE 1 — THE PROBLEM
+**Timestamp:** 0:00 – 0:35
+**Visual:** Black screen → single stat → doctor's desk at end of day
+
+**[Black screen. Silence. Then a single line of text fades in:]**
+
+> *"In Ghana, there is 1 doctor for every 10,000 people."*
+
+**[Fade to: a doctor's desk late in the day. Stack of paper files.
+A tired hand writing notes. A clock on the wall.]**
+
+**NARRATOR (Voice-over):**
+
+> "Every day, doctors in Ghana see between 30 and 50 patients.
+> They diagnose. They treat. They care.
+>
+> But when the last patient leaves — the work is not done.
+>
+> The notes still need to be written.
+> The records updated.
+> The paperwork filed.
+>
+> For every hour spent with a patient —
+> another hour is spent on documentation.
+>
+> That is an hour stolen from the next patient.
+> From rest. From family.
+>
+> This is the hidden cost of healthcare —
+> and it is burning doctors out."
+
+**[Text overlay appears on screen:]**
+
+> *"Medical burnout affects 70% of doctors in sub-Saharan Africa."*
+> *— WHO, 2024*
+
+---
+
+### SCENE 2 — THE HUMAN COST
+**Timestamp:** 0:35 – 0:55
+**Visual:** Empty waiting room chairs. Then a full one. A patient waiting alone.
+
+**NARRATOR (Voice-over):**
+
+> "When a doctor is exhausted, the patient feels it.
+>
+> Shorter consultations.
+> Less explanation.
+> Less time to listen.
+>
+> The patient who comes in last
+> gets less than the patient who came in first.
+>
+> That is not a failure of the doctor.
+> That is a failure of the system.
+>
+> We built something to fix it."
+
+---
+
+### SCENE 3 — THE SOLUTION
+**Timestamp:** 0:55 – 1:15
+**Visual:** Laptop screen showing Hospital Copilot. Live transcript streaming.
+           ICD codes appearing. SOAP note generating.
+
+**NARRATOR (Voice-over):**
+
+> "Hospital Copilot is an AI clinical assistant powered by Gemma 4.
+>
+> It listens to the consultation — with the doctor's permission —
+> and handles the documentation automatically.
+>
+> Live transcription.
+> Symptom extraction.
+> SOAP notes.
+> Patient summaries.
+>
+> Grounded in real ICD-10 codes
+> and WHO-approved drug dosages.
+>
+> The doctor talks to the patient.
+> The AI handles the rest."
+
+---
+
+### SCENE 4 — THE HONEST DISCLAIMER
+**Timestamp:** 1:15 – 1:30
+**Visual:** Plain background. No music. Just voice. Calm and direct.
+
+**[Music fades out completely here. Silence under the voice.]**
+
+**NARRATOR (Voice-over):**
+
+> "What you are about to see is a proof of concept.
+>
+> We are not in a hospital.
+> The patient is not real.
+> The setting is simulated.
+>
+> But the AI is real.
+> The technology is real.
+> The output is real.
+>
+> Everything you will see —
+> the transcription, the clinical notes, the intelligence —
+> is exactly what would happen
+> in an actual hospital consultation.
+>
+> This is what it could look like.
+> This is what it should look like.
+> Starting today."
+
+---
+
+### SCENE 5 — CLOSING TITLE CARD
+**Timestamp:** 1:30 – 1:45
+**Visual:** Clean dark screen. Text appears line by line with gentle fade.
+
+```
+Hospital Copilot
+
+Powered by Gemma 4
+Built for Ghana. Built for Good.
+
+─────────────────────────────────────
+Gemma 4 for Good Hackathon  ·  2026
+```
+
+**[Soft transition into the demo video]**
+
+---
+
+## FILMING GUIDE
+
+### Scenes and What You Need
+
+| Scene | Location | Props |
+|---|---|---|
+| Opening desk shot | Any desk — dim warm light | Paper files, pen, clock |
+| Waiting room | Any corridor or room with chairs | Chairs, natural light |
+| Laptop screen | Anywhere with the app running | Laptop showing Hospital Copilot |
+| Title card | No filming needed | Post-production text overlay |
+
+### Narrator
+- Does not need to be on camera — voice-over recorded separately works perfectly
+- Speak slowly and deliberately — pause between each short line
+- Tone: calm, serious, hopeful — not dramatic or over-performed
+
+### Music
+- Use soft, minimal instrumental music — piano or ambient
+- Volume: low throughout Scenes 1–3
+- **Fade to silence completely** at Scene 4 (the disclaimer)
+- Silence makes the disclaimer land harder than any music would
+- Bring music back softly under the title card in Scene 5
+
+---
+
+## FULL NARRATION — CLEAN READ-THROUGH
+
+*(Use this for recording the voice-over in one take)*
+
+---
+
+In Ghana, there is one doctor for every ten thousand people.
+
+Every day, doctors see between thirty and fifty patients.
+They diagnose. They treat. They care.
+
+But when the last patient leaves — the work is not done.
+The notes still need to be written. The records updated. The paperwork filed.
+
+For every hour spent with a patient, another hour is spent on documentation.
+That is an hour stolen from the next patient. From rest. From family.
+This is the hidden cost of healthcare — and it is burning doctors out.
+
+When a doctor is exhausted, the patient feels it.
+Shorter consultations. Less explanation. Less time to listen.
+The patient who comes in last gets less than the patient who came in first.
+
+That is not a failure of the doctor. That is a failure of the system.
+We built something to fix it.
+
+Hospital Copilot is an AI clinical assistant powered by Gemma 4.
+It listens to the consultation — with the doctor's permission —
+and handles the documentation automatically.
+
+Live transcription. Symptom extraction. SOAP notes. Patient summaries.
+Grounded in real ICD-10 codes and WHO-approved drug dosages.
+The doctor talks to the patient. The AI handles the rest.
+
+---
+
+What you are about to see is a proof of concept.
+We are not in a hospital. The patient is not real. The setting is simulated.
+
+But the AI is real. The technology is real. The output is real.
+
+Everything you will see — the transcription, the clinical notes, the intelligence —
+is exactly what would happen in an actual hospital consultation.
+
+This is what it could look like.
+This is what it should look like.
+Starting today.
+
+---
+
+## KEY CREATIVE DECISIONS
+
+| Decision | Reason |
+|---|---|
+| Silence under the disclaimer | Removes all distraction — the honesty lands harder without music |
+| Short punchy lines in narration | Easier to absorb, more memorable, feels confident not rushed |
+| "Failure of the system, not the doctor" | Positions the app as supporting doctors, not replacing them |
+| "Starting today" as the final line | Confident, present-tense — not a future promise, a current reality |
+| Owning "proof of concept" plainly | More credible to judges than overselling — shows maturity and integrity |

README.md

@@ -0,0 +1,73 @@
+# Hospital Copilot
+
+AI-powered medical documentation assistant for the **Gemma 4 for Good** hackathon.
+
+Listens to doctor-patient consultations and automatically generates SOAP notes, patient summaries, symptom extractions, and Twi (Akan) translations — reducing paperwork and language barriers in Ghanaian healthcare.
+
+## Features
+
+- **Live transcription** via faster-whisper (runs on CPU)
+- **Symptom extraction** via Gemma 4 E2B (local, Ollama, CPU)
+- **SOAP note generation** via Gemma 4 27B (Google AI Studio)
+- **Patient summary** in plain English
+- **English ↔ Twi translation** for Ghanaian patients
+- **Patient records** stored in local SQLite
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Install Ollama and pull Gemma 4
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull gemma4:e2b
+```
+
+### 3. Configure environment
+
+```bash
+cp .env.example .env
+# Edit .env and add your Google AI Studio API key
+```
+
+Get a free API key at https://aistudio.google.com
+
+### 4. Run
+
+```bash
+python app.py
+```
+
+Open http://localhost:7860 in your browser.
+
+## Project Structure
+
+```
+hosptial_copilot/
+├── app.py                      # Gradio UI + app logic
+├── agents/
+│   ├── symptom_agent.py        # Local Gemma 4 (Ollama) symptom extractor
+│   └── cloud_agents.py         # Cloud Gemma 4: SOAP, summary, translation
+├── transcription/
+│   └── transcriber.py          # faster-whisper live mic transcription
+├── database/
+│   └── db.py                   # SQLite helpers
+├── requirements.txt
+└── .env.example
+```
+
+## Architecture
+
+```
+Microphone
+  └─► faster-whisper (local, CPU)   → raw transcript
+        ├─► Gemma 4 E2B via Ollama  → symptom JSON (local CPU)
+        └─► Gemma 4 27B via API     → SOAP note + summary + Twi translation
+              └─► SQLite            → patient records
+                    └─► Gradio UI   → doctor dashboard
+```

SUBMISSION_WRITEUP.md

@@ -0,0 +1,139 @@
+# MediScribe AI
+## An Offline-First Multilingual Clinical Assistant Powered by Gemma 4
+
+**Track:** Health & Sciences
+
+---
+
+## Overview
+
+In many clinics across Africa, doctors spend more time documenting than treating. MediScribe AI is a desktop AI assistant that listens to a doctor-patient consultation, transcribes it in real time, and automatically generates a structured SOAP note, a plain-language patient summary, and a structured symptom record — all reviewed and approved by the doctor before anything is saved.
+
+The system was built specifically for Ghanaian healthcare contexts, targeting clinics where internet access may be intermittent and where patients may speak languages other than English.
+
+---
+
+## The Problem
+
+Healthcare workers in developing regions face crushing administrative workloads. Manual note-taking after every consultation reduces patient interaction time, increases burnout, and introduces inconsistencies in medical records. Language barriers between English-trained doctors and local-language-speaking patients add further friction. Many cloud-first AI tools are impractical where connectivity is unreliable.
+
+---
+
+## What We Built
+
+MediScribe AI is a single Python application with a Gradio web UI. The consultation workflow is:
+
+1. The doctor registers or selects a patient.
+2. Consultation starts — the microphone opens and audio begins streaming.
+3. faster-whisper transcribes speech in real time in 3-second blocks on CPU.
+4. After the consultation ends, Gemma 4 (cloud) repairs ASR errors and labels each turn as Doctor or Patient.
+5. The doctor clicks **Generate Notes**. The system:
+   - Extracts structured symptoms via **local Gemma 4 E2B** (Ollama, CPU) — chief complaint, symptom list, duration, severity, vitals, medications, allergies, follow-up actions
+   - Falls back to **cloud Gemma 4 function calling** if local extraction fails, returning a guaranteed-valid structured schema
+   - Runs **semantic RAG retrieval** against a local ChromaDB knowledge base to surface relevant ICD-10 codes and WHO essential medicines dosages
+   - Generates a **SOAP note** using cloud Gemma 4 with reasoning/thinking mode enabled, grounded by the RAG context
+   - Generates a **plain-language patient summary**
+6. The doctor reviews both outputs in editable panels before approving.
+7. Everything is saved to local SQLite — transcript, SOAP note, summary, and structured symptom JSON.
+
+An optional document upload allows the doctor to attach a photo or PDF of a lab result, prescription, or X-ray. Gemma 4's multimodal capability reads the document and automatically includes the findings in the SOAP note.
+
+---
+
+## Why Gemma 4
+
+We used Gemma 4 across every AI-powered step of the pipeline:
+
+| Task | Model | Where |
+|---|---|---|
+| Symptom extraction (primary) | Gemma 4 E2B | Local CPU via Ollama |
+| Symptom extraction (fallback) | Gemma 4 26B — function calling | Google AI Studio API |
+| Transcript repair + speaker labelling | Gemma 4 26B | Google AI Studio API |
+| SOAP note generation | Gemma 4 26B — reasoning mode | Google AI Studio API |
+| Patient summary | Gemma 4 26B | Google AI Studio API |
+| Medical document analysis | Gemma 4 26B — multimodal | Google AI Studio API |
+
+The local Gemma 4 E2B model (quantized, running via Ollama on CPU) handles the privacy-sensitive symptom extraction step, keeping structured clinical data local when possible. The cloud Gemma 4 model handles the tasks requiring stronger reasoning — particularly SOAP note generation, which uses the model's built-in thinking mode to reason through the clinical picture before writing the note.
+
+Gemma 4's native function calling was used to implement a guaranteed-valid structured output schema for symptom extraction — eliminating JSON parsing failures that plagued earlier prompt-only approaches.
+
+---
+
+## System Architecture
+
+**Frontend:** Gradio web UI running locally on port 7860. Two main tabs — Live Consultation and Patient Records. No external server required.
+
+**Speech-to-Text:** faster-whisper (`small` model, CPU, int8 quantized) with sounddevice for microphone streaming. Audio is processed in 3-second chunks with VAD filtering. Full session audio is saved as WAV after the consultation ends.
+
+**Symptom Extraction Agent (`agents/symptom_agent.py`):** Calls local Gemma 4 E2B via Ollama with a structured JSON prompt. On any failure (model unavailable, invalid JSON, malformed response), automatically falls back to cloud Gemma 4 function calling with a defined schema, guaranteeing a valid structured output.
+
+**Cloud Agent (`agents/cloud_agents.py`):** Wraps the Google GenAI SDK. Implements transcript repair, SOAP generation (with `ThinkingConfig`), patient summary, function-calling symptom extraction, and multimodal document analysis. Temperature is set to 0.3 for clinical outputs; 1.0 when thinking mode is active (required by the API).
+
+**RAG Pipeline (`rag/retriever.py`):** `all-MiniLM-L6-v2` sentence-transformers embeddings + ChromaDB persistent vector store. Two collections: 90+ ICD-10 codes (Ghana-relevant and general) and 40+ WHO Essential Medicines entries. The top-5 ICD codes and top-3 drug matches are retrieved per consultation and injected into the SOAP note prompt as grounding context.
+
+**Database (`database/db.py`):** SQLite with four tables — `patients`, `sessions`, `notes`, and `symptoms`. Stores the full cleaned transcript, SOAP note, English summary, and structured symptom JSON per session.
+
+---
+
+## Key Features
+
+### Real-Time Transcription with Post-Processing
+faster-whisper streams transcription as the consultation proceeds. After the session ends, Gemma 4 repairs ASR errors (medical terminology, drug names, run-on sentences) and labels each turn as Doctor or Patient in a single pass.
+
+### Dual-Mode Symptom Extraction
+Local-first extraction via Gemma 4 E2B keeps sensitive data off the network whenever possible. Automatic cloud fallback via function calling ensures the pipeline never silently fails.
+
+### RAG-Grounded SOAP Notes
+ICD-10 codes and drug dosage references are retrieved semantically before SOAP note generation. This grounds the model's clinical output in verifiable reference data rather than relying purely on parametric knowledge.
+
+### Multimodal Document Analysis
+Doctors can upload a photo or PDF of a lab result, prescription, or report. Gemma 4 reads it and its findings are automatically included as context in the SOAP note generation step.
+
+### Human-in-the-Loop Validation
+Every generated output is shown to the doctor in a readable panel with an editable fallback before anything is committed to the database. Doctors approve; the AI drafts.
+
+### Local Storage
+All patient records, transcripts, SOAP notes, and symptom data are stored in a local SQLite database. No patient data leaves the device except for the API calls to generate notes.
+
+---
+
+## Technical Challenges
+
+### Reliable Structured Output from a Local Small Model
+Gemma 4 E2B running on CPU occasionally produces malformed JSON or misses required fields. We implemented a two-tier extraction strategy: local Ollama first with JSON validation, cloud function calling as a typed-schema fallback. This eliminated silent data loss in the pipeline.
+
+### ASR Quality on Medical Vocabulary
+faster-whisper on CPU struggles with drug names, medical abbreviations, and Ghanaian proper names. We addressed this by adding a dedicated Gemma 4 repair pass after the consultation ends, correcting the transcript before any clinical information is extracted.
+
+### Thinking Mode Compatibility
+Gemma 4's reasoning mode requires `temperature=1.0` and is not supported on all model variants. We implemented a graceful fallback that detects API errors related to `ThinkingConfig` and retries without it, so SOAP generation never fails silently.
+
+### RAG Grounding for Clinical Accuracy
+SOAP notes generated without reference context showed inconsistent ICD code suggestions and occasionally incorrect drug dosages. Adding RAG retrieval with ChromaDB significantly improved specificity and reduced hallucinated medication instructions.
+
+---
+
+## What Is Not Yet Built
+
+Twi/English translation is planned (NLLB-200) but not yet implemented — stubs exist in `cloud_agents.py`. Speaker diarization is partially scaffolded (session audio is saved as WAV) but not yet wired up. The system currently requires internet access for SOAP generation and transcript repair; a fully offline mode would require a larger local model than E2B.
+
+---
+
+## Impact
+
+MediScribe AI reduces the documentation burden on doctors by automating the most time-consuming parts of post-consultation admin: writing SOAP notes, summarizing for patients, and coding diagnoses. Because it runs locally and saves to a local database, it is viable in clinics with unreliable connectivity. The human-in-the-loop design keeps the doctor fully in control — the AI is a drafter, not an authority.
+
+---
+
+## Stack Summary
+
+| Component | Technology |
+|---|---|
+| UI | Gradio (Python, port 7860) |
+| Speech-to-Text | faster-whisper small, CPU, int8 |
+| Local AI | Gemma 4 E2B via Ollama |
+| Cloud AI | Gemma 4 26B-IT via Google AI Studio |
+| Embeddings | all-MiniLM-L6-v2 (sentence-transformers) |
+| Vector Store | ChromaDB (local, persistent) |
+| Database | SQLite |
+| Language | Python 3.11 |

agents/cloud_agents.py

@@ -0,0 +1,274 @@
+import os
+import base64
+from pathlib import Path
+from google import genai
+from google.genai import types
+from dotenv import load_dotenv
+
+load_dotenv()
+
+CLOUD_MODEL = os.getenv("CLOUD_MODEL", "gemma-4-26b-a4b-it")
+
+_client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+
+
+def _call(prompt: str, use_thinking: bool = False) -> str:
+    try:
+        config = types.GenerateContentConfig(temperature=0.3)
+        if use_thinking:
+            config = types.GenerateContentConfig(
+                temperature=1.0,  # required when thinking is enabled
+                thinking_config=types.ThinkingConfig(
+                    include_thoughts=False,   # reason internally, return only final answer
+                    thinking_budget=2048,
+                ),
+            )
+        response = _client.models.generate_content(
+            model=CLOUD_MODEL,
+            contents=prompt,
+            config=config,
+        )
+        return response.text.strip()
+    except Exception as e:
+        raise RuntimeError(f"Gemma API error: {e}") from e
+
+
+# ── Function calling — symptom schema ────────────────────────────────────────
+
+SYMPTOM_SCHEMA = types.FunctionDeclaration(
+    name="record_symptoms",
+    description="Record all structured clinical information extracted from the consultation transcript.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "chief_complaint":      {"type": "string",  "description": "Main reason for the visit"},
+            "symptoms":             {"type": "array",   "items": {"type": "string"}, "description": "List of reported symptoms"},
+            "duration":             {"type": "string",  "description": "How long symptoms have been present"},
+            "severity":             {"type": "string",  "enum": ["mild", "moderate", "severe"], "description": "Overall severity"},
+            "associated_symptoms":  {"type": "array",   "items": {"type": "string"}},
+            "medications_mentioned":{"type": "array",   "items": {"type": "string"}, "description": "Drugs or treatments mentioned"},
+            "allergies":            {"type": "array",   "items": {"type": "string"}},
+            "vitals_mentioned": {
+                "type": "object",
+                "properties": {
+                    "temperature":    {"type": "string"},
+                    "blood_pressure": {"type": "string"},
+                    "pulse":          {"type": "string"},
+                    "weight":         {"type": "string"},
+                },
+            },
+            "relevant_history":     {"type": "string",  "description": "Past medical history mentioned"},
+            "follow_up_actions":    {"type": "array",   "items": {"type": "string"}, "description": "Next steps, tests, referrals"},
+        },
+        "required": ["chief_complaint", "symptoms"],
+    },
+)
+
+_SYMPTOM_TOOL = types.Tool(function_declarations=[SYMPTOM_SCHEMA])
+
+
+def extract_symptoms_cloud(transcript: str) -> dict:
+    """
+    Use cloud Gemma 4 function calling to extract structured symptoms.
+    Returns a guaranteed-valid dict — no JSON parsing errors.
+    """
+    if not transcript.strip():
+        return {}
+    try:
+        response = _client.models.generate_content(
+            model=CLOUD_MODEL,
+            contents=f"Extract all clinical information from this consultation transcript:\n\n{transcript}",
+            config=types.GenerateContentConfig(
+                tools=[_SYMPTOM_TOOL],
+                tool_config=types.ToolConfig(
+                    function_calling_config=types.FunctionCallingConfig(
+                        mode="ANY",
+                        allowed_function_names=["record_symptoms"],
+                    )
+                ),
+                temperature=0.1,
+            ),
+        )
+        for part in response.candidates[0].content.parts:
+            if part.function_call:
+                return dict(part.function_call.args)
+    except Exception as e:
+        print(f"[FunctionCalling] Cloud extraction failed: {e}")
+    return {}
+
+
+# ── Transcript repair + speaker labelling ─────────────────────────────────────
+
+REPAIR_PROMPT = """You are a medical transcription editor. You will receive a raw speech-to-text transcript of a doctor-patient consultation. The transcript may contain:
+- Misheared words or garbled medical terms
+- Missing punctuation and sentence breaks
+- Run-on sentences
+- Filler words (um, uh, like, you know)
+- Incorrectly transcribed drug names, symptoms, or medical terminology
+- Words run together without spaces
+
+Your job is to:
+1. REPAIR the transcript — fix obvious errors, correct medical terminology, add punctuation, split run-on sentences, remove filler words
+2. LABEL each speaker — prefix each turn with "Doctor:" or "Patient:"
+   - Doctors: ask clinical questions, give diagnoses, prescribe medications, explain treatment
+   - Patients: describe symptoms, answer questions, mention their history, express concerns
+3. Start a new labelled line each time the speaker changes
+4. Do NOT add, invent, or remove any clinical facts — only fix language/transcription errors
+5. Keep all mentioned symptoms, medications, durations, and instructions intact
+
+Raw transcript:
+{transcript}
+
+Cleaned and labelled transcript:"""
+
+
+def clean_and_label_transcript(transcript: str) -> str:
+    """
+    Repair ASR errors and add Doctor/Patient speaker labels in one Gemma 4 call.
+    Falls back to raw transcript on failure.
+    """
+    if not transcript.strip():
+        return transcript
+    try:
+        return _call(REPAIR_PROMPT.format(transcript=transcript))
+    except Exception as e:
+        print(f"[TranscriptRepair] Failed ({e}), using raw transcript.")
+        return transcript
+
+
+def label_speakers(transcript: str) -> str:
+    """Alias kept for backwards compatibility — now delegates to clean_and_label."""
+    return clean_and_label_transcript(transcript)
+
+
+# ── SOAP Note (with reasoning mode) ──────────────────────────────────────────
+
+SOAP_PROMPT = """You are an experienced medical scribe and clinician. Generate a professional SOAP note from the following doctor-patient consultation transcript.
+
+{rag_context}
+
+Think carefully about the clinical picture before writing. Format with these exact sections:
+
+**S - Subjective**
+(Patient's reported complaints, history, and symptoms in their own words)
+
+**O - Objective**
+(Observable, measurable findings: vitals, physical exam findings, lab values if mentioned)
+
+**A - Assessment**
+(Clinical impression and working diagnosis. Include the most likely ICD-10 code.)
+
+**P - Plan**
+(Medications with correct dosages from the reference above, investigations ordered, referrals, follow-up schedule, patient education)
+
+Transcript:
+{transcript}
+
+SOAP Note:"""
+
+
+def generate_soap_note(transcript: str, rag_context: str = "") -> str:
+    if not transcript.strip():
+        return "No transcript available."
+    context_block = f"\nClinical Reference:\n{rag_context}\n" if rag_context else ""
+    try:
+        return _call(
+            SOAP_PROMPT.format(transcript=transcript, rag_context=context_block),
+            use_thinking=True,
+        )
+    except RuntimeError as e:
+        if "thinking" in str(e).lower() or "ThinkingConfig" in str(e):
+            # model doesn't support thinking — retry without it
+            print("[Reasoning] Thinking not supported on this model, retrying without.")
+            return _call(
+                SOAP_PROMPT.format(transcript=transcript, rag_context=context_block),
+                use_thinking=False,
+            )
+        raise
+
+
+# ── Patient Summary ───────────────────────────────────────────────────────────
+
+SUMMARY_PROMPT = """You are a compassionate medical communicator. Write a clear, friendly patient summary from this consultation that:
+- Uses simple, non-technical language
+- Explains what was discussed and decided
+- Lists medications and dosages prescribed
+- States next steps and follow-up plan
+- Is encouraging and reassuring in tone
+
+Transcript:
+{transcript}
+
+Patient Summary:"""
+
+
+def generate_patient_summary(transcript: str) -> str:
+    if not transcript.strip():
+        return "No transcript available."
+    return _call(SUMMARY_PROMPT.format(transcript=transcript))
+
+
+# ── Medical image / document analysis ────────────────────────────────────────
+
+IMAGE_PROMPT = """You are a medical document analyst. Carefully examine this medical document (lab result, prescription, X-ray report, or clinical record).
+
+Extract ALL clinical information present and structure it clearly:
+
+**Document Type:** (lab result / prescription / imaging report / other)
+
+**Key Findings:**
+(List every test, value, measurement, or finding with its result and reference range if shown)
+
+**Abnormal Values:**
+(Highlight any results outside normal range)
+
+**Medications / Dosages:**
+(Any drugs, doses, or treatment instructions visible)
+
+**Clinical Notes:**
+(Any doctor notes, diagnoses, or instructions on the document)
+
+**Summary for SOAP Note:**
+(One paragraph summarising what this document adds to the clinical picture)"""
+
+
+def analyze_medical_document(file_path: str) -> str:
+    """
+    Extract clinical data from an uploaded image or PDF using Gemma 4 multimodal.
+    Contents format: [Part.from_bytes(...), "text string"] — per official Gemma 4 docs.
+    """
+    suffix = Path(file_path).suffix.lower()
+    mime_map = {
+        ".jpg":  "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".png":  "image/png",
+        ".webp": "image/webp",
+        ".pdf":  "application/pdf",
+    }
+    mime_type = mime_map.get(suffix, "image/jpeg")
+
+    with open(file_path, "rb") as f:
+        file_bytes = f.read()
+
+    try:
+        response = _client.models.generate_content(
+            model=CLOUD_MODEL,
+            contents=[
+                types.Part.from_bytes(data=file_bytes, mime_type=mime_type),
+                IMAGE_PROMPT,
+            ],
+            config=types.GenerateContentConfig(temperature=0.1),
+        )
+        return response.text.strip()
+    except Exception as e:
+        raise RuntimeError(f"Image analysis failed: {e}") from e
+
+
+# ── Translation stubs (disabled — NLLB-200 planned) ──────────────────────────
+
+def translate_to_twi(english_text: str) -> str:
+    return ""
+
+
+def translate_to_english(twi_text: str) -> str:
+    return ""

agents/symptom_agent.py

@@ -0,0 +1,112 @@
+import os
+import json
+import ollama
+from agents.cloud_agents import extract_symptoms_cloud
+
+OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "gemma4:e2b")
+
+SYMPTOM_PROMPT = """You are a medical symptom extraction AI. Extract all clinical information from this transcript into valid JSON only.
+
+Return ONLY valid JSON — no markdown, no explanation, no code fences:
+{{
+  "chief_complaint": "main reason for visit",
+  "symptoms": ["list", "of", "symptoms"],
+  "duration": "how long symptoms have been present",
+  "severity": "mild | moderate | severe",
+  "associated_symptoms": ["other symptoms"],
+  "medications_mentioned": ["drugs or treatments mentioned"],
+  "allergies": ["any allergies mentioned"],
+  "vitals_mentioned": {{
+    "temperature": null,
+    "blood_pressure": null,
+    "pulse": null,
+    "weight": null
+  }},
+  "relevant_history": "past medical history",
+  "follow_up_actions": ["follow-up steps, tests, referrals"]
+}}
+
+Transcript:
+{transcript}"""
+
+
+def _extract_via_ollama(transcript: str) -> dict:
+    """Primary: local Gemma 4 E2B via Ollama."""
+    response = ollama.chat(
+        model=OLLAMA_MODEL,
+        messages=[{"role": "user", "content": SYMPTOM_PROMPT.format(transcript=transcript)}],
+        options={"temperature": 0.1},
+    )
+    raw = response["message"]["content"].strip()
+
+    # strip markdown fences if present
+    if "```" in raw:
+        parts = raw.split("```")
+        raw = parts[1] if len(parts) > 1 else parts[0]
+        if raw.startswith("json"):
+            raw = raw[4:]
+    raw = raw.strip()
+
+    result = json.loads(raw)
+    # must be a dict with at least chief_complaint to be valid
+    if not isinstance(result, dict) or "chief_complaint" not in result:
+        raise ValueError("Invalid symptom structure from Ollama")
+    return result
+
+
+def extract_symptoms(transcript: str) -> dict:
+    """
+    Extract structured symptoms from transcript.
+    Tries local Gemma 4 E2B (Ollama) first — fast, private.
+    Falls back to cloud Gemma 4 function calling on any failure — guaranteed valid schema.
+    """
+    if not transcript.strip():
+        return {}
+
+    try:
+        result = _extract_via_ollama(transcript)
+        print("[Symptoms] Extracted via local Gemma 4 E2B (Ollama)")
+        return result
+    except Exception as e:
+        print(f"[Symptoms] Ollama failed ({e}), falling back to cloud function calling...")
+
+    try:
+        result = extract_symptoms_cloud(transcript)
+        print("[Symptoms] Extracted via cloud Gemma 4 function calling")
+        return result
+    except Exception as e:
+        print(f"[Symptoms] Cloud fallback also failed: {e}")
+        return {"error": str(e)}
+
+
+def format_symptoms_for_display(symptoms: dict) -> str:
+    if not symptoms or "error" in symptoms:
+        return "_No symptoms extracted._"
+
+    lines = []
+    if cc := symptoms.get("chief_complaint"):
+        lines.append(f"**Chief Complaint:** {cc}")
+    if s := symptoms.get("symptoms"):
+        lines.append(f"**Symptoms:** {', '.join(s)}")
+    if d := symptoms.get("duration"):
+        lines.append(f"**Duration:** {d}")
+    if sev := symptoms.get("severity"):
+        lines.append(f"**Severity:** {sev}")
+    if assoc := symptoms.get("associated_symptoms"):
+        lines.append(f"**Associated:** {', '.join(assoc)}")
+    if meds := symptoms.get("medications_mentioned"):
+        lines.append(f"**Medications:** {', '.join(meds)}")
+    if allerg := symptoms.get("allergies"):
+        lines.append(f"**Allergies:** {', '.join(allerg)}")
+
+    vitals = symptoms.get("vitals_mentioned") or {}
+    vital_parts = [f"{k}: {v}" for k, v in vitals.items() if v]
+    if vital_parts:
+        lines.append(f"**Vitals:** {', '.join(vital_parts)}")
+    if hist := symptoms.get("relevant_history"):
+        lines.append(f"**History:** {hist}")
+    if followup := symptoms.get("follow_up_actions"):
+        actions = "\n".join(f"- {a}" for a in followup)
+        lines.append(f"**Follow-up Actions:**\n{actions}")
+
+    return "\n\n".join(lines) if lines else "_No structured data found._"

app.py

@@ -0,0 +1,490 @@
+import threading
+from dotenv import load_dotenv
+
+load_dotenv()
+
+import gradio as gr
+
+from database.db import (
+    init_db,
+    create_patient,
+    get_all_patients,
+    get_patient,
+    create_session,
+    update_transcript,
+    close_session,
+    save_note,
+    save_symptoms,
+    get_sessions_for_patient,
+    get_note_for_session,
+    get_symptoms_for_session,
+)
+from transcription.transcriber import LiveTranscriber
+from agents.symptom_agent import extract_symptoms, format_symptoms_for_display
+from agents.cloud_agents import generate_soap_note, generate_patient_summary, clean_and_label_transcript, analyze_medical_document
+from rag.retriever import (
+    ensure_kb,
+    retrieve_icd_codes,
+    retrieve_drug_info,
+    format_icd_context,
+    format_drug_context,
+)
+
+# ── Startup ───────────────────────────────────────────────────────────────────
+
+init_db()
+ensure_kb()
+
+# ── State ─────────────────────────────────────────────────────────────────────
+
+_transcriber: LiveTranscriber | None = None
+_transcript_parts: list[str] = []
+_labelled_transcript: str = ""
+_document_analysis: str = ""
+_current_session_id: int | None = None
+_transcript_lock = threading.Lock()
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _patient_choices() -> list[str]:
+    patients = get_all_patients()
+    return [f"{p['id']} — {p['name']}" for p in patients] if patients else []
+
+
+def _parse_patient_choice(choice: str) -> int:
+    return int(choice.split("—")[0].strip())
+
+
+def _full_transcript() -> str:
+    with _transcript_lock:
+        return " ".join(_transcript_parts)
+
+
+def _format_icd_panel(codes: list[dict]) -> str:
+    if not codes:
+        return "_No ICD-10 suggestions._"
+    lines = ["### Suggested ICD-10 Codes\n"]
+    for c in codes:
+        lines.append(f"- **{c['code']}** — {c['description']} *(confidence: {c['score']})*")
+    return "\n".join(lines)
+
+
+def _format_drug_panel(drugs: list[dict]) -> str:
+    if not drugs:
+        return "_No drug references matched._"
+    lines = ["### Drug Reference\n"]
+    for d in drugs:
+        lines.append(
+            f"**{d['name']}** ({d['class']})\n"
+            f"- Adult dose: {d['adult_dose']}\n"
+            f"- Indications: {d['indications']}\n"
+            f"- Caution: {d['contraindications']}\n"
+        )
+    return "\n".join(lines)
+
+
+# ── Tab 1: Live Consultation ──────────────────────────────────────────────────
+
+def register_patient(name, dob, gender, phone):
+    if not name.strip():
+        return gr.update(), "Please enter a patient name."
+    pid = create_patient(name.strip(), dob, gender, phone)
+    choices = _patient_choices()
+    new_val = next((c for c in choices if c.startswith(str(pid))), choices[-1] if choices else None)
+    return gr.update(choices=choices, value=new_val), f"Patient '{name}' registered (ID {pid})."
+
+
+def start_consultation(patient_choice, doctor_name):
+    global _transcriber, _transcript_parts, _current_session_id
+
+    if not patient_choice:
+        return "No patient selected.", "", gr.update(interactive=False), gr.update(interactive=True)
+
+    pid = _parse_patient_choice(patient_choice)
+    _current_session_id = create_session(pid, doctor_name or "Doctor")
+
+    with _transcript_lock:
+        _transcript_parts.clear()
+    global _labelled_transcript, _document_analysis
+    _labelled_transcript = ""
+    _document_analysis = ""
+
+    def on_text(text):
+        with _transcript_lock:
+            _transcript_parts.append(text)
+    _transcriber = LiveTranscriber(on_text=on_text)
+    _transcriber.start()
+
+    return (
+        "Recording... speak clearly.",
+        "",
+        gr.update(interactive=True),
+        gr.update(interactive=False),
+    )
+
+
+def poll_transcript():
+    return _full_transcript()
+
+
+def stop_consultation():
+    global _transcriber, _labelled_transcript
+
+    if _transcriber:
+        _transcriber.stop()
+        _transcriber = None
+
+    raw = _full_transcript()
+    if not raw:
+        return "No audio captured.", "", gr.update(interactive=False), gr.update(interactive=True)
+
+    if _current_session_id:
+        update_transcript(_current_session_id, raw)
+
+    _labelled_transcript = clean_and_label_transcript(raw)
+
+    return (
+        "Consultation ended. Transcript cleaned ✓  Click 'Generate Notes' to proceed.",
+        _labelled_transcript,
+        gr.update(interactive=False),
+        gr.update(interactive=True),
+    )
+
+
+def upload_document(file):
+    """Analyse an uploaded medical document with Gemma 4 vision."""
+    global _document_analysis
+    if file is None:
+        _document_analysis = ""
+        return "_No document uploaded._"
+    try:
+        result = analyze_medical_document(file.name)
+        _document_analysis = result
+        return result
+    except Exception as e:
+        _document_analysis = ""
+        return f"_Document analysis failed: {e}_"
+
+
+def generate_notes():
+    """RAG retrieval → cloud agents → save to DB."""
+    # Use labelled transcript if available, fall back to raw
+    transcript = _labelled_transcript or _full_transcript()
+    if not transcript:
+        return "No transcript available.", "No transcript available.", "_No symptoms._", "_No ICD codes._", "_No drug info._", "", ""
+
+    # 1. Extract symptoms locally (Gemma 4 E2B via Ollama)
+    symptoms = extract_symptoms(transcript)
+    symptoms_md = format_symptoms_for_display(symptoms)
+
+    # 2. RAG retrieval
+    chief = symptoms.get("chief_complaint", "")
+    sym_list = symptoms.get("symptoms", [])
+    meds_list = symptoms.get("medications_mentioned", [])
+    rag_query = f"{chief} {' '.join(sym_list)}".strip() or transcript[:300]
+
+    icd_codes = retrieve_icd_codes(rag_query, n=5)
+    drug_info = retrieve_drug_info(meds_list, n=3) if meds_list else []
+
+    doc_section = f"\nUploaded Medical Document (lab result / prescription / report):\n{_document_analysis}\n" if _document_analysis else ""
+    rag_context = "\n".join(filter(None, [
+        format_icd_context(icd_codes),
+        format_drug_context(drug_info),
+        doc_section,
+    ]))
+
+    # 3. Cloud agents
+    try:
+        soap = generate_soap_note(transcript, rag_context=rag_context)
+    except Exception as e:
+        soap = f"_SOAP note generation failed: {e}_"
+
+    try:
+        summary_en = generate_patient_summary(transcript)
+    except Exception as e:
+        summary_en = f"_Summary generation failed: {e}_"
+
+    # 4. Persist
+    if _current_session_id:
+        save_note(_current_session_id, soap, summary_en, summary_twi="")
+        save_symptoms(_current_session_id, symptoms)
+        close_session(_current_session_id)
+
+    return soap, summary_en, symptoms_md, _format_icd_panel(icd_codes), _format_drug_panel(drug_info), soap, summary_en
+
+
+# ── Tab 2: Patient Records ────────────────────────────────────────────────────
+
+def load_patient_records(patient_choice):
+    if not patient_choice:
+        return "Select a patient.", "", "", ""
+
+    pid = _parse_patient_choice(patient_choice)
+    patient = get_patient(pid)
+    if not patient:
+        return "Patient not found.", "", "", ""
+
+    sessions = get_sessions_for_patient(pid)
+    if not sessions:
+        return f"No sessions found for {patient['name']}.", "", "", ""
+
+    latest = sessions[0]
+    sid = latest["id"]
+    note = get_note_for_session(sid)
+    symptoms = get_symptoms_for_session(sid)
+
+    session_info = (
+        f"**Patient:** {patient['name']}  |  **DOB:** {patient.get('dob', 'N/A')}  |  "
+        f"**Gender:** {patient.get('gender', 'N/A')}\n\n"
+        f"**Session:** {latest['date']}  |  **Doctor:** {latest.get('doctor', 'N/A')}"
+    )
+
+    soap = note["soap_note"] if note else "_No SOAP note found._"
+    summary = note["summary_en"] if note else "_No summary found._"
+    symptoms_md = format_symptoms_for_display(symptoms)
+
+    return session_info, soap, summary, symptoms_md
+
+
+# ── CSS ───────────────────────────────────────────────────────────────────────
+
+CSS = """
+body, .gradio-container { font-family: 'Segoe UI', system-ui, sans-serif; }
+
+#header-banner {
+    background: linear-gradient(135deg, #1a6eb5, #0d4f8a);
+    color: white;
+    padding: 20px 28px;
+    border-radius: 12px;
+    margin-bottom: 20px;
+}
+#header-banner h1 { margin: 0; font-size: 1.9rem; font-weight: 700; letter-spacing: -0.5px; }
+#header-banner p  { margin: 5px 0 0; opacity: 0.85; font-size: 0.95rem; }
+
+/* Fix markdown panels — transparent so they inherit theme bg */
+.gr-markdown, .svelte-1ed2p3z, [data-testid="markdown"] {
+    background: transparent !important;
+}
+
+/* Note cards — rendered SOAP/summary display */
+.note-card {
+    border: 1px solid #2d4a6e;
+    border-radius: 8px;
+    padding: 16px 20px !important;
+    min-height: 200px;
+    font-size: 0.92rem;
+    line-height: 1.7;
+}
+.note-card h1, .note-card h2, .note-card h3 {
+    color: #4a9eff;
+    margin-top: 12px;
+    font-size: 1rem;
+}
+.note-card strong { color: #7ec8ff; }
+.note-card p { margin: 6px 0; }
+.note-card ul, .note-card ol { padding-left: 20px; margin: 4px 0; }
+
+/* Status bar */
+.status-bar p { font-weight: 600; color: #4a9eff; font-size: 1rem; }
+
+/* RAG accordion open panel */
+.rag-content {
+    border-left: 3px solid #1a6eb5;
+    padding: 10px 14px;
+    border-radius: 0 6px 6px 0;
+    font-size: 0.9rem;
+}
+
+/* Tighten up accordion headers */
+.gr-accordion .label-wrap { font-weight: 600 !important; }
+
+/* Recording pulse indicator */
+@keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
+.recording p { animation: pulse 1.4s ease-in-out infinite; color: #ff4444 !important; font-weight: 700; }
+"""
+
+# ── Layout ────────────────────────────────────────────────────────────────────
+
+with gr.Blocks(title="Hospital Copilot") as demo:
+
+    gr.HTML("""
+    <div id="header-banner">
+        <h1>🏥 Hospital Copilot</h1>
+        <p>AI-powered medical documentation &nbsp;·&nbsp; Gemma 4 &nbsp;·&nbsp; RAG-grounded &nbsp;·&nbsp; Ghana</p>
+    </div>
+    """)
+
+    with gr.Tabs():
+
+        # ── Tab 1: Live Consultation ──────────────────────────────────────
+        with gr.Tab("🎙️ Live Consultation"):
+            with gr.Row(equal_height=False):
+
+                # Left column — patient panel
+                with gr.Column(scale=1, min_width=280):
+                    with gr.Group():
+                        gr.Markdown("#### 👤 Select Patient")
+                        patient_dd  = gr.Dropdown(label="Patient", choices=_patient_choices(), interactive=True)
+                        doctor_name = gr.Textbox(label="Doctor", placeholder="Dr. Mensah")
+
+                    with gr.Accordion("➕ Register New Patient", open=False):
+                        reg_name   = gr.Textbox(label="Full Name",    placeholder="Kofi Agyeman")
+                        reg_dob    = gr.Textbox(label="Date of Birth", placeholder="1985-03-15")
+                        reg_gender = gr.Radio(["Male", "Female", "Other"], label="Gender", value="Male")
+                        reg_phone  = gr.Textbox(label="Phone",         placeholder="+233 24 000 0000")
+                        reg_btn    = gr.Button("Register Patient", variant="primary")
+                        reg_status = gr.Markdown()
+
+                    reg_btn.click(
+                        register_patient,
+                        inputs=[reg_name, reg_dob, reg_gender, reg_phone],
+                        outputs=[patient_dd, reg_status],
+                    )
+
+                # Right column — consultation
+                with gr.Column(scale=3):
+                    status_txt = gr.Markdown("_Ready. Select a patient and click Start._", elem_classes=["status-bar"])
+
+                    with gr.Row():
+                        start_btn = gr.Button("▶ Start Consultation", variant="primary", scale=1)
+                        stop_btn  = gr.Button("⏹ End Consultation",   variant="stop",    scale=1, interactive=False)
+
+                    live_transcript = gr.Textbox(
+                        label="Transcript (cleaned & speaker-labelled after consultation ends)",
+                        lines=8, max_lines=16,
+                        interactive=False,
+                        placeholder="Transcript streams here as you speak. After you click End Consultation, Gemma 4 cleans and labels it automatically.",
+                    )
+                    timer = gr.Timer(value=2)
+                    timer.tick(poll_transcript, outputs=live_transcript)
+
+                    with gr.Accordion("🩺 Extracted Symptoms", open=False):
+                        symptoms_live = gr.Markdown("_Will populate after Generate Notes._")
+
+            gr.Markdown("---")
+
+            with gr.Accordion("📎 Upload Medical Document (Lab Result / Prescription / Report)", open=False):
+                gr.Markdown(
+                    "_Optional — upload a photo or PDF of a lab result, prescription, or any medical document. "
+                    "Gemma 4 will read it and include the findings in the SOAP note automatically._"
+                )
+                with gr.Row():
+                    doc_upload = gr.File(
+                        label="Upload document",
+                        file_types=[".jpg", ".jpeg", ".png", ".webp", ".pdf"],
+                        scale=1,
+                    )
+                    doc_analyse_btn = gr.Button("🔍 Analyse Document", variant="secondary", scale=0)
+                doc_result = gr.Markdown("_No document uploaded._")
+                doc_analyse_btn.click(upload_document, inputs=[doc_upload], outputs=[doc_result])
+
+            generate_btn = gr.Button("⚡ Generate Notes from Transcript", variant="primary", size="lg")
+
+            # RAG panels — inside accordions so they don't show as white boxes
+            with gr.Row():
+                with gr.Accordion("🏷️ ICD-10 Suggestions", open=True):
+                    icd_panel = gr.Markdown("_Click Generate Notes to see suggestions._")
+                with gr.Accordion("💊 Drug Reference", open=True):
+                    drug_panel = gr.Markdown("_Click Generate Notes to see drug info._")
+
+            gr.Markdown("### 📋 Generated Notes")
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("#### 🗒️ SOAP Note")
+                    soap_out = gr.Markdown(
+                        "_SOAP note will appear here after generating._",
+                        elem_classes=["note-card"],
+                    )
+                    with gr.Accordion("✏️ Edit SOAP Note", open=False):
+                        soap_edit = gr.Textbox(lines=18, interactive=True, show_label=False)
+
+                with gr.Column():
+                    gr.Markdown("#### 📄 Patient Summary")
+                    summary_en_out = gr.Markdown(
+                        "_Patient summary will appear here after generating._",
+                        elem_classes=["note-card"],
+                    )
+                    with gr.Accordion("✏️ Edit Summary", open=False):
+                        summary_edit = gr.Textbox(lines=10, interactive=True, show_label=False)
+
+            start_btn.click(
+                start_consultation,
+                inputs=[patient_dd, doctor_name],
+                outputs=[status_txt, live_transcript, stop_btn, start_btn],
+            )
+            stop_btn.click(
+                stop_consultation,
+                outputs=[status_txt, live_transcript, stop_btn, start_btn],
+            )
+            generate_btn.click(
+                generate_notes,
+                outputs=[soap_out, summary_en_out, symptoms_live, icd_panel, drug_panel, soap_edit, summary_edit],
+            )
+
+        # ── Tab 2: Patient Records ────────────────────────────────────────
+        with gr.Tab("📁 Patient Records"):
+            with gr.Row():
+                records_patient_dd = gr.Dropdown(
+                    label="Select Patient", choices=_patient_choices(), interactive=True, scale=3,
+                )
+                load_btn = gr.Button("Load Records", variant="primary", scale=1)
+
+            session_info_md = gr.Markdown()
+
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("#### 🗒️ SOAP Note")
+                    rec_soap = gr.Markdown("_Load a patient to see their SOAP note._", elem_classes=["note-card"])
+                with gr.Column():
+                    gr.Markdown("#### 📄 Patient Summary")
+                    rec_summary = gr.Markdown("_Load a patient to see their summary._", elem_classes=["note-card"])
+
+            with gr.Accordion("🩺 Extracted Symptoms", open=False):
+                rec_symptoms = gr.Markdown()
+
+            load_btn.click(
+                load_patient_records,
+                inputs=[records_patient_dd],
+                outputs=[session_info_md, rec_soap, rec_summary, rec_symptoms],
+            )
+            reg_btn.click(
+                lambda: gr.update(choices=_patient_choices()),
+                outputs=[records_patient_dd],
+            )
+
+        # ── Tab 3: About ──────────────────────────────────────────────────
+        with gr.Tab("ℹ️ About"):
+            gr.Markdown("""
+## Hospital Copilot — Gemma 4 for Good
+
+**Reducing doctor burnout. Improving care quality. Built for Ghana.**
+
+### How it works
+1. **Live Transcription** — faster-whisper converts speech to text in real time on CPU
+2. **Symptom Extraction** — Gemma 4 E2B (local, Ollama) extracts structured clinical JSON
+3. **RAG Retrieval** — sentence-transformers + ChromaDB matches ICD-10 codes and drug dosages
+4. **SOAP Note Generation** — Gemma 4 26B (cloud) writes a grounded, accurate medical note
+5. **Patient Summary** — plain-language summary the patient can take home
+6. **Structured Records** — everything saved to local SQLite
+
+### RAG Knowledge Base
+| Collection | Entries | Source |
+|---|---|---|
+| ICD-10 codes | 90+ | Ghana-relevant + general conditions |
+| Essential medicines | 40+ | WHO Essential Medicines List |
+
+### Technology Stack
+| Component | Model | Where |
+|---|---|---|
+| Speech-to-Text | faster-whisper (base) | Local CPU |
+| Symptom Extraction | Gemma 4 E2B (Q4_K_M) | Local CPU via Ollama |
+| Embeddings | all-MiniLM-L6-v2 | Local CPU |
+| Vector Store | ChromaDB | Local disk |
+| SOAP / Summary | Gemma 4 26B-IT | Google AI Studio API |
+| Storage | SQLite | Local |
+| UI | Gradio | Desktop |
+            """)
+
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860, share=False, css=CSS)

database/db.py

@@ -0,0 +1,150 @@
+import sqlite3
+import json
+from datetime import datetime
+from pathlib import Path
+
+DB_PATH = Path(__file__).parent.parent / "hospital_copilot.db"
+
+
+def get_conn():
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def init_db():
+    with get_conn() as conn:
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS patients (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                name        TEXT NOT NULL,
+                dob         TEXT,
+                gender      TEXT,
+                phone       TEXT,
+                language    TEXT DEFAULT 'en',
+                created_at  TEXT DEFAULT (datetime('now'))
+            );
+
+            CREATE TABLE IF NOT EXISTS sessions (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                patient_id  INTEGER NOT NULL REFERENCES patients(id),
+                doctor      TEXT,
+                date        TEXT DEFAULT (datetime('now')),
+                transcript  TEXT,
+                status      TEXT DEFAULT 'open'
+            );
+
+            CREATE TABLE IF NOT EXISTS notes (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id  INTEGER NOT NULL REFERENCES sessions(id),
+                soap_note   TEXT,
+                summary_en  TEXT,
+                summary_twi TEXT,
+                created_at  TEXT DEFAULT (datetime('now'))
+            );
+
+            CREATE TABLE IF NOT EXISTS symptoms (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id  INTEGER NOT NULL REFERENCES sessions(id),
+                data        TEXT,
+                created_at  TEXT DEFAULT (datetime('now'))
+            );
+        """)
+
+
+# --- Patient helpers ---
+
+def create_patient(name: str, dob: str = "", gender: str = "", phone: str = "", language: str = "en") -> int:
+    with get_conn() as conn:
+        cur = conn.execute(
+            "INSERT INTO patients (name, dob, gender, phone, language) VALUES (?, ?, ?, ?, ?)",
+            (name, dob, gender, phone, language),
+        )
+        return cur.lastrowid
+
+
+def get_all_patients() -> list[dict]:
+    with get_conn() as conn:
+        rows = conn.execute("SELECT * FROM patients ORDER BY name").fetchall()
+        return [dict(r) for r in rows]
+
+
+def get_patient(patient_id: int) -> dict | None:
+    with get_conn() as conn:
+        row = conn.execute("SELECT * FROM patients WHERE id = ?", (patient_id,)).fetchone()
+        return dict(row) if row else None
+
+
+# --- Session helpers ---
+
+def create_session(patient_id: int, doctor: str = "Dr. Unknown") -> int:
+    with get_conn() as conn:
+        cur = conn.execute(
+            "INSERT INTO sessions (patient_id, doctor) VALUES (?, ?)",
+            (patient_id, doctor),
+        )
+        return cur.lastrowid
+
+
+def update_transcript(session_id: int, transcript: str):
+    with get_conn() as conn:
+        conn.execute(
+            "UPDATE sessions SET transcript = ? WHERE id = ?",
+            (transcript, session_id),
+        )
+
+
+def close_session(session_id: int):
+    with get_conn() as conn:
+        conn.execute(
+            "UPDATE sessions SET status = 'closed' WHERE id = ?",
+            (session_id,),
+        )
+
+
+def get_sessions_for_patient(patient_id: int) -> list[dict]:
+    with get_conn() as conn:
+        rows = conn.execute(
+            "SELECT * FROM sessions WHERE patient_id = ? ORDER BY date DESC",
+            (patient_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+
+# --- Notes helpers ---
+
+def save_note(session_id: int, soap_note: str, summary_en: str, summary_twi: str) -> int:
+    with get_conn() as conn:
+        cur = conn.execute(
+            "INSERT INTO notes (session_id, soap_note, summary_en, summary_twi) VALUES (?, ?, ?, ?)",
+            (session_id, soap_note, summary_en, summary_twi),
+        )
+        return cur.lastrowid
+
+
+def get_note_for_session(session_id: int) -> dict | None:
+    with get_conn() as conn:
+        row = conn.execute(
+            "SELECT * FROM notes WHERE session_id = ? ORDER BY created_at DESC LIMIT 1",
+            (session_id,),
+        ).fetchone()
+        return dict(row) if row else None
+
+
+# --- Symptom helpers ---
+
+def save_symptoms(session_id: int, symptoms: dict):
+    with get_conn() as conn:
+        conn.execute(
+            "INSERT INTO symptoms (session_id, data) VALUES (?, ?)",
+            (session_id, json.dumps(symptoms)),
+        )
+
+
+def get_symptoms_for_session(session_id: int) -> dict:
+    with get_conn() as conn:
+        row = conn.execute(
+            "SELECT data FROM symptoms WHERE session_id = ? ORDER BY created_at DESC LIMIT 1",
+            (session_id,),
+        ).fetchone()
+        return json.loads(row["data"]) if row else {}

rag/data/essential_medicines.json

@@ -0,0 +1,416 @@
+[
+  {
+    "name": "Artemether-Lumefantrine (Coartem)",
+    "class": "Antimalarial",
+    "adult_dose": "4 tablets at 0, 8, 24, 36, 48 and 60 hours (80mg/480mg per dose)",
+    "pediatric_dose": "Weight-based: 5-14kg = 1 tab, 15-24kg = 2 tabs, 25-34kg = 3 tabs per dose",
+    "indications": "Uncomplicated Plasmodium falciparum malaria",
+    "contraindications": "First trimester pregnancy, severe malaria",
+    "notes": "Take with food or milk to improve absorption"
+  },
+  {
+    "name": "Artesunate IV",
+    "class": "Antimalarial",
+    "adult_dose": "2.4mg/kg IV at 0, 12, 24 hours then daily",
+    "pediatric_dose": "2.4mg/kg IV same schedule",
+    "indications": "Severe malaria, cerebral malaria",
+    "contraindications": "Known hypersensitivity",
+    "notes": "Preferred over quinine for severe malaria"
+  },
+  {
+    "name": "Amoxicillin",
+    "class": "Antibiotic (Beta-lactam)",
+    "adult_dose": "500mg three times daily for 5-7 days",
+    "pediatric_dose": "25-50mg/kg/day in three divided doses",
+    "indications": "Respiratory infections, ear infections, UTI, skin infections, H. pylori",
+    "contraindications": "Penicillin allergy",
+    "notes": "Can be taken with or without food"
+  },
+  {
+    "name": "Amoxicillin-Clavulanate (Augmentin)",
+    "class": "Antibiotic (Beta-lactam + inhibitor)",
+    "adult_dose": "625mg (500/125mg) three times daily for 5-7 days",
+    "pediatric_dose": "25-45mg/kg/day amoxicillin component in divided doses",
+    "indications": "Resistant infections, sinusitis, pneumonia, UTI, skin infections",
+    "contraindications": "Penicillin allergy, cholestatic jaundice from prior use",
+    "notes": "Take with food to reduce GI side effects"
+  },
+  {
+    "name": "Azithromycin",
+    "class": "Antibiotic (Macrolide)",
+    "adult_dose": "500mg on day 1, then 250mg daily for 4 days (or 500mg daily x 3 days)",
+    "pediatric_dose": "10mg/kg on day 1, then 5mg/kg daily for 4 days",
+    "indications": "Respiratory infections, typhoid, STIs, community-acquired pneumonia",
+    "contraindications": "Macrolide allergy, liver disease",
+    "notes": "Take 1 hour before or 2 hours after meals"
+  },
+  {
+    "name": "Ciprofloxacin",
+    "class": "Antibiotic (Fluoroquinolone)",
+    "adult_dose": "500mg twice daily for 5-7 days (UTI: 250-500mg twice daily x 3 days)",
+    "pediatric_dose": "Not recommended in children under 18 except specific indications",
+    "indications": "UTI, typhoid, diarrhoea, respiratory infections, skin infections",
+    "contraindications": "Children, pregnancy, tendon disorders, QT prolongation",
+    "notes": "Avoid dairy products, antacids within 2 hours"
+  },
+  {
+    "name": "Metronidazole",
+    "class": "Antibiotic/Antiprotozoal",
+    "adult_dose": "400-500mg three times daily for 5-7 days",
+    "pediatric_dose": "7.5mg/kg three times daily",
+    "indications": "Amoebic dysentery, giardiasis, anaerobic infections, bacterial vaginosis, H. pylori",
+    "contraindications": "First trimester pregnancy, alcohol use",
+    "notes": "Avoid alcohol during treatment and 48 hours after"
+  },
+  {
+    "name": "Paracetamol (Acetaminophen)",
+    "class": "Analgesic/Antipyretic",
+    "adult_dose": "500-1000mg every 4-6 hours, maximum 4g/day",
+    "pediatric_dose": "10-15mg/kg every 4-6 hours, maximum 60mg/kg/day",
+    "indications": "Pain, fever, headache, post-operative analgesia",
+    "contraindications": "Severe liver disease",
+    "notes": "Most common OTC medication. Safe in pregnancy"
+  },
+  {
+    "name": "Ibuprofen",
+    "class": "NSAID (Anti-inflammatory)",
+    "adult_dose": "400-600mg three times daily with food",
+    "pediatric_dose": "5-10mg/kg every 6-8 hours (>6 months)",
+    "indications": "Pain, fever, inflammation, dysmenorrhoea, arthritis",
+    "contraindications": "Peptic ulcer, renal impairment, third trimester pregnancy, asthma (some)",
+    "notes": "Always take with food"
+  },
+  {
+    "name": "Diclofenac",
+    "class": "NSAID",
+    "adult_dose": "75mg twice daily or 50mg three times daily",
+    "pediatric_dose": "1mg/kg twice to three times daily (>1 year)",
+    "indications": "Pain, inflammation, arthritis, musculoskeletal disorders",
+    "contraindications": "Peptic ulcer, heart failure, renal disease, third trimester pregnancy",
+    "notes": "Take with food"
+  },
+  {
+    "name": "Tramadol",
+    "class": "Opioid analgesic",
+    "adult_dose": "50-100mg every 4-6 hours, maximum 400mg/day",
+    "pediatric_dose": "1-2mg/kg every 4-6 hours (>1 year, >10kg)",
+    "indications": "Moderate to severe pain",
+    "contraindications": "Epilepsy, MAOIs, respiratory depression, children under 12",
+    "notes": "Controlled substance. Risk of dependence"
+  },
+  {
+    "name": "Omeprazole",
+    "class": "Proton Pump Inhibitor (PPI)",
+    "adult_dose": "20-40mg once daily before breakfast",
+    "pediatric_dose": "0.7-1.4mg/kg once daily (max 20mg)",
+    "indications": "GERD, peptic ulcer, H. pylori eradication, NSAID-induced ulcer prevention",
+    "contraindications": "Hypersensitivity",
+    "notes": "Take 30 minutes before meals"
+  },
+  {
+    "name": "Metformin",
+    "class": "Antidiabetic (Biguanide)",
+    "adult_dose": "500mg twice daily with meals, increase to max 2000mg/day",
+    "pediatric_dose": "Not recommended under 10 years",
+    "indications": "Type 2 diabetes mellitus, pre-diabetes",
+    "contraindications": "Renal impairment (eGFR <30), liver failure, heart failure, contrast media",
+    "notes": "Take with food. First-line therapy for T2DM"
+  },
+  {
+    "name": "Glibenclamide (Glyburide)",
+    "class": "Antidiabetic (Sulphonylurea)",
+    "adult_dose": "2.5-5mg once daily before breakfast, max 15mg/day",
+    "pediatric_dose": "Not recommended",
+    "indications": "Type 2 diabetes when metformin insufficient",
+    "contraindications": "Type 1 diabetes, renal/hepatic failure, pregnancy",
+    "notes": "Risk of hypoglycaemia. Ensure regular meals"
+  },
+  {
+    "name": "Amlodipine",
+    "class": "Antihypertensive (Calcium Channel Blocker)",
+    "adult_dose": "5-10mg once daily",
+    "pediatric_dose": "2.5-5mg once daily (6-17 years)",
+    "indications": "Hypertension, angina",
+    "contraindications": "Severe aortic stenosis, cardiogenic shock",
+    "notes": "Common side effect: ankle oedema"
+  },
+  {
+    "name": "Lisinopril",
+    "class": "Antihypertensive (ACE Inhibitor)",
+    "adult_dose": "5-10mg once daily, max 40mg/day",
+    "pediatric_dose": "0.07mg/kg once daily (>6 years)",
+    "indications": "Hypertension, heart failure, diabetic nephropathy",
+    "contraindications": "Pregnancy, bilateral renal artery stenosis, angioedema history",
+    "notes": "Common side effect: dry cough. Check renal function and potassium"
+  },
+  {
+    "name": "Atenolol",
+    "class": "Antihypertensive (Beta-blocker)",
+    "adult_dose": "25-100mg once daily",
+    "pediatric_dose": "0.5-1mg/kg once daily",
+    "indications": "Hypertension, angina, arrhythmia, post-MI",
+    "contraindications": "Asthma, bradycardia, heart block, cardiogenic shock",
+    "notes": "Do not stop abruptly"
+  },
+  {
+    "name": "Hydrochlorothiazide",
+    "class": "Antihypertensive (Thiazide Diuretic)",
+    "adult_dose": "12.5-25mg once daily in the morning",
+    "pediatric_dose": "1-2mg/kg/day in one or two doses",
+    "indications": "Hypertension, oedema",
+    "contraindications": "Anuria, hypersensitivity to sulfonamides, gout",
+    "notes": "Monitor electrolytes, especially potassium"
+  },
+  {
+    "name": "Furosemide (Frusemide)",
+    "class": "Loop Diuretic",
+    "adult_dose": "20-80mg once or twice daily",
+    "pediatric_dose": "1-2mg/kg once or twice daily",
+    "indications": "Heart failure, oedema, hypertension, pulmonary oedema",
+    "contraindications": "Anuria, hypovolaemia, hypokalaemia",
+    "notes": "Monitor electrolytes and renal function"
+  },
+  {
+    "name": "Atorvastatin",
+    "class": "Lipid-lowering (Statin)",
+    "adult_dose": "10-80mg once daily at night",
+    "pediatric_dose": "10-20mg daily (10-17 years with familial hypercholesterolaemia)",
+    "indications": "Hypercholesterolaemia, cardiovascular risk reduction",
+    "contraindications": "Active liver disease, pregnancy, breastfeeding",
+    "notes": "Preferably take in the evening. Monitor LFTs"
+  },
+  {
+    "name": "Aspirin",
+    "class": "Antiplatelet/NSAID",
+    "adult_dose": "75-150mg once daily (antiplatelet); 300-900mg every 4-6 hours (analgesia)",
+    "pediatric_dose": "Avoid in children under 16 (Reye syndrome risk)",
+    "indications": "Antiplatelet: MI prevention, stroke prevention, ACS; Analgesic: pain fever",
+    "contraindications": "Children under 16, peptic ulcer, bleeding disorders, third trimester",
+    "notes": "Irreversibly inhibits platelets"
+  },
+  {
+    "name": "Cotrimoxazole (Trimethoprim-Sulfamethoxazole)",
+    "class": "Antibiotic/Anti-infective",
+    "adult_dose": "960mg (2 standard tablets) twice daily for 5-7 days",
+    "pediatric_dose": "4/20mg/kg twice daily",
+    "indications": "UTI, chest infections, toxoplasmosis prophylaxis in HIV, PCP prophylaxis",
+    "contraindications": "Sulfonamide allergy, G6PD deficiency, severe renal/hepatic failure",
+    "notes": "Ensure adequate fluid intake"
+  },
+  {
+    "name": "Chlorphenamine (Chlorpheniramine)",
+    "class": "Antihistamine (1st generation)",
+    "adult_dose": "4mg every 4-6 hours, max 24mg/day",
+    "pediatric_dose": "0.1mg/kg every 6 hours",
+    "indications": "Allergic reactions, urticaria, hay fever, pruritus",
+    "contraindications": "Glaucoma, urinary retention, MAOIs",
+    "notes": "Causes drowsiness. Avoid driving"
+  },
+  {
+    "name": "Cetirizine",
+    "class": "Antihistamine (2nd generation)",
+    "adult_dose": "10mg once daily",
+    "pediatric_dose": "5mg once or twice daily (6-11 years); 2.5mg twice daily (2-5 years)",
+    "indications": "Allergic rhinitis, urticaria, eczema, allergic reactions",
+    "contraindications": "Severe renal impairment",
+    "notes": "Less sedating than chlorphenamine"
+  },
+  {
+    "name": "Salbutamol (Albuterol)",
+    "class": "Bronchodilator (Short-acting beta-2 agonist)",
+    "adult_dose": "100-200mcg (1-2 puffs) every 4-6 hours as needed",
+    "pediatric_dose": "100mcg (1 puff) as needed (under supervision)",
+    "indications": "Asthma, COPD, bronchospasm",
+    "contraindications": "Tachyarrhythmia",
+    "notes": "Shake inhaler. Rinse mouth after use if using spacer with steroid"
+  },
+  {
+    "name": "Prednisolone",
+    "class": "Corticosteroid",
+    "adult_dose": "5-60mg daily depending on indication",
+    "pediatric_dose": "1-2mg/kg/day in divided doses",
+    "indications": "Asthma exacerbation, severe allergic reactions, autoimmune conditions, inflammation",
+    "contraindications": "Systemic infections (without antibiotics), live vaccines",
+    "notes": "Do not stop abruptly if on long-term therapy"
+  },
+  {
+    "name": "Dexamethasone",
+    "class": "Corticosteroid",
+    "adult_dose": "0.5-24mg daily depending on indication",
+    "pediatric_dose": "0.08-0.3mg/kg/day",
+    "indications": "Severe asthma, croup, cerebral oedema, severe COVID-19, meningitis",
+    "contraindications": "Systemic fungal infections",
+    "notes": "More potent than prednisolone. IV/IM for severe conditions"
+  },
+  {
+    "name": "ORS (Oral Rehydration Salts)",
+    "class": "Rehydration therapy",
+    "adult_dose": "200-400mL after each loose stool, aiming for 3L/day",
+    "pediatric_dose": "50-100mL/kg over 3-4 hours for mild dehydration",
+    "indications": "Diarrhoea, dehydration, cholera",
+    "contraindications": "Severe dehydration requiring IV fluids, ileus",
+    "notes": "First-line for diarrhoeal disease in all ages"
+  },
+  {
+    "name": "Zinc Sulphate",
+    "class": "Micronutrient supplement",
+    "adult_dose": "20mg once daily",
+    "pediatric_dose": "10mg/day under 6 months; 20mg/day over 6 months for 10-14 days with ORS",
+    "indications": "Diarrhoea (adjunct), zinc deficiency, growth faltering",
+    "contraindications": "Hypersensitivity",
+    "notes": "Reduces duration and severity of diarrhoea in children"
+  },
+  {
+    "name": "Folic Acid",
+    "class": "Vitamin/Haematinic",
+    "adult_dose": "5mg once daily (therapeutic); 400mcg daily (prophylactic in pregnancy)",
+    "pediatric_dose": "500mcg/kg/day",
+    "indications": "Megaloblastic anaemia, pregnancy (neural tube defect prevention), haemolytic anaemia",
+    "contraindications": "Undiagnosed anaemia (may mask B12 deficiency)",
+    "notes": "Ideally start 3 months before conception"
+  },
+  {
+    "name": "Ferrous Sulphate",
+    "class": "Iron supplement",
+    "adult_dose": "200mg (65mg elemental iron) three times daily",
+    "pediatric_dose": "3-6mg/kg/day elemental iron in divided doses",
+    "indications": "Iron deficiency anaemia, pregnancy iron supplementation",
+    "contraindications": "Haemochromatosis, repeated blood transfusions",
+    "notes": "Take on empty stomach or with vitamin C. Stools may turn black"
+  },
+  {
+    "name": "Vitamin A",
+    "class": "Fat-soluble vitamin",
+    "adult_dose": "200,000 IU once (for deficiency or measles)",
+    "pediatric_dose": "100,000 IU (6-11 months); 200,000 IU (>12 months) every 6 months",
+    "indications": "Vitamin A deficiency, measles, night blindness, malnutrition",
+    "contraindications": "Pregnancy (high dose teratogenic)",
+    "notes": "Part of national immunisation programme in Ghana"
+  },
+  {
+    "name": "Gentamicin",
+    "class": "Antibiotic (Aminoglycoside)",
+    "adult_dose": "5-7mg/kg IV/IM once daily",
+    "pediatric_dose": "7.5mg/kg/day divided every 8 hours (neonatal: 4-7mg/kg/day)",
+    "indications": "Serious gram-negative infections, sepsis, neonatal sepsis",
+    "contraindications": "Renal impairment, myasthenia gravis",
+    "notes": "Monitor renal function and drug levels. Ototoxic and nephrotoxic"
+  },
+  {
+    "name": "Benzylpenicillin (Penicillin G)",
+    "class": "Antibiotic (Beta-lactam)",
+    "adult_dose": "1.2-2.4g IV every 4-6 hours",
+    "pediatric_dose": "50,000-100,000 units/kg/day divided every 4-6 hours",
+    "indications": "Meningitis, septicaemia, pneumonia, syphilis, neonatal infections",
+    "contraindications": "Penicillin allergy",
+    "notes": "IV administration. Monitor for hypersensitivity"
+  },
+  {
+    "name": "Ceftriaxone",
+    "class": "Antibiotic (3rd generation Cephalosporin)",
+    "adult_dose": "1-2g IV/IM once daily",
+    "pediatric_dose": "50-100mg/kg once daily (max 4g/day)",
+    "indications": "Meningitis, severe pneumonia, typhoid, sepsis, gonorrhoea",
+    "contraindications": "Cephalosporin allergy, neonates with hyperbilirubinaemia",
+    "notes": "Can be given IM (with lidocaine) or IV"
+  },
+  {
+    "name": "Fluconazole",
+    "class": "Antifungal",
+    "adult_dose": "150mg single dose (vaginal candidiasis); 200mg daily (systemic)",
+    "pediatric_dose": "3-12mg/kg/day",
+    "indications": "Candidiasis, cryptococcal meningitis, tinea infections",
+    "contraindications": "Hepatic impairment (high doses), QT prolongation",
+    "notes": "Significant drug interactions including with warfarin and statins"
+  },
+  {
+    "name": "Tenofovir-Lamivudine-Dolutegravir (TLD)",
+    "class": "Antiretroviral (NRTI + INSTI)",
+    "adult_dose": "One tablet (300/300/50mg) once daily",
+    "pediatric_dose": "Weight-band dosing for children",
+    "indications": "HIV-1 infection (first-line regimen in Ghana)",
+    "contraindications": "Severe renal impairment",
+    "notes": "Current WHO-recommended first-line ART. Take at same time daily"
+  },
+  {
+    "name": "Isoniazid",
+    "class": "Anti-tuberculosis",
+    "adult_dose": "5mg/kg (max 300mg) once daily",
+    "pediatric_dose": "10mg/kg (max 300mg) once daily",
+    "indications": "Tuberculosis treatment and prophylaxis",
+    "contraindications": "Severe liver disease, peripheral neuropathy",
+    "notes": "Give with pyridoxine (B6) to prevent peripheral neuropathy"
+  },
+  {
+    "name": "Rifampicin",
+    "class": "Anti-tuberculosis",
+    "adult_dose": "10mg/kg (max 600mg) once daily on empty stomach",
+    "pediatric_dose": "15mg/kg (max 600mg) once daily",
+    "indications": "Tuberculosis, leprosy, Neisseria meningitidis prophylaxis",
+    "contraindications": "Severe liver disease, jaundice",
+    "notes": "Turns urine/sweat/tears orange. Many drug interactions"
+  },
+  {
+    "name": "Diazepam",
+    "class": "Benzodiazepine/Anticonvulsant",
+    "adult_dose": "5-10mg IV slowly for seizures; 2-10mg orally for anxiety",
+    "pediatric_dose": "0.2-0.5mg/kg IV (max 10mg) for seizures; rectal: 0.5mg/kg",
+    "indications": "Seizures, status epilepticus, anxiety, muscle spasm, alcohol withdrawal",
+    "contraindications": "Respiratory depression, sleep apnoea, severe liver disease",
+    "notes": "Controlled substance. Risk of dependence"
+  },
+  {
+    "name": "Phenobarbital",
+    "class": "Anticonvulsant (Barbiturate)",
+    "adult_dose": "60-180mg at night (maintenance); 15-20mg/kg IV for status epilepticus",
+    "pediatric_dose": "3-5mg/kg/day (maintenance); 15-20mg/kg IV (status epilepticus)",
+    "indications": "Epilepsy, status epilepticus, neonatal seizures",
+    "contraindications": "Respiratory depression, porphyria",
+    "notes": "Long-acting. First-line for neonatal seizures"
+  },
+  {
+    "name": "Misoprostol",
+    "class": "Prostaglandin (Uterotonic)",
+    "adult_dose": "600mcg sublingual or 800mcg rectally for PPH",
+    "pediatric_dose": "N/A",
+    "indications": "Prevention and treatment of postpartum haemorrhage, medical abortion, cervical ripening",
+    "contraindications": "Allergy to prostaglandins",
+    "notes": "Essential medicine for maternal health"
+  },
+  {
+    "name": "Magnesium Sulphate",
+    "class": "Anticonvulsant/Tocolytic",
+    "adult_dose": "4g IV loading over 20 min, then 1g/hour maintenance",
+    "pediatric_dose": "25-50mg/kg for hypomagnesaemia",
+    "indications": "Pre-eclampsia, eclampsia seizure prophylaxis and treatment",
+    "contraindications": "Renal failure, myasthenia gravis",
+    "notes": "Monitor deep tendon reflexes, respiratory rate, urine output"
+  },
+  {
+    "name": "Insulin (Regular/Soluble)",
+    "class": "Antidiabetic hormone",
+    "adult_dose": "Individualised; DKA: 0.1 units/kg/hour IV",
+    "pediatric_dose": "Individualised",
+    "indications": "Type 1 diabetes, Type 2 diabetes (uncontrolled), diabetic ketoacidosis",
+    "contraindications": "Hypoglycaemia",
+    "notes": "Store in refrigerator. Monitor blood glucose closely"
+  },
+  {
+    "name": "Hydrocortisone",
+    "class": "Corticosteroid",
+    "adult_dose": "100-500mg IV every 6-8 hours (emergency); 20-30mg oral daily (replacement)",
+    "pediatric_dose": "2-8mg/kg IV (emergency)",
+    "indications": "Adrenal crisis, severe allergic reactions, anaphylaxis, severe asthma",
+    "contraindications": "Systemic infections without antimicrobials",
+    "notes": "IV for emergencies. Mineralocorticoid effects at high doses"
+  },
+  {
+    "name": "Adrenaline (Epinephrine)",
+    "class": "Sympathomimetic",
+    "adult_dose": "0.5mg (0.5mL of 1:1000) IM for anaphylaxis; repeat after 5 min if needed",
+    "pediatric_dose": "0.01mg/kg IM (max 0.5mg)",
+    "indications": "Anaphylaxis, cardiac arrest, severe asthma",
+    "contraindications": "No absolute contraindications in life-threatening emergencies",
+    "notes": "Outer mid-thigh IM injection. Store away from light"
+  }
+]

rag/data/icd10_common.json

@@ -0,0 +1,103 @@
+[
+  {"code": "B54", "description": "Unspecified malaria", "keywords": "malaria fever chills rigors sweating headache vomiting anaemia"},
+  {"code": "B50.0", "description": "Plasmodium falciparum malaria with cerebral complications", "keywords": "cerebral malaria coma seizures severe malaria falciparum"},
+  {"code": "B50.9", "description": "Plasmodium falciparum malaria, unspecified", "keywords": "malaria falciparum fever Africa Ghana tropical"},
+  {"code": "A01.0", "description": "Typhoid fever", "keywords": "typhoid enteric fever salmonella sustained fever abdominal pain rose spots"},
+  {"code": "A09", "description": "Diarrhoea and gastroenteritis of presumed infectious origin", "keywords": "diarrhoea gastroenteritis vomiting loose stools dehydration"},
+  {"code": "A00.9", "description": "Cholera, unspecified", "keywords": "cholera rice water stools severe dehydration watery diarrhoea"},
+  {"code": "A15.0", "description": "Tuberculosis of lung, confirmed by sputum microscopy", "keywords": "tuberculosis TB pulmonary cough blood haemoptysis night sweats weight loss"},
+  {"code": "A16.2", "description": "Tuberculosis of lung, without mention of bacteriological confirmation", "keywords": "TB tuberculosis cough chronic lung weight loss"},
+  {"code": "B20", "description": "Human immunodeficiency virus disease resulting in infectious and parasitic diseases", "keywords": "HIV AIDS opportunistic infection immune"},
+  {"code": "B24", "description": "Unspecified human immunodeficiency virus disease", "keywords": "HIV AIDS retroviral disease"},
+  {"code": "B19.9", "description": "Unspecified viral hepatitis without hepatic coma", "keywords": "hepatitis jaundice liver yellow eyes dark urine"},
+  {"code": "A77.9", "description": "Spotted fever, unspecified", "keywords": "spotted fever tick rickettsia rash fever"},
+  {"code": "B65.9", "description": "Schistosomiasis, unspecified", "keywords": "schistosomiasis bilharzia blood urine haematuria"},
+  {"code": "B76.9", "description": "Hookworm disease, unspecified", "keywords": "hookworm anaemia soil transmitted helminth worm"},
+  {"code": "B74.0", "description": "Filariasis due to Wuchereria bancrofti", "keywords": "filariasis lymphoedema elephantiasis swollen leg"},
+
+  {"code": "J06.9", "description": "Acute upper respiratory infection, unspecified", "keywords": "cold cough sore throat runny nose nasal congestion upper respiratory"},
+  {"code": "J00", "description": "Acute nasopharyngitis (common cold)", "keywords": "common cold rhinitis sneezing runny nose"},
+  {"code": "J02.9", "description": "Acute pharyngitis, unspecified", "keywords": "sore throat pharyngitis throat pain difficulty swallowing"},
+  {"code": "J03.9", "description": "Acute tonsillitis, unspecified", "keywords": "tonsillitis swollen tonsils sore throat fever pus"},
+  {"code": "J18.9", "description": "Pneumonia, unspecified organism", "keywords": "pneumonia chest infection cough fever shortness of breath sputum"},
+  {"code": "J20.9", "description": "Acute bronchitis, unspecified", "keywords": "bronchitis cough chest mucus productive cough"},
+  {"code": "J45.9", "description": "Asthma, unspecified", "keywords": "asthma wheeze shortness of breath inhaler bronchospasm"},
+  {"code": "J44.1", "description": "Chronic obstructive pulmonary disease with acute exacerbation", "keywords": "COPD breathlessness chronic lung disease exacerbation"},
+  {"code": "J30.9", "description": "Allergic rhinitis, unspecified", "keywords": "allergic rhinitis hay fever sneezing itchy nose dust allergy"},
+
+  {"code": "I10", "description": "Essential (primary) hypertension", "keywords": "hypertension high blood pressure HTN headache"},
+  {"code": "I11.9", "description": "Hypertensive heart disease without heart failure", "keywords": "hypertensive heart disease high blood pressure cardiac"},
+  {"code": "I50.9", "description": "Heart failure, unspecified", "keywords": "heart failure cardiac failure breathlessness oedema swollen legs"},
+  {"code": "I20.9", "description": "Angina pectoris, unspecified", "keywords": "angina chest pain exertion heart coronary"},
+  {"code": "I21.9", "description": "Acute myocardial infarction, unspecified", "keywords": "heart attack myocardial infarction MI chest pain severe"},
+  {"code": "I64", "description": "Stroke, not specified as haemorrhage or infarction", "keywords": "stroke CVA weakness facial droop speech difficulty paralysis"},
+  {"code": "I63.9", "description": "Cerebral infarction, unspecified", "keywords": "ischaemic stroke brain infarction weakness hemiplegia"},
+
+  {"code": "E11.9", "description": "Type 2 diabetes mellitus without complications", "keywords": "diabetes mellitus type 2 blood sugar hyperglycaemia thirst urination"},
+  {"code": "E10.9", "description": "Type 1 diabetes mellitus without complications", "keywords": "type 1 diabetes insulin dependent juvenile diabetes"},
+  {"code": "E11.5", "description": "Type 2 diabetes mellitus with peripheral circulatory complications", "keywords": "diabetic foot ulcer peripheral vascular disease gangrene"},
+  {"code": "E11.3", "description": "Type 2 diabetes mellitus with ophthalmic complications", "keywords": "diabetic retinopathy vision loss eye diabetes"},
+  {"code": "E66.9", "description": "Obesity, unspecified", "keywords": "obesity overweight BMI weight"},
+  {"code": "E46", "description": "Unspecified protein-calorie malnutrition", "keywords": "malnutrition underweight protein deficiency wasting"},
+  {"code": "E43", "description": "Unspecified severe protein-calorie malnutrition", "keywords": "severe malnutrition kwashiorkor marasmus oedema wasting"},
+  {"code": "D50.9", "description": "Iron deficiency anaemia, unspecified", "keywords": "anaemia iron deficiency pallor fatigue tiredness weakness"},
+  {"code": "D64.9", "description": "Anaemia, unspecified", "keywords": "anaemia pallor fatigue weakness low blood count"},
+
+  {"code": "K29.7", "description": "Gastritis, unspecified", "keywords": "gastritis stomach pain epigastric pain nausea indigestion"},
+  {"code": "K21.0", "description": "Gastro-oesophageal reflux disease with oesophagitis", "keywords": "GERD acid reflux heartburn regurgitation burning chest"},
+  {"code": "K35.9", "description": "Acute appendicitis, unspecified", "keywords": "appendicitis right lower quadrant pain RLQ nausea vomiting fever"},
+  {"code": "K80.20", "description": "Calculus of gallbladder without cholecystitis", "keywords": "gallstones cholelithiasis right upper quadrant pain fatty food"},
+  {"code": "K92.1", "description": "Melaena", "keywords": "melaena black stool blood stool GI bleed upper gastrointestinal"},
+  {"code": "K57.30", "description": "Diverticulosis of large intestine without perforation", "keywords": "diverticulosis colon lower abdominal pain constipation"},
+
+  {"code": "N39.0", "description": "Urinary tract infection, site not specified", "keywords": "UTI urinary infection dysuria frequency burning urination"},
+  {"code": "N40", "description": "Enlarged prostate", "keywords": "BPH benign prostatic hyperplasia urinary retention frequency nocturia"},
+  {"code": "N18.9", "description": "Chronic kidney disease, unspecified", "keywords": "CKD renal failure kidney disease creatinine oedema"},
+  {"code": "N10", "description": "Acute pyelonephritis", "keywords": "pyelonephritis kidney infection loin pain fever urinary"},
+
+  {"code": "G43.9", "description": "Migraine, unspecified", "keywords": "migraine severe headache throbbing nausea light sensitivity aura"},
+  {"code": "R51", "description": "Headache", "keywords": "headache head pain cephalalgia tension headache"},
+  {"code": "G40.9", "description": "Epilepsy, unspecified", "keywords": "epilepsy seizure convulsion fits loss of consciousness"},
+  {"code": "G35", "description": "Multiple sclerosis", "keywords": "multiple sclerosis MS weakness numbness vision fatigue"},
+  {"code": "F32.9", "description": "Depressive episode, unspecified", "keywords": "depression low mood sadness hopelessness sleep appetite loss"},
+  {"code": "F41.1", "description": "Generalised anxiety disorder", "keywords": "anxiety worry generalised anxiety disorder GAD nervousness"},
+  {"code": "F20.9", "description": "Schizophrenia, unspecified", "keywords": "schizophrenia psychosis hallucinations delusions mental illness"},
+
+  {"code": "M54.5", "description": "Low back pain", "keywords": "back pain lower back lumbar pain lumbago"},
+  {"code": "M54.2", "description": "Cervicalgia", "keywords": "neck pain cervical pain stiff neck"},
+  {"code": "M25.5", "description": "Pain in joint", "keywords": "joint pain arthralgia knee hip shoulder elbow joint"},
+  {"code": "M06.9", "description": "Rheumatoid arthritis, unspecified", "keywords": "rheumatoid arthritis RA joint swelling morning stiffness"},
+  {"code": "M10.9", "description": "Gout, unspecified", "keywords": "gout uric acid joint pain big toe swollen joint"},
+
+  {"code": "O80", "description": "Encounter for full-term uncomplicated delivery", "keywords": "normal delivery labour birth full term vaginal delivery"},
+  {"code": "O14.9", "description": "Pre-eclampsia, unspecified", "keywords": "pre-eclampsia hypertension pregnancy oedema proteinuria"},
+  {"code": "O20.0", "description": "Threatened abortion", "keywords": "threatened miscarriage bleeding pregnancy spotting"},
+  {"code": "O03.9", "description": "Spontaneous abortion, complete or unspecified", "keywords": "miscarriage spontaneous abortion pregnancy loss"},
+  {"code": "O42.9", "description": "Premature rupture of membranes, unspecified", "keywords": "PROM ruptured membranes water broke premature labour"},
+  {"code": "P07.3", "description": "Other preterm infants", "keywords": "premature baby preterm birth low birth weight"},
+
+  {"code": "L50.9", "description": "Urticaria, unspecified", "keywords": "hives urticaria itchy rash allergic skin reaction welts"},
+  {"code": "L20.9", "description": "Atopic dermatitis, unspecified", "keywords": "eczema atopic dermatitis itchy skin rash"},
+  {"code": "B35.9", "description": "Dermatophytosis, unspecified", "keywords": "ringworm tinea fungal skin infection itchy rash"},
+  {"code": "L03.9", "description": "Cellulitis, unspecified", "keywords": "cellulitis skin infection red swollen hot skin bacterial"},
+
+  {"code": "R50.9", "description": "Fever, unspecified", "keywords": "fever pyrexia high temperature febrile"},
+  {"code": "R05", "description": "Cough", "keywords": "cough dry cough productive cough chronic cough"},
+  {"code": "R06.0", "description": "Dyspnoea", "keywords": "breathlessness shortness of breath dyspnoea difficulty breathing"},
+  {"code": "R10.4", "description": "Other and unspecified abdominal pain", "keywords": "abdominal pain stomach ache belly pain"},
+  {"code": "R11.2", "description": "Nausea with vomiting, unspecified", "keywords": "nausea vomiting queasy sick stomach"},
+  {"code": "R55", "description": "Syncope and collapse", "keywords": "fainting syncope collapse blackout loss of consciousness"},
+  {"code": "R00.0", "description": "Tachycardia, unspecified", "keywords": "fast heart rate palpitations racing heart tachycardia"},
+  {"code": "R73.09", "description": "Other abnormal glucose", "keywords": "high blood sugar hyperglycaemia pre-diabetes glucose"},
+
+  {"code": "S09.9", "description": "Unspecified injury of head", "keywords": "head injury trauma concussion fall accident"},
+  {"code": "T14.9", "description": "Injury, unspecified", "keywords": "injury trauma wound accident"},
+  {"code": "S72.9", "description": "Fracture of femur, unspecified", "keywords": "broken bone fracture hip femur"},
+  {"code": "T78.40", "description": "Allergy, unspecified", "keywords": "allergy allergic reaction hypersensitivity"},
+  {"code": "T36.9", "description": "Poisoning by unspecified systemic antibiotic", "keywords": "antibiotic poisoning drug reaction adverse effect"},
+
+  {"code": "Z00.0", "description": "General adult medical examination", "keywords": "check-up routine examination general health review"},
+  {"code": "Z23", "description": "Encounter for immunization", "keywords": "vaccination immunization vaccine injection"},
+  {"code": "Z30.0", "description": "Encounter for general counselling and advice on contraception", "keywords": "family planning contraception birth control counselling"},
+  {"code": "Z71.3", "description": "Encounter for dietary counselling and surveillance", "keywords": "diet nutrition counselling weight management"}
+]

rag/retriever.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import chromadb
+from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction
+
+DATA_DIR = Path(__file__).parent / "data"
+DB_DIR = Path(__file__).parent.parent / "chroma_db"
+
+EMBED_MODEL = "all-MiniLM-L6-v2"
+
+_client: chromadb.PersistentClient | None = None
+_icd_col = None
+_drug_col = None
+
+
+def _get_client():
+    global _client
+    if _client is None:
+        _client = chromadb.PersistentClient(path=str(DB_DIR))
+    return _client
+
+
+def _embedding_fn():
+    return SentenceTransformerEmbeddingFunction(model_name=EMBED_MODEL)
+
+
+def build_knowledge_base(force: bool = False):
+    """Embed ICD-10 codes and medicines into ChromaDB. Runs once; skipped if DB exists."""
+    client = _get_client()
+    ef = _embedding_fn()
+
+    existing = [c.name for c in client.list_collections()]
+
+    # ── ICD-10 ──────────────────────────────────────────────────────────────
+    if "icd10" not in existing or force:
+        if "icd10" in existing:
+            client.delete_collection("icd10")
+        col = client.create_collection("icd10", embedding_function=ef)
+        with open(DATA_DIR / "icd10_common.json") as f:
+            records = json.load(f)
+        col.add(
+            ids=[r["code"] for r in records],
+            documents=[f"{r['description']} {r['keywords']}" for r in records],
+            metadatas=[{"code": r["code"], "description": r["description"]} for r in records],
+        )
+        print(f"[RAG] Indexed {len(records)} ICD-10 codes")
+
+    # ── Medicines ────────────────────────────────────────────────────────────
+    if "medicines" not in existing or force:
+        if "medicines" in existing:
+            client.delete_collection("medicines")
+        col = client.create_collection("medicines", embedding_function=ef)
+        with open(DATA_DIR / "essential_medicines.json") as f:
+            records = json.load(f)
+        col.add(
+            ids=[str(i) for i in range(len(records))],
+            documents=[
+                f"{r['name']} {r['class']} {r['indications']}"
+                for r in records
+            ],
+            metadatas=records,
+        )
+        print(f"[RAG] Indexed {len(records)} essential medicines")
+
+
+def _icd_collection():
+    global _icd_col
+    if _icd_col is None:
+        _icd_col = _get_client().get_collection("icd10", embedding_function=_embedding_fn())
+    return _icd_col
+
+
+def _drug_collection():
+    global _drug_col
+    if _drug_col is None:
+        _drug_col = _get_client().get_collection("medicines", embedding_function=_embedding_fn())
+    return _drug_col
+
+
+def retrieve_icd_codes(query: str, n: int = 5) -> list[dict]:
+    """Return top-n ICD-10 codes matching the clinical query."""
+    if not query.strip():
+        return []
+    results = _icd_collection().query(query_texts=[query], n_results=n)
+    codes = []
+    for meta, dist in zip(results["metadatas"][0], results["distances"][0]):
+        codes.append({
+            "code": meta["code"],
+            "description": meta["description"],
+            "score": round(1 - dist, 3),
+        })
+    return codes
+
+
+def retrieve_drug_info(drug_names: list[str], n: int = 3) -> list[dict]:
+    """Return drug info for each named medication. Falls back to closest match."""
+    if not drug_names:
+        return []
+    query = ", ".join(drug_names)
+    results = _drug_collection().query(query_texts=[query], n_results=n)
+    drugs = []
+    for meta in results["metadatas"][0]:
+        drugs.append({
+            "name": meta["name"],
+            "class": meta["class"],
+            "adult_dose": meta["adult_dose"],
+            "indications": meta["indications"],
+            "contraindications": meta["contraindications"],
+            "notes": meta.get("notes", ""),
+        })
+    return drugs
+
+
+def format_icd_context(codes: list[dict]) -> str:
+    """Format ICD codes as text context for injection into prompts."""
+    if not codes:
+        return ""
+    lines = ["Relevant ICD-10 codes to consider:"]
+    for c in codes:
+        lines.append(f"  {c['code']} — {c['description']}")
+    return "\n".join(lines)
+
+
+def format_drug_context(drugs: list[dict]) -> str:
+    """Format drug info as text context for injection into prompts."""
+    if not drugs:
+        return ""
+    lines = ["Relevant medication reference:"]
+    for d in drugs:
+        lines.append(
+            f"  {d['name']} ({d['class']}): {d['adult_dose']}. "
+            f"Indications: {d['indications']}."
+        )
+    return "\n".join(lines)
+
+
+def ensure_kb():
+    """Called at app startup — builds KB only if it doesn't exist yet."""
+    client = _get_client()
+    existing = [c.name for c in client.list_collections()]
+    if "icd10" not in existing or "medicines" not in existing:
+        print("[RAG] Building knowledge base for the first time...")
+        build_knowledge_base()
+    else:
+        print("[RAG] Knowledge base ready.")

requirements.txt

@@ -0,0 +1,11 @@
+gradio>=4.44.0
+faster-whisper>=1.0.0
+ollama>=0.3.0
+google-genai>=1.0.0
+sounddevice>=0.4.6
+numpy>=1.26.0
+scipy>=1.13.0
+python-dotenv>=1.0.0
+fpdf2>=2.7.9
+chromadb>=0.5.0
+sentence-transformers>=3.0.0

transcription/transcriber.py

@@ -0,0 +1,125 @@
+import os
+import queue
+import tempfile
+import threading
+import wave
+import numpy as np
+import sounddevice as sd
+from faster_whisper import WhisperModel
+
+SAMPLE_RATE = 16000
+BLOCK_SECONDS = 3
+CHANNELS = 1
+
+_model: WhisperModel | None = None
+
+
+def _load_model() -> WhisperModel:
+    global _model
+    if _model is None:
+        model_size = os.getenv("WHISPER_MODEL", "small")
+        _model = WhisperModel(model_size, device="cpu", compute_type="int8")
+    return _model
+
+
+class LiveTranscriber:
+    """
+    Streams microphone audio, transcribes in real time, and saves the full
+    session to a WAV file for post-hoc speaker diarization.
+    """
+
+    def __init__(self, on_text):
+        self.on_text = on_text
+        self._audio_q: queue.Queue = queue.Queue()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._stream: sd.InputStream | None = None
+
+        # accumulate all raw audio for diarization
+        self._all_audio: list[np.ndarray] = []
+        self._audio_lock = threading.Lock()
+
+        # path to saved WAV after stop()
+        self.wav_path: str | None = None
+
+    def _audio_callback(self, indata, frames, time_info, status):
+        chunk = indata.copy()
+        self._audio_q.put(chunk)
+        with self._audio_lock:
+            self._all_audio.append(chunk.flatten())
+
+    def _process_loop(self):
+        model = _load_model()
+        buffer = np.empty((0,), dtype=np.float32)
+        chunk_size = SAMPLE_RATE * BLOCK_SECONDS
+
+        while not self._stop_event.is_set():
+            try:
+                chunk = self._audio_q.get(timeout=0.5)
+                buffer = np.concatenate([buffer, chunk.flatten()])
+            except queue.Empty:
+                continue
+
+            if len(buffer) >= chunk_size:
+                audio_chunk = buffer[:chunk_size].astype(np.float32)
+                buffer = buffer[chunk_size:]
+                segments, _ = model.transcribe(
+                    audio_chunk,
+                    language="en",
+                    vad_filter=True,
+                    vad_parameters={"min_silence_duration_ms": 300},
+                )
+                text = " ".join(s.text for s in segments).strip()
+                if text:
+                    self.on_text(text)
+
+        # flush remaining audio
+        if len(buffer) > SAMPLE_RATE:
+            segments, _ = _load_model().transcribe(
+                buffer.astype(np.float32), language="en", vad_filter=True
+            )
+            text = " ".join(s.text for s in segments).strip()
+            if text:
+                self.on_text(text)
+
+    def start(self):
+        self._stop_event.clear()
+        self._all_audio.clear()
+        self._stream = sd.InputStream(
+            samplerate=SAMPLE_RATE,
+            channels=CHANNELS,
+            dtype="float32",
+            blocksize=SAMPLE_RATE,
+            callback=self._audio_callback,
+        )
+        self._stream.start()
+        self._thread = threading.Thread(target=self._process_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> str | None:
+        """Stop recording and save full audio to a WAV file. Returns the WAV path."""
+        self._stop_event.set()
+        if self._stream:
+            self._stream.stop()
+            self._stream.close()
+        if self._thread:
+            self._thread.join(timeout=5)
+
+        with self._audio_lock:
+            all_audio = list(self._all_audio)
+
+        if not all_audio:
+            return None
+
+        full_audio = np.concatenate(all_audio).astype(np.float32)
+        pcm = (full_audio * 32767).astype(np.int16)
+
+        tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+        with wave.open(tmp.name, "wb") as wf:
+            wf.setnchannels(CHANNELS)
+            wf.setsampwidth(2)
+            wf.setframerate(SAMPLE_RATE)
+            wf.writeframes(pcm.tobytes())
+
+        self.wav_path = tmp.name
+        return tmp.name