Clarke: NHS clinical documentation system

.env.template

@@ -0,0 +1,35 @@
+# .env.template — copy to .env and fill values
+
+# === Model Configuration ===
+MEDASR_MODEL_ID=google/medasr
+MEDGEMMA_4B_MODEL_ID=google/medgemma-1.5-4b-it
+MEDGEMMA_27B_MODEL_ID=google/medgemma-27b-text-it
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
+QUANTIZE_4BIT=true
+USE_FLASH_ATTENTION=true
+
+# === FHIR Configuration ===
+FHIR_SERVER_URL=http://localhost:8080/fhir
+USE_MOCK_FHIR=true
+FHIR_TIMEOUT_S=10
+
+# === Application Configuration ===
+APP_HOST=0.0.0.0
+APP_PORT=7860
+LOG_LEVEL=INFO
+MAX_AUDIO_DURATION_S=1800
+PIPELINE_TIMEOUT_S=120
+DOC_GEN_MAX_TOKENS=2048
+DOC_GEN_TEMPERATURE=0.3
+
+# === Fine-tuning (optional, Phase 4) ===
+WANDB_API_KEY=
+WANDB_PROJECT=clarke-finetuning
+LORA_RANK=16
+LORA_ALPHA=32
+LORA_DROPOUT=0.05
+TRAINING_EPOCHS=3
+LEARNING_RATE=2e-4
+BATCH_SIZE=2
+GRAD_ACCUM_STEPS=8
+MAX_SEQ_LENGTH=4096

.gitattributes

@@ -1 +1,2 @@
 *.wav filter=lfs diff=lfs merge=lfs -text
+*.aiff filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -205,3 +205,13 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Clarke runtime artifacts
+logs/
+models/
+*.pt
+*.bin
+*.safetensors
+*.ckpt
+*.wav
+!data/demo/*.wav

Additional Competition Context.md

@@ -0,0 +1,339 @@
+# **Additional Competition Context — MedGemma Impact Challenge**
+
+*Compiled 2026-02-12 from systematic review of Kaggle competition pages, discussions, rules, and HAI-DEF developer documentation.*
+
+### **Key NEW findings not in Clarke spec:**
+
+1. **Submission is a Kaggle Writeup (not a file upload)** — created via the Writeups tab, with a Submit button. One submission per team, can re-submit.  
+2. **3 pages \= \~1,500 words** (host clarification). With images, aim for 1,000-1,200 words.  
+3. **12 named judges** — all Google Research/Health AI staff. Profiles documented.  
+4. **Judged as DEMO, not production** — Yun Liu explicitly said regulatory pathway is NOT the focus. Focus is technical demonstration.  
+5. **Non-commercial training data is OK** — Daniel Golden confirmed. Model weights release is BONUS not required.  
+6. **MedGemma 4B has known instruction-following bugs** — leaks system prompts, generates meta-commentary. Risk for Clarke's EHR pipeline.  
+7. **MedGemma 27B deployment is very hard** — needs \~54GB VRAM, Vertex AI A100 quotas being rejected. Unsloth GGUF quantizations available via Ollama (Q8\_0 \= 31.8GB).  
+8. **MedGemma 1.5 4B adds EHR understanding** — directly relevant to Clarke. Should use 1.5 not 1.0.  
+9. **MedASR runs in-browser via ONNX/WebGPU** — someone built it, could strengthen Edge AI track claim.  
+10. **Only 129 submissions from 5,855 entrants** — competitive field may be smaller than expected.  
+11. **Google explicitly suggests agentic orchestration** in their MedGemma docs — validates Clarke's architecture.
+
+---
+
+## **1\. Submission Requirements**
+
+### **Submission Format: Kaggle Writeup (NOT a file upload)**
+
+* Your submission is a **Kaggle Writeup** attached to the competition's Writeups page — not a PDF or file upload. Create via the "New Writeup" button at: [https://www.kaggle.com/competitions/med-gemma-impact-challenge/writeups](https://www.kaggle.com/competitions/med-gemma-impact-challenge/writeups)  
+* After saving your Writeup, click the **"Submit"** button in the top right corner.  
+* Each team gets **one (1) Writeup submission only**, but it can be un-submitted, edited, and re-submitted unlimited times before the deadline.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Submission Instructions section)
+
+### **3-Page Limit Clarification**
+
+* The "3 pages" translates to **\~1,500 words** single-spaced. If using charts/images/code blocks, aim for **1,000–1,200 words** of text.  
+* **Source:** Fereshteh Mahvar (Competition Host) at [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/671156](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/671156)
+
+### **Required Links in Writeup**
+
+* **Required:** Video (3 min or less)  
+* **Required:** Public code repository  
+* **Bonus:** Public interactive live demo app  
+* **Bonus:** Open-weight Hugging Face model tracing to a HAI-DEF model  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Submission Instructions)
+
+### **Track Selection**
+
+* All submissions automatically compete in the **Main Track**.  
+* You may select **one** special award prize (Agentic Workflow, Novel Task, or Edge AI).  
+* If you select multiple special awards, only one will be considered (randomly selected).  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Choosing a Track)
+
+### **Writeup Template (exact structure required)**
+
+\#\#\# Project name  
+\#\#\# Your team \[Name members, speciality, role\]  
+\#\#\# Problem statement \[Problem domain \+ Impact potential criteria\]  
+\#\#\# Overall solution \[Effective use of HAI-DEF models criterion\]  
+\#\#\# Technical details \[Product feasibility criterion\]
+
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Proposed Writeup template)
+
+### **Private Resources Warning**
+
+* If you attach a **private** Kaggle Resource to your public Writeup, it will be **automatically made public** after the deadline.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview)
+
+### **Submissions Must Be in English**
+
+* Confirmed by María Cruz (Kaggle Staff).  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/667660](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/667660)
+
+---
+
+## **2\. Judging Details**
+
+### **Full Judge Panel (12 judges)**
+
+| Judge | Role |
+| ----- | ----- |
+| Fereshteh Mahvar | Staff Medical Software Engineer & Solutions Architect, Google Health AI |
+| Omar Sanseviero | Developer Experience Lead, Google DeepMind |
+| Glenn Cameron | Sr. PMM, Google |
+| Can "John" Kirmizi | Software Engineer, Google Research |
+| Andrew Sellergren | Software Engineer, Google Research |
+| Dave Steiner | Clinical Research Scientist, Google |
+| Sunny Virmani | Group Product Manager, Google Research |
+| Liron Yatziv | Research Engineer, Google Research |
+| Daniel Golden | Engineering Manager, Google Research |
+| Yun Liu | Research Scientist, Google Research |
+| Rebecca Hemenway | Health AI Strategic Partnerships, Google Research |
+| Fayaz Jamil | Technical Program Manager, Google Research |
+
+**Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Judges section)
+
+### **Evaluation is Through Demonstration Application Lens**
+
+* Judges evaluate through the lens of a **demonstration application, NOT a finished product**.  
+* Regulatory pathway, HIPAA/GDPR compliance, etc. are **not the focus** of evaluation criteria — though you may include them.  
+* Quote from Yun Liu (Competition Host): *"The focus of the evaluation criteria is the technical aspects of the demonstration application. Each evaluation criteria will be judged through the lens of a demonstration application and not a finished product."*  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/668280](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/668280)
+
+### **Execution & Communication is the Highest-Weighted Category (30%)**
+
+* Judges look for a **"cohesive and compelling narrative across all submitted materials"** that articulates how you meet the rest of the criteria.  
+* Assess: clarity/polish/effectiveness of video demo, completeness/readability of writeup, quality of source code (organization, comments, reusability).  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Evaluation Criteria table)
+
+---
+
+## **3\. Rules & Restrictions**
+
+### **Team Size**
+
+* Maximum **5 members** per team.  
+* Team mergers allowed before Team Merger Deadline.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.1)
+
+### **One Submission Per Team**
+
+* For Hackathons, each team is allowed **one (1) Submission**.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.2)
+
+### **Winner License: CC BY 4.0**
+
+* Winning submissions must be licensed under **CC BY 4.0** (code and demos).  
+* For generally commercially available software you used but don't own, you don't need to grant that license.  
+* For input data or pretrained models with incompatible licenses used to generate your winning solution, you **don't need to grant** open source license for that data/model.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.5)
+
+### **Non-Commercial Data is Allowed for Training**
+
+* Using public, research-only / non-commercial external datasets during development is **permitted**.  
+* Participation in a Kaggle challenge is **not considered commercial use**.  
+* Releasing final model weights is a **bonus, not a requirement**.  
+* Daniel Golden (Competition Host) quote: *"You are permitted to use data and other code sources during development that are governed under other, potentially more restrictive licenses."*  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/671596](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/671596)
+
+### **External Data & Tools**
+
+* External data allowed if **publicly available and equally accessible** to all participants at no cost, or meets the "Reasonableness Standard".  
+* Use of HAI-DEF and MedGemma subject to **HAI-DEF Terms of Use**: [https://developers.google.com/health-ai-developer-foundations/terms](https://developers.google.com/health-ai-developer-foundations/terms)  
+* Automated ML tools (AutoML, H2O, etc.) are permitted with appropriate licensing.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.6)
+
+### **HAI-DEF Terms Key Restrictions**
+
+* **"Clinical Use"** (diagnosis/treatment of patients) requires Health Regulatory Authorization — this doesn't apply to a demo/competition context.  
+* HAI-DEF source code licensed under **Apache 2.0**.  
+* Models are free for research and commercial use.  
+* **Source:** [https://developers.google.com/health-ai-developer-foundations/terms](https://developers.google.com/health-ai-developer-foundations/terms)
+
+### **Mandatory HAI-DEF Model Usage**
+
+* Use of **at least one HAI-DEF model** (such as MedGemma) is **mandatory**.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Effective use of HAI-DEF models criterion)
+
+### **Eligibility**
+
+* Must be 18+, registered on Kaggle, not resident of sanctioned countries.  
+* Competition Entities (Google, Kaggle employees) can participate but **cannot win prizes**.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.7, 3.1)
+
+### **Winner's Obligations**
+
+* Deliver final model's software code \+ documentation.  
+* Code must be capable of generating the winning submission.  
+* Must describe resources required to build/run.  
+* For hackathons, deliverables are as described on the competition website (may not be software code).  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.8)
+
+### **No Cloud Credits Provided**
+
+* Multiple competitors asked about GCP credits / Colab compute — no response from organizers confirming any credits.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/667660](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/667660)
+
+---
+
+## **4\. Winning Patterns & Insights from Discussions**
+
+### **Focus on Demonstration, Not Production**
+
+* The organizers repeatedly emphasize this is about **demonstration applications** with impact potential, not production-ready systems. Keep the writeup high-level; use the video to convey concepts.  
+* *"Less is more\! You should take advantage of the video to convey most of the concepts and keep the write-up as high level as possible."*  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Submission Instructions)
+
+### **Storytelling is Explicitly Scored**
+
+* Problem Domain criterion explicitly mentions **"storytelling"** alongside clarity of problem definition.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Evaluation Criteria)
+
+### **Use HAI-DEF Models "to Their Fullest Potential"**
+
+* The criterion asks whether your application uses HAI-DEF models *"to their fullest potential, where other solutions would likely be less effective"*.  
+* Clarke's multi-model approach (MedASR \+ MedGemma 4B \+ MedGemma 27B) is well-aligned with this.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Evaluation Criteria)
+
+### **Agentic Orchestration is Officially Suggested**
+
+* Google's own MedGemma documentation explicitly suggests agentic orchestration: using MedGemma as a tool within an agentic system, coupled with FHIR generators/interpreters, Gemini Live for bidirectional audio, or Gemini 2.5 Pro for function calling.  
+* MedGemma can **"parse private health data locally before sending anonymized requests to centralized models"** — directly supports Clarke's privacy-preserving architecture.  
+* **Source:** [https://developers.google.com/health-ai-developer-foundations/medgemma](https://developers.google.com/health-ai-developer-foundations/medgemma)
+
+### **Competition Scale: Low Submissions So Far**
+
+* 5,855 entrants but only **129 submissions** (134 participants, 129 teams) as of Feb 12 2026\.  
+* This suggests many entrants haven't submitted yet — the field may be smaller than expected.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview](https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview) (Participation stats)
+
+### **MedGemma 1.5 is the Latest Version**
+
+* MedGemma 1.5 4B (google/medgemma-1.5-4b-it) was released in Jan 2026 with improved capabilities:  
+  * High-dimensional medical imaging (CT, MRI, histopathology)  
+  * Longitudinal medical imaging (chest X-ray time series)  
+  * Medical document understanding (structured extraction from lab reports)  
+  * EHR understanding (interpretation of text-based EHR data)  
+  * Improved medical text reasoning accuracy  
+* **Source:** [https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/](https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/)
+
+---
+
+## **5\. Technical Resources**
+
+### **Official Notebooks & Code**
+
+| Resource | URL |
+| ----- | ----- |
+| Quick start (Hugging Face) | [https://github.com/google-health/medgemma/blob/main/notebooks/quick\_start\_with\_hugging\_face.ipynb](https://github.com/google-health/medgemma/blob/main/notebooks/quick_start_with_hugging_face.ipynb) |
+| Quick start (Model Garden) | [https://github.com/google-health/medgemma/blob/main/notebooks/quick\_start\_with\_model\_garden.ipynb](https://github.com/google-health/medgemma/blob/main/notebooks/quick_start_with_model_garden.ipynb) |
+| Fine-tuning with LoRA | [https://github.com/google-health/medgemma/blob/main/notebooks/fine\_tune\_with\_hugging\_face.ipynb](https://github.com/google-health/medgemma/blob/main/notebooks/fine_tune_with_hugging_face.ipynb) |
+| Reinforcement Learning | [https://github.com/Google-Health/medgemma/blob/main/notebooks/reinforcement\_learning\_with\_hugging\_face.ipynb](https://github.com/Google-Health/medgemma/blob/main/notebooks/reinforcement_learning_with_hugging_face.ipynb) |
+| MedGemma GitHub repo | [https://github.com/google-health/medgemma](https://github.com/google-health/medgemma) |
+| HAI-DEF developer forum | [https://discuss.ai.google.dev/c/hai-def/](https://discuss.ai.google.dev/c/hai-def/) |
+
+### **MedASR Resources**
+
+| Resource | URL |
+| ----- | ----- |
+| MedASR model (HuggingFace) | [https://huggingface.co/google/medasr](https://huggingface.co/google/medasr) |
+| MedASR developer docs | [https://developers.google.com/health-ai-developer-foundations/medasr/](https://developers.google.com/health-ai-developer-foundations/medasr/) |
+| MedASR in-browser (ONNX/WebGPU) | [https://medasr.ainergiz.com/](https://medasr.ainergiz.com/) |
+| MedASR in-browser source | [https://github.com/ainergiz/medasr-web](https://github.com/ainergiz/medasr-web) |
+| MedASR MLX (Apple Silicon) | Discussion: [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/672879](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/672879) |
+| MedASR ONNX export script | In ainergiz/medasr-web repo at /scripts/export\_onnx.py |
+
+### **MedGemma 27B GGUF Quantizations (Unsloth)**
+
+* Available at: [https://huggingface.co/unsloth/medgemma-27b-it-GGUF/tree/main](https://huggingface.co/unsloth/medgemma-27b-it-GGUF/tree/main)  
+* Can run locally via Ollama: ollama run hf.co/unsloth/medgemma-27b-it-GGUF:Q8\_0 (31.8 GB)  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/673091](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/673091)
+
+### **HuggingFace Collections**
+
+| Collection | URL |
+| ----- | ----- |
+| MedGemma release | [https://huggingface.co/collections/google/medgemma-release-680aade845f90bec6a3f60c4](https://huggingface.co/collections/google/medgemma-release-680aade845f90bec6a3f60c4) |
+| HAI-DEF collection | [https://huggingface.co/collections/google/health-ai-developer-foundations-hai-def](https://huggingface.co/collections/google/health-ai-developer-foundations-hai-def) |
+| Community fine-tunes | [https://huggingface.co/models?other=or:base\_model:finetune:google/medgemma-4b-it,base\_model:finetune:google/medgemma-4b-pt,base\_model:finetune:google/medgemma-27b-it,base\_model:finetune:google/medgemma-27b-text-it](https://huggingface.co/models?other=or:base_model:finetune:google/medgemma-4b-it,base_model:finetune:google/medgemma-4b-pt,base_model:finetune:google/medgemma-27b-it,base_model:finetune:google/medgemma-27b-text-it) |
+
+### **Key Blog Posts**
+
+| Title | URL |
+| ----- | ----- |
+| MedGemma 1.5 \+ MedASR announcement | [https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/](https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/) |
+| Original MedGemma blog | [https://research.google/blog/medgemma-our-most-capable-open-models-for-health-ai-development/](https://research.google/blog/medgemma-our-most-capable-open-models-for-health-ai-development/) |
+| HAI-DEF launch blog | [https://research.google/blog/helping-everyone-build-ai-for-healthcare-applications-with-open-foundation-models/](https://research.google/blog/helping-everyone-build-ai-for-healthcare-applications-with-open-foundation-models/) |
+| AskCPG concept integration | [https://discuss.ai.google.dev/t/sharing-our-product-integration-with-medgemma-askcpg/94556](https://discuss.ai.google.dev/t/sharing-our-product-integration-with-medgemma-askcpg/94556) |
+
+### **Notable Competition Notebooks (for inspiration)**
+
+| Notebook | Theme |
+| ----- | ----- |
+| MedFlow AI (24 upvotes) | Top-voted notebook |
+| MedGemma Navigator: DICOMweb ↔ FHIR (16 upvotes) | FHIR/DICOM integration — similar to Clarke's EHR focus |
+| MedGemma Medical AI Chatbot \+ 5 Test Scenarios (14 upvotes) | Medical chatbot with test scenarios |
+| MedAssist Edge Offline Medical AI (7 upvotes) | Offline/edge deployment |
+| Spasht AI — Bridging India's "Last Mile" Health Gap (6 upvotes) | Community health focus |
+| RadAssist-MedGemma: AI Radiology Triage Assistant (4 upvotes) | Radiology triage |
+| CRSA — Clinical Reasoning Stability Auditor | Reasoning evaluation |
+
+**Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/code](https://www.kaggle.com/competitions/med-gemma-impact-challenge/code)  
+---
+
+## **6\. Gaps & Risks**
+
+### **MedGemma 4B Instruction Following Issues**
+
+* Multiple competitors report MedGemma 4B (medgemma-1.5-4b-it) **leaking system prompts, generating meta-commentary, and outputting chain-of-thought training artifacts** (critique responses, constraint checklists, special tokens).  
+* One user reports running with Ollama locally works well; the issues may be prompt/framework dependent.  
+* **Risk for Clarke:** If using MedGemma 4B for EHR extraction, we need thorough prompt engineering and output parsing to handle instruction-following failures.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/673091](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/673091)
+
+### **MedGemma 27B Deployment is Extremely Challenging**
+
+* Requires \~54GB VRAM — won't run on Apple M3 Max 64GB (MPS buffer limit), won't fit on 2x L4 GPUs (48GB).  
+* Vertex AI A100 quota requests being **rejected by Google**.  
+* Quantized GGUF versions (Unsloth Q8\_0 \= 31.8GB) can run via Ollama on local hardware.  
+* **Risk for Clarke:** The 24-hour build plan assumes MedGemma 27B for letter generation. If deploying on Kaggle/cloud is blocked by GPU quota, we need a fallback (quantized 27B via Ollama, or enhanced 4B with heavy prompt engineering).  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/673091](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/673091)
+
+### **MedGemma 1.5 Only Available as 4B**
+
+* MedGemma 1.5 is only released as 4B multimodal. The 27B model is still MedGemma 1 (text-only and multimodal).  
+* **Risk for Clarke:** Clarke spec references "MedGemma 27B" — should clarify we're using MedGemma 1 27B, not 1.5.  
+* **Source:** [https://developers.google.com/health-ai-developer-foundations/medgemma](https://developers.google.com/health-ai-developer-foundations/medgemma)
+
+### **No Provided Dataset \= You Must Source Your Own**
+
+* Competition provides **zero data**. All data must be sourced externally.  
+* For Clarke: synthetic NHS consultation data or publicly available clinical note datasets needed. Non-commercial academic datasets are acceptable per organizer clarification.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules](https://www.kaggle.com/competitions/med-gemma-impact-challenge/rules) (Section 2.4)
+
+### **Model Weights Release is Bonus, Not Required**
+
+* Releasing fine-tuned model weights on HuggingFace is listed as a **bonus** submission element, not mandatory.  
+* However, it could significantly strengthen the "Effective use of HAI-DEF models" score.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/671596](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/671596) (Daniel Golden's response)
+
+### **EHR/FHIR Understanding is a New MedGemma 1.5 Capability**
+
+* MedGemma 1.5 4B specifically adds **"EHR understanding for the interpretation of text-based EHR data"** — this directly supports Clarke's EHR navigation component.  
+* Consider using MedGemma 1.5 4B (instead of 1.0 4B) for the EHR extraction pipeline.  
+* **Source:** [https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/](https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/)
+
+### **Official Discord Exists But Not Monitored by Staff**
+
+* Kaggle Discord at [http://discord.gg/kaggle](http://discord.gg/kaggle) — additional discussion channel, but organizers don't monitor it.  
+* **Source:** [https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/667660](https://www.kaggle.com/competitions/med-gemma-impact-challenge/discussion/667660)
+
+---
+
+## **Pages That Could Not Be Accessed**
+
+| URL | Issue |
+| ----- | ----- |
+| Kaggle discussion threads via web\_fetch | JS-rendered, required browser automation |
+| Kaggle Code notebooks (content) | Would require login/browser to read notebook code cells |
+| AskCPG concept app details | [https://discuss.ai.google.dev/t/sharing-our-product-integration-with-medgemma-askcpg/94556](https://discuss.ai.google.dev/t/sharing-our-product-integration-with-medgemma-askcpg/94556) — not fetched |
+| MedGemma model card | [https://developers.google.com/health-ai-developer-foundations/medgemma/model-card](https://developers.google.com/health-ai-developer-foundations/medgemma/model-card) — not fetched |
+| MedASR developer docs | [https://developers.google.com/health-ai-developer-foundations/medasr/](https://developers.google.com/health-ai-developer-foundations/medasr/) — not fetched |
+| HAI-DEF Terms of Use (full) | [https://developers.google.com/health-ai-developer-foundations/terms](https://developers.google.com/health-ai-developer-foundations/terms) — truncated at Section 3 |
+

Clarke_Product_Specification_V2.md

@@ -0,0 +1,610 @@
+# Clarke — Product Specification Document
+
+**Version:** 2.0  
+**Date:** 12 February 2026  
+**Purpose:** Comprehensive specification for PRD generation and AI-agent execution within 24 working hours  
+**Competition:** MedGemma Impact Challenge (Kaggle)  
+**Targets:** Main Track 1st Place ($30,000) + Agentic Workflow Prize ($5,000)
+
+---
+
+## SECTION 1: PRODUCT VISION
+
+### 1.1 Clarke in One Sentence
+
+Clarke is an open-source, privacy-preserving AI system that listens to a clinician's patient consultation, automatically retrieves the relevant patient record context, and generates a complete, structured clinical document — ready to review and sign off — using a pipeline of three purpose-built HAI-DEF medical models (MedASR → MedGemma 4B → MedGemma 27B) running entirely within the hospital network.
+
+### 1.2 The 30-Second Pitch
+
+You talk to your patient. Clarke listens. In the background, it simultaneously pulls the patient's history, medications, recent bloods, and imaging results from the electronic health record. By the time you say goodbye, a draft clinic letter — structured to NHS standards, populated with the right investigation results, and chronologically ordered — is waiting on your screen. You review it, make any edits, and sign off. No dictaphone. No secretary. No 15-minute write-up from memory. No logging into five separate systems. Your letter is done before your next patient walks in. And no patient data ever leaves the building.
+
+### 1.3 The Core Synergy: Why Combining Ambient Documentation with EHR Navigation Creates a Product Greater Than the Sum of Its Parts
+
+The two capabilities are not merely additive — they solve each other's critical weakness.
+
+**Ambient documentation alone** (CliniScribe) captures what was *said* in the consultation but is blind to what already *exists* in the patient record. A clinician discusses a rising HbA1c, but the scribe has no access to the actual lab values, the trend over the past 6 months, or the current medication list. The clinician must still manually look up and insert this information, or the generated letter is incomplete. This is exactly why commercial ambient scribes like Heidi Health and DAX Copilot still require significant post-generation editing — they produce notes from conversation alone, without record context.
+
+**EHR navigation alone** (WardBrief) retrieves and summarises existing patient data but cannot capture what happens *during* the consultation — the new symptoms reported, the examination findings, the shared decision-making, the agreed plan. It produces a pre-consultation briefing, not a post-consultation document.
+
+**Clarke unifies both pipelines through a single integration point:** the conversation transcript (produced by MedASR) is passed to MedGemma 27B *alongside* the structured patient context (retrieved by MedGemma 4B acting as a FHIR agent). This means the document-generation model has access to both what the clinician discussed *and* what the record contains. The result is a clinical letter that:
+
+- References actual lab values discussed ("Your HbA1c has risen from 48 to 55 mmol/mol since June 2025") rather than vague mentions ("blood sugar levels were discussed")
+- Includes the current medication list without the clinician having to dictate it
+- Automatically attaches relevant investigation results referenced during the conversation
+- Cross-checks for consistency — if the clinician mentions "no allergies" but the record shows a penicillin allergy, Clarke flags the discrepancy
+
+This integration transforms Clarke from a transcription tool into a **clinical reasoning assistant** that produces documents no standalone ambient scribe or EHR navigator could match.
+
+**For the Agentic Workflow Prize specifically:** this pipeline — audio capture → medical speech recognition → agentic EHR data retrieval → context-enriched document generation → clinician review — constitutes a five-stage agentic workflow where three HAI-DEF models operate as intelligent agents, each making autonomous decisions about what to process and retrieve. This is precisely the "significant overhaul of a challenging process" the prize description calls for.
+
+---
+
+## SECTION 2: THE PROBLEM
+
+### 2.1 Problem Definition
+
+NHS doctors spend four hours on administrative tasks for every one hour with patients, with clinical documentation — writing letters, discharge summaries, referral notes, and ward round entries — consuming the largest share of that administrative time. This documentation requires clinicians to assimilate information scattered across multiple disconnected IT systems, compose structured clinical narratives, and ensure accuracy, all under severe time pressure. The result is a workforce crisis: doctors burning out, leaving the profession, and — critically — spending less time with the 7.3 million patients currently waiting for NHS treatment.
+
+### 2.2 Quantified Magnitude
+
+**(a) Affected clinicians.** The NHS employs 151,980 FTE hospital and community health service doctors and 38,220 FTE GPs in England alone — approximately 190,200 FTE doctors total [NHS Digital Workforce Statistics, August 2025; General Practice Workforce, December 2025]. Adding Scotland, Wales, and Northern Ireland brings the UK total to approximately 210,000 practising doctors. All of them document clinical encounters.
+
+**(b) Time lost per clinician per day.** The TACT study (Time Allocation in Clinical Training), a national multicentre observational study of 137 NHS resident doctors observed across secondary care centres over 7 months (January–July 2024), found that doctors spent only 17.9% of their time on patient-facing activities while 73.0% was consumed by non-patient-facing tasks [Arab et al., QJM: An International Journal of Medicine, June 2025, doi:10.1093/qjmed/hcaf141]. Our own clinician survey (n=47, January–February 2026) confirmed that documentation specifically accounts for approximately 15 minutes per patient encounter, with clinicians seeing 10–12 patients per half-day clinic — yielding 2.5–3 hours of documentation time per clinic session.
+
+**(c) National aggregate impact.**
+
+- **Time:** If 190,200 FTE NHS doctors in England each save 30 minutes per day (the figure demonstrated by Olson et al., JAMA Network Open 2025), that yields **95,100 clinician-hours freed per day** — equivalent to approximately **11,888 additional full-time doctors** (at 8 hours/day). The NHS currently has 7,248 medical vacancies in secondary care alone [NHS Digital, September 2025]. Clarke's time savings could effectively fill more vacancies than currently exist.
+- **Money:** The mean annual basic pay per FTE doctor is £90,290 [NHS Digital, August 2025]. The 30-minute daily saving per doctor equates to £5,642 per doctor per year in reclaimed clinical time, or **£1.07 billion annually** across 190,200 NHS doctors in England.
+- **Career:** The GMC's 2025 National Training Survey found 61% of trainees at moderate or high risk of burnout [GMC NTS 2025; NHS Employers]. The 2024 NHS Staff Survey reported 42.19% of medical and dental staff experience work-related stress and 30.24% feel burnt out [BMA, Medical Staffing Data Analysis]. The JAMA Network Open study demonstrated that ambient AI scribes reduced burnout from 51.9% to 38.8% (OR 0.26, 95% CI 0.13–0.54, p<0.001) after just 30 days [Olson et al., JAMA Netw Open 2025;8(10):e2534976].
+- **Waiting list:** 7.31 million cases on the NHS waiting list as of November 2025, with only 62% of patients treated within 18 weeks against a 92% constitutional standard [BMA Backlog Data Analysis; King's Fund]. Every hour freed from documentation is an hour available for patient care.
+
+**(d) Patient safety consequences.** The TACT study found that junior trainees (FY1–ST5) spent only 17.8% of time on patient-facing tasks versus 38.4% for senior trainees (ST6–8) — meaning the least experienced doctors have the least patient contact and the most administrative burden [Arab et al., 2025]. The GMC 2025 NTS found 21% of trainees hesitated to escalate patient care concerns [GMC NTS 2025]. Fragmented records directly contribute to safety incidents: our survey respondents described emergency situations where patients were "unconscious, confused, or unable to speak" and "missing one piece of information like an allergy or heart condition could cause serious harm."
+
+### 2.3 Unmet Need — Why Existing Solutions Fall Short
+
+| Competitor | What It Does | Why It Falls Short for NHS Clinicians |
+|---|---|---|
+| **Microsoft DAX Copilot (Nuance)** | Cloud-based ambient scribe integrated with Epic/Oracle | Sends patient audio to US-hosted cloud servers — violates NHS data sovereignty requirements. Requires enterprise EHR integration (Epic). Costs >$200/clinician/month at scale. Generates American-style documentation, not NHS clinical letters. |
+| **Heidi Health** | Cloud-based ambient scribe with NHS GP traction (claims 60% of NHS GPs) | Closed-source, proprietary — NHS trusts cannot audit the model. Cloud-dependent ($99/month per clinician). No EHR record integration — generates notes from conversation only, without access to patient history, lab results, or imaging. Produces documentation that still requires manual enrichment with record data. |
+| **Abridge** | Ambient AI scribe deployed at Yale, UCSF, and other US health systems | US-focused, no NHS deployment. Cloud-only architecture. No FHIR-based record navigation. |
+| **Nabla** | European ambient scribe | Cloud-dependent. Limited NHS integration. No record context retrieval. |
+| **Tortus AI / Accurx Scribe** | UK-based ambient scribes with NHS deployments | Accurx claims 97% clinical accuracy but is a closed proprietary solution with no EHR data retrieval. Tortus operates across 3,500+ GP practices but is cloud-dependent and subscription-based. Neither provides intelligent record navigation. |
+| **Existing EHR systems (Cerner, EMIS, SystmOne)** | Store and display patient records | Present data in silos across separate modules. No synthesis, no summarisation, no document generation from conversation. Clinicians must manually navigate and compile information. |
+
+**The specific unmet need Clarke addresses:** An open-source, fully local, NHS-tailored AI system that combines ambient clinical documentation with intelligent EHR record retrieval — producing context-enriched clinical documents from conversation, without patient data leaving the hospital, at zero per-clinician licensing cost.
+
+No existing product does both. Every commercial ambient scribe generates documents from conversation alone, without EHR context. Every EHR system presents records without document generation. Clarke is the first system to close this loop using purpose-built medical AI models that can be audited, customised, and deployed entirely on-premise.
+
+---
+
+## SECTION 3: HOW CLARKE WORKS — END-TO-END
+
+### 3.1 Complete User Journey
+
+**Pre-consultation (30 seconds):**
+
+1. The clinician opens Clarke in their web browser (accessible on any device connected to the hospital network). They see a clean dashboard showing their clinic list for the day — patient names, appointment times, and brief one-line summaries.
+2. They click on the next patient's name. Clarke's EHR Agent (MedGemma 4B) begins retrieving patient context in the background via FHIR API calls: demographics, problem list, current medications, recent blood results, recent imaging reports, and the last clinic letter.
+3. A "Patient Context" panel populates on the left side of the screen, showing a structured summary: key diagnoses, current medications, recent investigations with trends, and any flags (e.g., allergies, pending results). This takes 5–10 seconds.
+
+**During consultation (10–30 minutes):**
+
+4. The clinician clicks "Start Consultation." Clarke activates the microphone. A small recording indicator appears at the top of the screen.
+5. The clinician has their normal conversation with the patient. They can glance at the Patient Context panel at any time for reference.
+6. MedASR processes the audio stream in real-time, producing a running transcript visible in a "Live Transcript" tab (minimised by default, expandable if the clinician wants to check).
+7. If the clinician mentions specific results ("Your kidney function has gotten a bit worse"), Clarke's EHR Agent can dynamically fetch the relevant lab values and queue them for inclusion in the document.
+
+**Post-consultation (15–60 seconds):**
+
+8. The clinician clicks "End Consultation." The recording stops.
+9. Clarke sends the complete transcript (from MedASR) and the patient context (from the EHR Agent) to MedGemma 27B, which generates a structured clinical document.
+10. Within 10–30 seconds, a draft document appears in the main panel. It is structured as an NHS clinic letter with: date, patient demographics, addressee (GP), reason for consultation, history of presenting complaint, relevant past medical history, examination findings, investigation results (with actual values from the EHR), assessment, and plan.
+11. The clinician reviews the document. They can:
+    - Edit any text directly (inline editing)
+    - Click on any cited investigation result to see the source record
+    - Accept or reject individual sections
+    - Use a "Regenerate" button on any section to get an alternative phrasing
+12. Once satisfied, they click "Sign Off." The document is marked as approved and ready for export.
+13. The document can be exported as: a PDF, a FHIR DocumentReference resource for EHR integration, or copied to clipboard for pasting into the existing EHR system.
+14. Clarke resets. The clinician clicks the next patient. The cycle begins again.
+
+**Ward Round Mode (alternative flow):**
+
+For inpatient settings, Clarke offers a "Ward Round" mode. Instead of recording a single extended consultation, it records the ward round conversation for each patient sequentially. The clinician taps "Next Patient" as they move between beds. For each patient, Clarke generates a ward round entry (not a letter) containing: overnight events, current status, examination findings, investigation results, and today's plan. This mode produces a daily progress note rather than a clinic letter, but uses the same underlying pipeline.
+
+### 3.2 System Architecture — Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        CLARKE SYSTEM                            │
+│                                                                 │
+│  ┌──────────┐    ┌───────────┐    ┌──────────────────────────┐ │
+│  │ Browser  │◄──►│ Gradio 5.x│◄──►│     Orchestrator          │ │
+│  │ (User)   │    │ Frontend  │    │   (Python / FastAPI)       │ │
+│  └──────────┘    └───────────┘    └────────┬─────────┬────────┘ │
+│                                            │         │          │
+│                    ┌───────────────────┐    │         │          │
+│                    │                   │    │         │          │
+│              ┌─────▼─────┐     ┌──────▼────▼──┐     │          │
+│              │  MedASR    │     │  MedGemma     │     │          │
+│              │  (105M)    │     │  1.5 4B       │     │          │
+│              │            │     │  EHR Agent    │     │          │
+│              │ Audio→Text │     │  FHIR→Context │     │          │
+│              └─────┬──────┘     └──────┬────────┘     │          │
+│                    │                   │              │          │
+│                    │    TRANSCRIPT     │   PATIENT    │          │
+│                    │                   │   CONTEXT    │          │
+│                    │                   │              │          │
+│                    └────────┬──────────┘              │          │
+│                             │                        │          │
+│                    ┌────────▼────────┐               │          │
+│                    │   MedGemma 27B  │               │          │
+│                    │   (text-only)   │               │          │
+│                    │                 │               │          │
+│                    │ Transcript +    │               │          │
+│                    │ Context →       │               │          │
+│                    │ Clinical Letter │               │          │
+│                    └────────┬────────┘               │          │
+│                             │                        │          │
+│                    ┌────────▼────────┐               │          │
+│                    │  Draft Document │               │          │
+│                    │  (Structured)   │◄──────────────┘          │
+│                    └─────────────────┘                           │
+│                                                                 │
+│  ┌──────────────┐                                               │
+│  │ FHIR Server  │ (Synthea synthetic data for demo;             │
+│  │ (HAPI FHIR)  │  real hospital FHIR server in production)     │
+│  └──────────────┘                                               │
+│                                                                 │
+│            ALL PROCESSING WITHIN HOSPITAL NETWORK               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Detailed Data Flow:**
+
+**Stage 1 — Audio Capture → Medical Transcript**
+- **Model:** MedASR (`google/medasr` on Hugging Face). 105M parameters. Conformer-based ASR.
+- **Input:** Mono-channel audio stream, 16kHz, int16 waveform. Captured via browser MediaRecorder API, chunked and sent to backend via WebSocket.
+- **Processing:** Audio chunks processed using `transformers` pipeline with `chunk_length_s=20` and `stride_length_s=2` for streaming transcription.
+- **Output:** Full-text transcript of the clinician-patient conversation.
+
+**Stage 2 — Agentic EHR Context Retrieval**
+- **Model:** MedGemma 1.5 4B multimodal, instruction-tuned (`google/medgemma-1.5-4b-it` on Hugging Face). 4B parameters.
+- **Architecture:** Operates as a LangGraph-based agent following Google's EHR Navigator pattern. The agent receives a clinical query (e.g., "Retrieve patient context for consultation"), discovers available FHIR resources, plans which to retrieve, fetches them via FHIR REST API calls, extracts relevant facts, and synthesises a structured context summary.
+- **Input:** Patient identifier + clinical query (initially "Prepare pre-consultation summary"; updated dynamically during consultation if specific results are mentioned in the transcript).
+- **FHIR Resources Queried:** Patient, Condition, MedicationRequest, Observation (labs), DiagnosticReport, AllergyIntolerance, Encounter (recent), DocumentReference (last clinic letter).
+- **Output:** Structured JSON containing: demographics, problem list, current medications, allergies, recent lab results (with values, units, reference ranges, and dates), recent imaging summaries, and key excerpts from the most recent clinic letter.
+
+**Stage 3 — Context-Enriched Document Generation**
+- **Model:** MedGemma 27B text-only, instruction-tuned (`google/medgemma-27b-text-it` on Hugging Face). 27B parameters.
+- **Input:** A structured prompt containing:
+  1. The full conversation transcript (from Stage 1)
+  2. The structured patient context JSON (from Stage 2)
+  3. A document template specifying the target format (NHS clinic letter, discharge summary, ward round note, or referral letter — selected by the clinician)
+  4. Instructions for clinical document conventions (chronological ordering, inclusion of positive and negative findings, reference to specific investigation values)
+- **Output:** A structured clinical document in the specified NHS format, with inline references to the source data (e.g., lab values traced to specific FHIR Observation resources).
+
+**Integration Point:** The orchestrator (Python/FastAPI) coordinates all three stages. The transcript and patient context are combined into a single prompt for MedGemma 27B. This is the critical fusion that no existing product achieves — the document generator sees both the conversation and the record simultaneously.
+
+### 3.3 HAI-DEF Model Justification
+
+**MedASR (105M, `google/medasr`):**
+
+(a) *Why not a general-purpose ASR like Whisper?* MedASR achieves 5.2% WER on chest X-ray dictation compared to 12.5% for Whisper large-v3 — 58% fewer transcription errors. On broad medical dictation, MedASR reaches 5.2% WER versus 28.2% for Whisper — 82% fewer errors [Google Research Blog, January 2026]. Medical terminology errors in transcription directly corrupt downstream document generation.
+
+(b) *Exploited capability:* MedASR was specifically trained on ~5,000 hours of de-identified physician dictations across radiology, internal medicine, and family medicine [Google/MedASR Hugging Face Model Card]. It has a strong vocabulary for drug names, anatomical terms, and clinical phrases that general ASR models consistently misrecognise.
+
+(c) *Beyond default use case:* MedASR was designed for single-speaker medical dictation. Clarke uses it for two-party ambient conversation (clinician + patient), which is significantly harder due to speaker overlap, non-medical language, and background noise. We fine-tune MedASR with LoRA on synthetic multi-speaker clinical conversations to improve ambient performance. [**Assumption:** ambient performance will degrade relative to single-speaker dictation; fine-tuning mitigates but may not fully close the gap.]
+
+**MedGemma 1.5 4B Multimodal (`google/medgemma-1.5-4b-it`):**
+
+(a) *Why not a general-purpose LLM for EHR navigation?* MedGemma 1.5 4B was specifically trained on FHIR-based EHR data and medical documents. Google's own EHR Navigator Agent notebook demonstrates this capability. A general-purpose model would need extensive prompting to understand FHIR resource structures; MedGemma 4B understands them natively. Furthermore, its 4B parameter count enables it to run on modest GPU hardware, making the agentic loop fast enough for real-time context retrieval (critical for the pre-consultation loading step).
+
+(b) *Exploited capability:* FHIR-native EHR understanding, medical document comprehension, and structured data extraction from lab reports — all capabilities added in the 1.5 release [Google Research Blog, January 2026].
+
+(c) *Beyond default use case:* Google's EHR Navigator demonstrates single-query Q&A over FHIR records. Clarke extends this to multi-step agentic retrieval with dynamic re-querying based on the live conversation transcript — if a clinician mentions a result that wasn't in the initial context fetch, the agent retrieves it on-the-fly.
+
+**MedGemma 27B Text-Only (`google/medgemma-27b-text-it`):**
+
+(a) *Why not a general-purpose LLM for document generation?* MedGemma 27B was trained on medical text, medical Q&A pairs, and EHR data. It is optimised for inference-time computation on medical reasoning tasks [MedGemma Technical Report, arXiv:2507.05201]. A general-purpose model of equivalent size would produce plausible-sounding but medically imprecise documents. MedGemma 27B's medical training means it understands which findings are clinically significant, how to order information in a clinical narrative, and when to include negative findings — all essential for a high-quality clinical letter.
+
+(b) *Exploited capability:* Medical text generation with clinical reasoning. The model can infer that if a patient is on metformin and their HbA1c has risen, this is clinically significant and should be prominently documented.
+
+(c) *Beyond default use case:* MedGemma 27B is designed for medical question-answering and reasoning. Clarke uses it for structured document generation to NHS clinical letter standards, which requires not just medical knowledge but understanding of UK healthcare documentation conventions. We fine-tune it on exemplar NHS clinical letters using LoRA to instil these conventions.
+
+---
+
+## SECTION 4: WHAT MAKES CLARKE SUPERIOR
+
+### 4.1 Why HAI-DEF Models Are Superior to General-Purpose Alternatives
+
+**(a) Versus GPT-4 / Gemini:** Three concrete advantages:
+
+1. **Privacy.** GPT-4 and Gemini require cloud API calls, sending patient audio and clinical data to third-party servers. Our clinician survey recorded a respondent stating: "Complete and unbreakable privacy would be non-negotiable. Any data sent to US companies (even if their servers are in the UK) would not be private." HAI-DEF models are open-weight and run locally. Zero patient data leaves the hospital.
+2. **Medical accuracy.** MedASR outperforms Whisper (a general-purpose ASR comparable to what GPT-4's speech mode uses) by 58–82% on medical dictation WER [Google Research Blog, January 2026]. MedGemma 4B's FHIR understanding is native, not prompt-engineered.
+3. **Cost at scale.** A one-time GPU infrastructure investment versus perpetual per-clinician API fees. At 190,200 NHS doctors, even $0.10 per consultation at 20 consultations/day = $380,400/day in API costs. Local HAI-DEF deployment: $0 marginal cost per consultation.
+
+**(b) Versus using each HAI-DEF model in isolation:** The pipeline creates emergent value. MedASR alone produces a transcript. MedGemma 4B alone produces a patient summary. MedGemma 27B alone could generate text from a prompt. But without the pipeline, the transcript has no record context, the summary has no consultation content, and the document generator has neither. The pipeline produces a document that is qualitatively different from what any individual model could generate — it is simultaneously grounded in the conversation and in the patient's medical record.
+
+### 4.2 Why Clarke Could Be Superior to Heidi Health and Other Commercial Ambient Scribes
+
+Heidi Health is the strongest current competitor in the NHS (claims 60% GP adoption, $65M Series B, 340,000 consultations/week) [TechFundingNews, October 2025]. Clarke's advantages are structural, not merely ideological:
+
+1. **Record context integration.** Heidi generates notes from conversation only. Clarke generates documents enriched with actual EHR data — lab values, medication lists, allergy checks. This is not a feature Heidi can easily add because their architecture sends audio to their cloud for processing and has no connection to the hospital's FHIR server. Clarke's local deployment enables direct FHIR server access.
+
+2. **Clinical safety through cross-referencing.** Because Clarke sees both the conversation and the record, it can flag discrepancies (e.g., clinician says "no known allergies" but record shows penicillin allergy). No conversation-only scribe can do this.
+
+3. **Zero marginal cost.** Heidi charges $99/month per clinician. For 190,200 NHS doctors, that is $226 million/year. Clarke is open-source with zero licensing cost. The only cost is GPU hardware, which NHS trusts already possess or can acquire as a one-time capital expenditure.
+
+4. **Auditability.** NHS Information Governance requires that AI systems processing patient data be auditable. Heidi is a closed-source black box. Clarke's code and model weights are fully inspectable.
+
+5. **NHS document format compliance.** Clarke is fine-tuned specifically on NHS clinical letter templates. Heidi generates generic notes that clinicians must reformat.
+
+### 4.3 Special Technology Prize: Agentic Workflow Prize
+
+Clarke targets the **Agentic Workflow Prize** ("the project that most effectively reimagines a complex workflow by deploying HAI-DEF models as intelligent agents or callable tools").
+
+The combined product gives a stronger case than either idea alone because it demonstrates a **multi-model agentic pipeline** where:
+
+- MedASR operates as an autonomous audio processing agent
+- MedGemma 4B operates as an autonomous EHR navigation agent (planning FHIR queries, deciding which resources to retrieve, extracting relevant facts)
+- MedGemma 27B operates as an autonomous document generation agent (deciding structure, selecting relevant information, generating prose)
+- The orchestrator coordinates these three agents into a cohesive workflow
+
+A documentation-only tool (CliniScribe) would demonstrate a two-stage pipeline. A navigation-only tool (WardBrief) would demonstrate a single-agent system. Clarke demonstrates a **three-model, five-stage agentic workflow** that fundamentally reimagines the entire clinical documentation process from audio capture to signed-off letter.
+
+---
+
+
+## SECTION 5: IMPACT QUANTIFICATION
+
+### 5.1 Impact Estimation Table
+
+| # | Metric | Estimate | Calculation Method | Source |
+|---|---|---|---|---|
+| 1 | **Documentation time saved per clinician per day** | 30 minutes | Direct measurement: 263 physicians across 6 US health systems, pre-post ambient AI scribe deployment over 90 days. Measured via EHR time-stamp logs. | Olson et al., JAMA Netw Open 2025;8(10):e2534976 |
+| 2 | **Documentation time saved per patient encounter** | ~15 minutes | Clinician self-report from 47 NHS clinicians. Direct quote: "save me 15 mins for every patient." Consistent with 30 min/day ÷ 2 encounters/hour. | MedGamma Clinician Survey, Jan–Feb 2026 (n=47) |
+| 3 | **After-hours documentation ("pajama time") reduction** | 42% decrease in after-hours EHR work; 66% decline in documentation delays | Retrospective study of 181 primary care physicians and APPs across 14 practices using hybrid ambient AI + virtual scribe. | Moura et al., J Gen Intern Med 2025. DOI:10.1007/s11606-025-09979-5 |
+| 4 | **Total EHR time reduction per note** | 15% less total EHR time; >15% less note-composing time specifically | Matched cohort comparison of 704 primary care clinicians (239 ambient AI users vs. 465 controls) at UChicago Medicine over 90 days. | Pearlman et al., JAMA Netw Open 2025;8(10):e2537000 |
+| 5 | **NHS doctors who benefit (England)** | 190,200 FTE | 151,980 FTE HCHS doctors + 38,220 FTE GPs. | NHS Digital Workforce Statistics Aug 2025 + GP Workforce Dec 2025 |
+| 6 | **Clinician-hours freed daily (England)** | 95,100 hours/day | 190,200 doctors × 0.5 hours saved/day. | Calculated from rows 1 + 5 |
+| 7 | **Equivalent full-time doctors freed** | ~11,888 FTE | 95,100 hours ÷ 8 hours/day. For context: NHS had 7,248 medical vacancies in secondary care alone (Sep 2025). | Calculated; vacancy figure from NHS Digital |
+| 8 | **Annual financial value of reclaimed time** | £1.07 billion | 190,200 × (30 min/day × 250 working days/year) × (£90,290 mean annual salary ÷ 2,000 working hours/year) = 190,200 × £5,642 = £1.07B. | NHS Digital mean doctor salary Aug 2025 + calculation |
+| 9 | **Burnout prevalence reduction (documentation-specific)** | 21.2 percentage-point absolute reduction at 84 days | Pre-post survey of 873 physicians and APPs piloting ambient AI at Mass General Brigham. Survey response rates: 30% at 42 days, 22% at 84 days. | You et al., JAMA Netw Open 2025. DOI:10.1001/jamanetworkopen.2025.28056 |
+| 10 | **Overall burnout reduction (comprehensive measure)** | 13.1 percentage points (51.9% → 38.8%; OR 0.26, 95% CI 0.13–0.54, p<0.001) at 30 days | Pre-post measurement across 263 physicians at 6 health systems. | Olson et al., JAMA Netw Open 2025;8(10):e2534976 |
+| 11 | **Documentation well-being improvement** | 30.7 percentage-point absolute increase at 60 days | Pre-post survey of 557 clinicians (attending physicians, APPs, residents, fellows) at Emory Healthcare. 11% response rate. | You et al., JAMA Netw Open 2025 (Emory arm) |
+| 12 | **Ward round preparation time saved (EHR navigation)** | 25–50 minutes per ward round | Currently 30–60 min to prepare a 10–12 patient ward round (multi-system login, data compilation). Reduced to 5–10 min with automated FHIR context retrieval. | Clinician survey descriptions + clinical workflow estimate |
+| 13 | **Patient safety: missing clinical information** | 15% of outpatient consultations have missing key information; of those, 32% experience care delays, 20% have documented risk of harm | Prospective study across 3 UK teaching hospitals. Extrapolation: ~10M outpatients/year seen without key info nationally, ~2M at risk of harm. | Burnett et al., BMC Health Serv Res 2011;11:114 |
+| 14 | **Patient safety: clinical negligence cost** | £4.6 billion annual cost of harm (2024/25); £60.3 billion total provision for future liabilities | NHS Resolution annual report. 14,428 new clinical negligence claims received in 2024/25. Documentation failures are a contributory factor in many claims. | NHS Resolution Annual Report 2024/25 |
+| 15 | **Commercial licensing cost avoided** | £226 million/year | 190,200 doctors × $99/month (Heidi Health pricing) × 12 months × 0.79 GBP/USD. Clarke's open-source model: £0 licensing. Hardware cost: £5K–£15K per trust (one-time). | Heidi Health pricing + calculation |
+
+### 5.2 Honest Caveats
+
+**1. The 30-minute daily saving comes from US ambulatory care, not NHS settings.** The Olson et al. and Pearlman et al. studies measured US clinicians generating SOAP notes in 15–20 minute primary care visits. NHS workflows differ structurally: GP consultations are typically 10 minutes, hospital clinics vary by specialty, and the documentation output is an NHS-format clinical letter (not a SOAP note). The actual NHS saving could be higher (because NHS clinicians still use dictaphones and manual secretary workflows, which are slower than the US EHR-based systems that ambient AI was compared against) or lower (because shorter consultations produce less source material for the AI). **Validation required:** A prospective time-motion study within a UK NHS pilot comparing Clarke to current documentation methods.
+
+**2. MedASR has not been validated on NHS-accented English at scale.** The NHS workforce includes doctors from over 100 countries. MedASR was trained on ~5,000 hours of US-accented medical dictation. While its Conformer architecture handles accent variation better than RNN-based models, and its fine-tuning notebook enables LoRA adaptation to new accents, we have not empirically tested WER on South Asian, Nigerian, Middle Eastern, or Scottish-accented English — the dominant NHS demographic groups. **Assumption:** LoRA fine-tuning on 100–500 hours of NHS-accented audio will bring WER to within 2 percentage points of the US baseline. This assumption has not been validated.
+
+**3. FHIR API availability varies across NHS trusts.** NHS England's Interoperability Standards mandate FHIR exposure, but adoption is uneven. Some trusts (especially those on EMIS or SystmOne) have robust FHIR endpoints; others (especially legacy Cerner/Oracle Health sites) have limited FHIR R4 support. Clarke degrades gracefully — it operates in "documentation-only" mode without FHIR — but the full value proposition requires FHIR access. **Validation required:** Survey of FHIR readiness across target pilot trusts before deployment.
+
+**4. Burnout reduction figures may not transfer to UK clinicians.** The You et al. study (Mass General Brigham/Emory) involved self-selected pilot users with modest response rates (22–30% at MGB; 11% at Emory), likely overrepresenting enthusiastic adopters. The Olson et al. study had stronger methodology but was still US-based. NHS burnout drivers include non-documentation factors (understaffing, pay disputes, waiting list pressure) that ambient AI cannot address. **Assumption:** Clarke will reduce documentation-related burnout but will not solve systemic NHS workforce issues.
+
+**5. AI-generated clinical documents will contain errors.** MedGemma 27B may hallucinate clinical findings, misattribute lab values, or generate imprecise medical terminology. The FHIR agent may fail to retrieve relevant records or retrieve irrelevant ones. MedASR will produce transcription errors, especially in noisy clinical environments. Clinician review and sign-off is mandatory for every document — Clarke is an authoring aid, not an autonomous documentation system. Google explicitly states HAI-DEF model outputs require independent professional verification.
+
+**6. The financial impact estimate (£1.07B) assumes the reclaimed time is used productively.** In reality, some freed time will be absorbed by other administrative tasks, meetings, or systemic inefficiencies. The per-doctor financial value is calculated at the average salary rate; the true value depends on whether freed time translates to additional patient encounters or clinical activity.
+
+---
+
+## SECTION 6: TECHNICAL FEASIBILITY & 3-DAY BUILD PLAN
+
+### 6.1 Hour-by-Hour Build Plan (24 Working Hours)
+
+**DAY 1 — FRIDAY 13 FEBRUARY (Hours 1–8): Foundation + Core Model Pipelines**
+
+| Hour | Task | Tools / Libraries | Deliverable | "Done" Criterion |
+|---|---|---|---|---|
+| 1 | **Environment setup.** Provision Hugging Face Space with A100 40GB GPU. Install Python 3.11, PyTorch 2.4.x, transformers, FastAPI, Gradio. Clone starter repo. | HF Spaces (Docker `nvidia/cuda:12.4.1-runtime-ubuntu22.04`), `pip`, `git` | Running HF Space with GPU confirmed via `torch.cuda.is_available()` | Space boots, GPU confirmed, all core packages import without error |
+| 2 | **Synthetic FHIR data generation.** Generate 50 UK-style synthetic patients using Synthea. Load into HAPI FHIR server (Docker container within Space). Configure patient names, NHS numbers, UK drug formulary, mmol/L units. | Synthea v3.3.0 (Java CLI), HAPI FHIR v7.4 (Docker), `requests` for REST verification | 50 patient records accessible via `GET /fhir/Patient` | `curl http://localhost:8080/fhir/Patient?_count=50` returns 50 patients with UK-formatted data |
+| 3 | **MedASR integration (Part 1).** Load `google/medasr` via `transformers` AutoModelForSpeechSeq2Seq pipeline. Build audio ingestion: browser MediaRecorder API → WebSocket → server-side WAV conversion (16kHz, mono, int16). | `transformers` 4.47.x, `librosa` 0.10.x, `pydub` 0.25.x, `ffmpeg` 7.x, `websockets` 12.x | Audio capture → WAV file on server | Record 30-second audio clip in browser → receive valid 16kHz WAV on server |
+| 4 | **MedASR integration (Part 2).** Implement chunked transcription: `chunk_length_s=20`, `stride_length_s=2`, `return_timestamps=True`. Build real-time transcript WebSocket return to frontend. Test with sample medical dictation audio. | `transformers` pipeline, `torch`, custom WebSocket handler | Working audio → text pipeline with streaming output | Transcribe 5-minute medical dictation WAV with visible real-time text in browser console; visual inspection confirms <10% WER |
+| 5 | **MedGemma 4B EHR Agent (Part 1).** Load `google/medgemma-1.5-4b-it` in 4-bit quantised mode. Implement LangGraph ReAct agent following Google's EHR Navigator pattern. Define FHIR tools: `search_patients`, `get_conditions`, `get_medications`, `get_observations`, `get_allergies`, `get_diagnostic_reports`. | `transformers`, `bitsandbytes` 0.44.x, `langgraph` 0.2.x, `httpx` for FHIR REST calls | Agent loads, tools callable, returns raw FHIR resources | Agent called with patient ID → returns raw Condition, MedicationRequest, Observation resources as JSON |
+| 6 | **MedGemma 4B EHR Agent (Part 2).** Add context synthesis: agent extracts and structures facts from raw FHIR resources into a standardised JSON schema (demographics, problem_list, medications, allergies, recent_labs, recent_imaging, last_letter_excerpt). Add flags (rising trends, critical values, allergy alerts). | Custom JSON schema, `langgraph` state management | Structured patient context JSON for any synthetic patient | Agent returns well-formed JSON for 5 test patients; manual inspection confirms accuracy against FHIR data |
+| 7 | **Orchestrator: connect MedASR + EHR Agent.** Build FastAPI orchestrator with endpoints: `POST /start-consultation` (activates audio capture + triggers EHR agent), `POST /end-consultation` (stops audio, sends transcript + context to document generation placeholder), `GET /patient-context/{id}` (returns pre-fetched context). | `FastAPI` 0.109.x, `uvicorn` 0.27.x, Python `asyncio` | Working orchestrator connecting both pipelines | Call `/start-consultation` with patient ID → EHR context loads while audio captures → call `/end-consultation` → receive combined prompt containing transcript + context |
+| 8 | **Integration test + prompt engineering.** Design the document-generation prompt template: system message (NHS letter conventions), user message (transcript + context JSON + document type). Test with a mock transcript and real FHIR context, passing to MedGemma 27B placeholder (print output). Build 3 prompt variants: clinic letter, discharge summary, ward round note. | Custom Jinja2 templates, `jinja2` 3.1.x | 3 tested prompt templates producing correctly formatted combined prompts | Visual inspection of 3 generated prompts confirms correct structure: system instructions → transcript → FHIR context → format specification |
+
+**DAY 2 — SATURDAY 14 FEBRUARY (Hours 9–16): Document Generation + UI + Fine-tuning**
+
+| Hour | Task | Tools / Libraries | Deliverable | "Done" Criterion |
+|---|---|---|---|---|
+| 9 | **MedGemma 27B loading + baseline generation.** Load `google/medgemma-27b-text-it` in 4-bit quantisation via bitsandbytes (NF4, double quantisation, `compute_dtype=bfloat16`). Generate 5 baseline clinic letters from the 3 prompt templates using 5 synthetic patients. | `transformers`, `bitsandbytes` 0.44.x, `accelerate` 1.2.x | MedGemma 27B loaded, generates text | 5 generated letters saved as baseline for comparison. Model generates coherent medical text (even if format is not yet NHS-standard) |
+| 10 | **Synthetic training data generation.** Generate 250 training triplets (transcript, FHIR context JSON, reference NHS clinic letter) using Claude API as a data generator. Each triplet based on a unique Synthea patient scenario. Apply NHS letter template conventions. Manually review 20 for quality. | `anthropic` SDK, Synthea data, custom generation scripts | 250 validated training triplets + 50 held-out test triplets in JSONL format | Training file (`train.jsonl`) and test file (`test.jsonl`) pass schema validation; 20 manually reviewed samples are clinically plausible and correctly formatted |
+| 11 | **LoRA fine-tuning MedGemma 27B.** Fine-tune using QLoRA: base model 4-bit NF4, LoRA adapters on `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`. Hyperparameters: rank=16, alpha=32, dropout=0.05, learning_rate=2e-4, warmup_ratio=0.03, lr_scheduler=cosine, max_seq_length=4096, per_device_batch_size=2, gradient_accumulation_steps=8, epochs=3, optimizer=paged_adamw_8bit. | `peft` 0.13.x, `trl` 0.12.x (SFTTrainer), `bitsandbytes`, `datasets`, `wandb` for logging | Fine-tuned LoRA adapter saved to disk + training loss curve | Training completes without OOM. Final training loss < initial loss. Adapter file size < 500MB. |
+| 12 | **Post-training evaluation.** Generate 50 test letters using fine-tuned model. Compute BLEU and ROUGE-L against held-out reference letters. Compare to 5 baseline letters from hour 9. Manual review of 10 generated letters for: (a) NHS format compliance, (b) clinical accuracy, (c) correct use of FHIR-sourced values, (d) appropriate positive and negative findings. | `evaluate` (HuggingFace), `rouge_score`, `sacrebleu`, manual review | Evaluation report: BLEU, ROUGE-L, qualitative assessment | Fine-tuned BLEU > baseline BLEU. Manual review confirms improved NHS format compliance. Report saved as `evaluation_report.md` |
+| 13 | **Gradio UI (Part 1): core layout.** Build main interface: left panel (patient context), centre panel (document editor), top bar (recording controls + status). Implement: patient list dropdown, "Start Consultation" / "End Consultation" buttons, recording indicator, live transcript expandable section. | `gradio` 5.x, custom CSS (NHS Design System colour palette: `#003087` primary, `#005EB8` secondary, `#FFFFFF` background), `gradio.themes` | Functional UI layout with all panels and controls | UI renders in browser. All buttons are clickable. Panels are correctly positioned and responsive at 1280×720 and 1920×1080 |
+| 14 | **Gradio UI (Part 2): data binding.** Connect UI to backend: clicking a patient triggers EHR agent → context panel populates. "Start Consultation" activates audio capture via JavaScript interop. "End Consultation" triggers document generation → draft letter appears in centre panel with inline editing. "Sign Off" button marks document as final. Export buttons (PDF, clipboard, FHIR DocumentReference). | `gradio` event handlers, `gr.State`, JavaScript interop for MediaRecorder | Fully interactive UI connected to backend | Complete end-to-end demo: select patient → see context → start recording → stop → draft letter appears → edit → sign off. All stages functional |
+| 15 | **Integration testing (5 full scenarios).** Test 5 complete consultation scenarios end-to-end. Use pre-recorded synthetic audio clips (generated via TTS or self-recorded). Verify: correct transcription, accurate FHIR context retrieval, clinically appropriate generated letters, working inline editing, successful sign-off and export. | Pre-recorded WAV files, `pytest` for automated checks, manual verification | 5 passing end-to-end demo scenarios | All 5 scenarios complete without crash or error. Generated letters are clinically coherent for each patient |
+| 16 | **Bug fixing + error handling.** Address all issues found in hour 15. Add: loading spinners, error messages for failed FHIR queries, timeout handling for model inference, graceful degradation if MedASR produces empty transcript, fallback if MedGemma 27B OOMs (reduce context length, retry). | Standard Python error handling, Gradio UI feedback components | Robust error-handled application | Re-run all 5 scenarios. Intentionally trigger 3 error conditions (empty audio, FHIR timeout, long transcript). All handled gracefully with user-visible feedback |
+
+**DAY 3 — SUNDAY 15 FEBRUARY (Hours 17–24): Evaluation, Polish, Deployment**
+
+| Hour | Task | Tools / Libraries | Deliverable | "Done" Criterion |
+|---|---|---|---|---|
+| 17 | **MedASR evaluation.** Measure WER on: (a) 20 synthetic medical dictation clips using `jiwer`, (b) 10 ambient conversation clips. Compare to Whisper large-v3 on same data. Document results. | `jiwer` 3.0.x, `openai-whisper` (for baseline comparison), custom test harness | WER comparison table: MedASR vs Whisper, dictation vs ambient | WER computed for all 30 clips. Results documented in `evaluation_report.md` |
+| 18 | **EHR Agent evaluation.** Test FHIR retrieval accuracy on 20 synthetic patients against manually annotated "gold standard" context summaries. Measure: fact recall (% of relevant facts extracted), precision (% of extracted facts that are correct), hallucination rate (% of fabricated facts). | Custom evaluation script, 20 annotated gold standards | Agent accuracy report | Fact recall >85%, precision >90%, hallucination rate <10%. Results appended to `evaluation_report.md` |
+| 19 | **Document generation evaluation + Ward Round mode.** Compute aggregate BLEU/ROUGE-L on full 50-sample test set. Implement Ward Round mode UI (sequential patient recording, progress note template instead of clinic letter). Test with 2 ward round scenarios. | `evaluate`, custom scripts, Gradio tab component | Ward Round mode functional + aggregate evaluation metrics | Ward Round tab generates progress notes. All metrics documented |
+| 20 | **UI polish.** Apply NHS Design System aesthetics: colour palette, typography (Frutiger/Arial), spacing, accessibility (ARIA labels, contrast ratios ≥4.5:1). Add Clarke logo/branding. Responsive design check at 3 viewport sizes. Loading state animations. | CSS custom properties, Gradio theming API, SVG logo | Production-quality visual design | UI screenshots pass visual QA at 1280×720, 1920×1080, and 768×1024 (tablet). Lighthouse accessibility score ≥90 |
+| 21 | **Pre-recorded demo preparation.** Record 3 polished demo audio clips (Mrs Thompson T2DM, Mr Okafor chest pain, Ms Patel asthma review). Each clip: 2–4 minutes, clear audio, realistic clinical dialogue. Save as 16kHz WAV. Verify MedASR transcribes accurately. | Audio recording (self/TTS), `ffmpeg` for format conversion | 3 demo-ready audio clips with verified transcripts | Each clip transcribes with <8% WER. Saved in `demo_data/` directory |
+| 22 | **Hugging Face deployment.** Push application to public HF Space. Upload LoRA adapters to HF Hub as a separate model repository (tracing to `google/medgemma-27b-text-it`). Verify public access: anyone can visit the URL and interact. Test from a different browser/device. | HF Spaces CLI, `huggingface_hub` SDK, `git-lfs` | Live public demo URL + public LoRA adapter repo | External browser (incognito) can access demo, select a patient, play pre-recorded audio, and receive a generated letter |
+| 23 | **Repository documentation.** Write comprehensive README.md: project description, architecture diagram, installation instructions, usage guide, model card, evaluation results, licence (Apache 2.0 for code, HAI-DEF terms for models). Annotate all source code files with docstrings and inline comments. | Markdown, standard Python docstrings | Documented public GitHub repository | README contains: architecture diagram, quickstart guide, evaluation table, licence info. All `.py` files have module-level docstrings |
+| 24 | **Final verification + submission artefacts.** End-to-end smoke test of live demo. Verify: GitHub repo is public, HF Space is live, HF model repo with LoRA adapter is public. Create `submission_checklist.md` confirming all competition requirements met. | Manual testing, checklist | All 3 submission artefacts publicly accessible | GitHub repo public ✓, HF Space live ✓, HF model repo public ✓. Demo runs without errors from external device |
+
+### 6.2 Complete Technology Stack
+
+| Layer | Component | Specific Technology | Version / Detail |
+|---|---|---|---|
+| **Infrastructure** | GPU compute | Hugging Face Spaces | A100 40GB GPU (ZeroGPU or dedicated; fallback: A10G 24GB) |
+| | Container base | Docker | `nvidia/cuda:12.4.1-runtime-ubuntu22.04` |
+| | Runtime | Python | 3.11.x |
+| **Backend** | Web framework | FastAPI | 0.109.x, served via `uvicorn` 0.27.x |
+| | Async | Python asyncio | Built-in, for concurrent MedASR + EHR Agent execution |
+| | WebSocket | `websockets` | 12.x, for real-time audio streaming and transcript return |
+| **Frontend** | UI framework | Gradio | 5.x (latest), served within HF Space |
+| | Audio capture | Browser MediaRecorder API | WebM/Opus codec → server-side conversion to 16kHz WAV |
+| | Styling | Custom CSS | NHS Design System colour palette + Gradio theming API |
+| **Audio processing** | Format conversion | `ffmpeg` | 7.x, for WebM→WAV transcoding |
+| | Audio manipulation | `pydub` | 0.25.x, for resampling and channel conversion |
+| | Audio analysis | `librosa` | 0.10.x, for waveform loading and preprocessing |
+| **ASR model** | MedASR | `google/medasr` | 105M params, Conformer-based, via `transformers` AutoModelForSpeechSeq2Seq |
+| **EHR Agent model** | MedGemma 1.5 4B IT | `google/medgemma-1.5-4b-it` | 4B params, 4-bit quantised via `bitsandbytes`, agent via `langgraph` 0.2.x |
+| **Document generation model** | MedGemma 27B Text IT | `google/medgemma-27b-text-it` | 27B params, 4-bit NF4 quantised via `bitsandbytes` 0.44.x, double quantisation, `compute_dtype=bfloat16` |
+| **ML framework** | Core | PyTorch | 2.4.x with CUDA 12.4 |
+| | Model loading | `transformers` | 4.47.x (HuggingFace) |
+| | Quantisation | `bitsandbytes` | 0.44.x (NF4 quantisation) |
+| | Acceleration | `accelerate` | 1.2.x (device mapping) |
+| **Fine-tuning** | LoRA framework | `peft` | 0.13.x (Parameter-Efficient Fine-Tuning) |
+| | Training | `trl` (SFTTrainer) | 0.12.x |
+| | Dataset loading | `datasets` | 3.2.x (HuggingFace) |
+| | Experiment tracking | `wandb` | 0.18.x (Weights & Biases) |
+| **FHIR** | Server | HAPI FHIR | v7.4, Docker container, FHIR R4 |
+| | Client | `httpx` | 0.27.x (async HTTP for FHIR REST API calls) |
+| | Data generation | Synthea | v3.3.0, configured with UK module (names, NHS numbers, mmol/L units, BNF drugs) |
+| **Prompt engineering** | Template engine | `jinja2` | 3.1.x, for structured prompt assembly |
+| **Evaluation** | WER | `jiwer` | 3.0.x |
+| | Text similarity | `rouge_score`, `sacrebleu` | Latest stable |
+| | ASR baseline | `openai-whisper` | large-v3 (for comparison only) |
+| **Version control** | Repository | GitHub | Public repository, Apache 2.0 licence |
+| **Model hosting** | LoRA adapter | Hugging Face Hub | Public model repo, tracing to `google/medgemma-27b-text-it` |
+| **Document export** | PDF generation | `reportlab` | 4.2.x, for clinic letter PDF export |
+
+### 6.3 Fine-Tuning Strategy
+
+**Model 1: MedGemma 27B Text-Only — NHS Clinical Letter Generation (Primary fine-tuning target)**
+
+- **Objective:** Adapt MedGemma 27B from general medical Q&A to structured NHS clinical document generation from (transcript, FHIR context) input pairs.
+
+- **Data generation:**
+  1. Select 50 diverse Synthea patients spanning: diabetes, COPD, heart failure, CKD, hypertension, cancer follow-up, mental health, orthopaedic, paediatric, obstetric scenarios.
+  2. For each patient, generate 5 training triplets using Claude 3.5 Sonnet API (total: 250 training + 50 held-out test):
+     - **Input 1:** Simulated clinician-patient conversation transcript (~500–1,500 words, naturalistic dialogue including interruptions, repetition, non-medical small talk)
+     - **Input 2:** FHIR context JSON (extracted from Synthea patient data: demographics, conditions, medications, labs, allergies)
+     - **Output:** Reference NHS-format clinic letter following Royal College of Physicians guidelines: date, addressee (GP), patient demographics, reason for consultation, history of presenting complaint, relevant PMH, examination findings, investigation results (with actual values from FHIR context), assessment, plan, follow-up.
+  3. Manually review 40 triplets (20 training, 20 test) for clinical accuracy, correct FHIR value usage, and NHS format compliance. Revise and re-generate any with errors.
+  
+- **Dataset format:** JSONL, one example per line. Each line: `{"messages": [{"role": "system", "content": "<NHS_LETTER_INSTRUCTIONS>"}, {"role": "user", "content": "<TRANSCRIPT>\n\n<FHIR_CONTEXT>"}, {"role": "assistant", "content": "<REFERENCE_LETTER>"}]}`
+
+- **Method:** QLoRA (Quantised Low-Rank Adaptation)
+  - **Base model:** `google/medgemma-27b-text-it`, loaded in 4-bit NF4 quantisation with double quantisation
+  - **LoRA targets:** `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` (all attention + MLP projections)
+  - **LoRA rank:** 16
+  - **LoRA alpha:** 32 (scaling factor = alpha/rank = 2.0)
+  - **LoRA dropout:** 0.05
+  - **Optimizer:** paged_adamw_8bit
+  - **Learning rate:** 2e-4
+  - **LR scheduler:** cosine with warmup
+  - **Warmup ratio:** 0.03 (≈2 warmup steps for 250 examples × 3 epochs / batch)
+  - **Per-device batch size:** 2
+  - **Gradient accumulation steps:** 8 (effective batch size: 16)
+  - **Max sequence length:** 4,096 tokens
+  - **Epochs:** 3
+  - **Mixed precision:** bf16
+
+- **Hardware:** Single A100 40GB GPU (same as inference; LoRA adapters fit in remaining VRAM after 4-bit base model).
+
+- **Duration estimate:** ~2.5 hours for 250 examples × 3 epochs at batch size 2 with gradient accumulation of 8, max_seq_length 4096 on A100 40GB. Based on comparable LoRA fine-tuning benchmarks for 27B models.
+
+- **Output:** LoRA adapter checkpoint (~200–500MB), uploaded to Hugging Face Hub as a public model tracing to `google/medgemma-27b-text-it`.
+
+**Model 2: MedASR — NHS-Accented Medical Speech (Stretch goal, hours 19–20 if evaluation results indicate need)**
+
+- **Rationale:** Only pursued if hour-17 evaluation shows MedASR WER on synthetic NHS-accented audio exceeds 10%. If base MedASR WER is acceptable (<10%), document this as a production requirement and proceed with base model.
+- **Data:** 100–500 labelled medical utterances with UK/international accents. For the demo, these can be self-recorded or sourced from open medical speech datasets.
+- **Method:** LoRA fine-tuning following Google's published MedASR fine-tuning notebook. LoRA rank 8, learning rate 1e-4, 5 epochs.
+- **Duration:** ~1 hour on A100.
+- **Fallback (if not pursued):** Document base MedASR performance on NHS-accented audio in the evaluation report. Note this as a production fine-tuning requirement.
+
+### 6.4 Model Performance Evaluation Plan
+
+| Model | Metric | Test Set | Baseline | Target | Evaluation Method |
+|---|---|---|---|---|---|
+| **MedASR** | Word Error Rate (WER) | 20 medical dictation clips (synthetic, clear audio, US-accent) + 10 ambient conversation clips (synthetic, multi-speaker, UK-accent) | Whisper large-v3 WER on identical audio | MedASR WER < Whisper WER on dictation (expect ≥58% relative improvement per published benchmarks); MedASR WER < 10% absolute on ambient clips | `jiwer` library; manual ground-truth transcripts for each clip |
+| **MedGemma 4B (EHR Agent)** | Fact recall, precision, hallucination rate | 20 synthetic patient records with manually annotated gold-standard context summaries (each containing 15–25 clinically relevant facts) | Naive FHIR dump (return all resources without summarisation or filtering) | Fact recall >85%, precision >90%, hallucination rate <10% | Custom script comparing agent JSON output to gold-standard annotations; 2 reviewers for 10 disagreement cases |
+| **MedGemma 27B (Document Gen, base)** | BLEU, ROUGE-L | 50 held-out (transcript, context, letter) triplets | N/A (this is the baseline) | Establish baseline scores | `sacrebleu`, `rouge_score` |
+| **MedGemma 27B (Document Gen, fine-tuned)** | BLEU, ROUGE-L, clinical accuracy | Same 50 held-out triplets | Base MedGemma 27B scores (from row above) | BLEU improvement ≥5 points; ROUGE-L improvement ≥3 points; manual review confirms improved NHS format compliance in ≥8/10 sampled letters | Automated metrics + manual clinical review of 10 randomly sampled letters by team clinician |
+| **End-to-end pipeline** | Latency (time from "End Consultation" to draft letter display) | 5 full demo scenarios | Manual documentation time (~15 min per clinician survey) | <60 seconds from click to rendered letter | Stopwatch measurement across 5 trials; mean and max recorded |
+| **End-to-end pipeline** | Clinical coherence (manual) | 5 generated letters from demo scenarios | N/A (qualitative) | All 5 letters are clinically coherent, factually consistent with FHIR data, and follow NHS letter structure | Manual review by team clinician using a 5-point rubric: format compliance, clinical accuracy, FHIR value correctness, appropriate plan, readability |
+
+---
+
+## SECTION 7: DEPLOYMENT & DEMO SPECIFICATION
+
+### 7.1 Live Demo Scenario
+
+The demo shows a complete consultation with a synthetic NHS patient, designed to demonstrate every stage of Clarke's agentic pipeline in under 3 minutes. A judge watching the video will see exactly this:
+
+**Screen 1 — Dashboard (0:00–0:15)**
+
+Clarke opens in a web browser showing a mock clinic list for "Dr. Sarah Chen, Diabetes & Endocrinology." Five patients are listed with appointment times and one-line summaries. The first patient is highlighted:
+
+> **Mrs. Margaret Thompson** | 67F | 14:00 | Follow-up — Type 2 Diabetes, rising HbA1c
+
+The clinician (or narrator) clicks on Mrs. Thompson's name.
+
+**Screen 2 — Patient Context Loading (0:15–0:25)**
+
+A brief loading animation plays (3–5 seconds) as Clarke's EHR Agent (MedGemma 4B) queries the FHIR server. The Patient Context panel on the left populates with structured data:
+
+- **Diagnoses:** Type 2 Diabetes Mellitus (2019), Hypertension (2017), CKD Stage 3a (2023)
+- **Medications:** Metformin 1g BD, Ramipril 5mg OD, Atorvastatin 20mg OD
+- **Allergies:** ⚠ Penicillin (anaphylaxis)
+- **Recent Labs:** HbA1c **55** mmol/mol ↑ (was 48 in Jun 2025) · eGFR **52** mL/min ↓ (was 58) · Creatinine **98** μmol/L
+- **Flag:** "⚠ HbA1c rising trend over 6 months — consider treatment escalation"
+
+**Screen 3 — Live Consultation (0:25–1:30)**
+
+The clinician clicks **"Start Consultation."** A red recording indicator appears. A pre-recorded synthetic audio clip plays (~60 seconds, ~250 words):
+
+> Doctor: "Hello Mrs. Thompson, good to see you again. How have you been since we last met?"
+> Patient: "Not too bad doctor, but I've been a bit more tired lately and I'm worried about my sugar levels..."
+> [Conversation covers: fatigue symptoms, dietary adherence, discussion of HbA1c rising from 48 to 55, explanation that metformin alone isn't enough, shared decision to start gliclazide, discussion of hypoglycaemia risk, plan for repeat HbA1c in 3 months]
+
+The Live Transcript panel shows MedASR's real-time text appearing as the audio plays, demonstrating the streaming transcription.
+
+**Screen 4 — Document Generation (1:30–1:50)**
+
+The clinician clicks **"End Consultation."** The recording stops. A progress indicator appears: "Generating clinical letter..." (15–20 seconds). During this time, a subtle animation shows the three pipeline stages: "Transcribing... → Retrieving context... → Drafting letter..."
+
+**Screen 5 — Draft Clinic Letter (1:50–2:30)**
+
+A structured NHS clinic letter appears in the centre panel:
+
+> **[NHS Trust Header]**
+> **Date:** 13 February 2026
+> **NHS Number:** 943 476 5829
+>
+> Dr. R. Patel
+> Riverside Medical Centre
+> 45 High Street, London SE1 2AB
+>
+> **Re: Mrs. Margaret Thompson, DOB 14/03/1958**
+>
+> Dear Dr. Patel,
+>
+> Thank you for asking me to review Mrs. Thompson in the Diabetes clinic today.
+>
+> **History of presenting complaint:** Mrs. Thompson reports increasing fatigue over the past 2–3 months. She has been adherent to dietary advice but has found it difficult to reduce her carbohydrate intake further. She denies polyuria, polydipsia, or weight loss.
+>
+> **Investigation results:** Her HbA1c has risen from **48 mmol/mol** (June 2025) to **55 mmol/mol** (January 2026), indicating worsening glycaemic control despite metformin monotherapy. Her renal function shows eGFR **52 mL/min** (previously 58), consistent with stable CKD Stage 3a. Creatinine is **98 μmol/L**.
+>
+> **Assessment and plan:** Given the rising HbA1c on maximum-dose metformin, I have discussed treatment escalation with Mrs. Thompson and we have agreed to commence **gliclazide 40mg once daily**. I have counselled her regarding the risk of hypoglycaemia and provided written patient information. Please arrange a repeat HbA1c in **3 months** and review her renal function at that time.
+>
+> **Current medications:** Metformin 1g BD, Gliclazide 40mg OD (NEW), Ramipril 5mg OD, Atorvastatin 20mg OD.
+>
+> Yours sincerely,
+> Dr. S. Chen, Consultant Diabetologist
+
+The narrator points out: (a) investigation values are hyperlinked to their FHIR source records, (b) the letter includes both conversation content AND FHIR-sourced data, (c) the allergy is preserved.
+
+**Screen 6 — Edit and Sign Off (2:30–2:50)**
+
+The clinician edits one line (e.g., adding "She is tolerating metformin well with no GI side effects" — demonstrating inline editing). Then clicks **"Sign Off."** The document status changes to "✓ Approved." Export buttons appear: PDF, Copy to Clipboard, FHIR DocumentReference.
+
+**Screen 7 — Closing (2:50–3:00)**
+
+Brief closing card showing: "Clarke: 3 HAI-DEF models. 1 pipeline. Zero patient data leaves the building." with the project URL.
+
+**Synthetic data used:** 50 Synthea-generated UK-style patients loaded into HAPI FHIR server. 3 pre-recorded audio clips for demo scenarios (Mrs. Thompson — diabetes; Mr. Okafor — chest pain follow-up; Ms. Patel — asthma review). Audio clips are 60–90 seconds, recorded in clear studio conditions at 16kHz WAV.
+
+### 7.2 Top 5 Deployment Challenges and Mitigations
+
+| # | Challenge | Specific Mitigation | Evidence / Precedent |
+|---|---|---|---|
+| 1 | **GPU hardware cost for NHS trusts** | MedGemma 4B runs on a single consumer GPU (RTX 4060 8GB, ~£300). MedGemma 27B quantised to 4-bit runs on a single A100 40GB or two A10G 24GB GPUs. NHS trusts already procure similar hardware for PACS imaging workstations. Capital cost: £5,000–£15,000 per trust (one-time), versus >£2M/year for Heidi Health licensing across a trust's doctors at $99/clinician/month. | NHS PACS infrastructure includes GPU workstations. NHS Digital recommends GPU-enabled infrastructure for AI workloads. |
+| 2 | **NHS accent diversity and MedASR accuracy** | Fine-tune MedASR with LoRA on NHS-accented audio. Google's published fine-tuning notebook provides the methodology. MedASR's Conformer architecture handles accent variation better than RNN-based ASRs. For production: each trust collects 100–500 de-identified audio samples from its own clinicians for local LoRA fine-tuning (~1 hour compute). | MedASR was trained on ~5,000 hours of diverse physician dictations. LoRA fine-tuning is computationally cheap (minutes to hours). |
+| 3 | **FHIR API availability across NHS trusts** | Demo uses HAPI FHIR with Synthea data. Production: NHS England's Interoperability Standards mandate FHIR R4 API exposure. EMIS, SystmOne, and Cerner/Oracle Health increasingly offer FHIR endpoints. Clarke degrades gracefully — if no FHIR API is available, it operates in "documentation-only" mode (ambient scribe without EHR context), still valuable. | NHS England's NHS England Digital Interoperability Programme (2024–2025) mandates FHIR for data sharing. The eDischarge Summary Standard (PRSB, updated January 2026) mandates structured discharge data transfer. |
+| 4 | **Clinical safety of AI-generated documents** | Clarke is a drafting tool, not an autonomous documentation system. Every document requires mandatory clinician review and sign-off before entering the medical record. FHIR-sourced values are hyperlinked to source records for verification. Discrepancy flags (e.g., allergy mismatch between conversation and record) are prominently displayed in red. | Google's HAI-DEF Terms of Use explicitly state model outputs require independent professional verification. Mass General Brigham's ambient AI programme (3,000+ providers) uses the same review-before-filing workflow. |
+| 5 | **Information governance and regulatory status** | All processing is local — no external data transmission. Open-source code is fully auditable by trust IG teams. Clarke is positioned as a clinical decision support tool (not a regulated medical device), consistent with MHRA guidance on software as a medical device. A Data Protection Impact Assessment (DPIA) would be completed per trust. | NHS England published guidance on AI scribes in health settings (April 2025). Open-source audit trail addresses NHS IG requirement for transparency. |
+
+### 7.3 Production Deployment Path
+
+**Phase 1 — Single-trust pilot (months 0–6)**
+
+- **Setup:** Deploy Clarke on a dedicated GPU server (A100 or 2×A10G) within the trust's on-premise data centre or private cloud (e.g., NHS-approved Azure/AWS tenancy). Dockerised deployment using `docker-compose` with three services: Clarke application, HAPI FHIR proxy, GPU model server.
+- **Scope:** 10–20 clinicians across 2–3 specialties (e.g., diabetes outpatients, general medicine ward round, GP training practice). Selected for diversity of documentation types.
+- **Integration:** Connect FHIR proxy to the trust's EHR (EMIS/SystmOne/Cerner) via existing FHIR R4 endpoints. Read-only access — Clarke does not write to the EHR in Phase 1.
+- **Measurement:** Prospective time-motion study comparing documentation time with vs. without Clarke. Pre-post burnout survey using validated instruments (MBI or Mini-Z). Letter quality audit: completeness, accuracy, NHS format compliance. Clinician satisfaction (System Usability Scale).
+- **Governance:** DPIA completed. Information governance approval from trust Caldicott Guardian. Clinical safety case per DCB0129 standard. Ethics approval if results are intended for publication.
+
+**Phase 2 — Trust-wide rollout (months 6–12)**
+
+- Expand to all clinicians in the pilot trust. Fine-tune MedASR on the trust's collected audio data for accent optimisation. Integrate EHR write-back (with appropriate clinical safety controls) so signed-off letters can be filed directly into the patient record.
+- Begin second-trust pilot to demonstrate transferability.
+
+**Phase 3 — Multi-trust deployment (months 12–24)**
+
+- Package Clarke as a `docker-compose` deployment kit with comprehensive setup documentation.
+- Publish on NHS App Store / Digital Marketplace for trust procurement teams.
+- Work with NHS England's AI and Digital Regulation programme for national endorsement.
+- Share specialty-specific LoRA adapters (e.g., cardiology, psychiatry, paediatrics) on Hugging Face Hub.
+
+**Phase 4 — Ongoing open-source development**
+
+- Community-driven improvement via GitHub contributions. Trust-specific LoRA adapters (accent, specialty, local conventions) shared on Hugging Face Hub. Regular model updates as Google releases new MedGemma and MedASR versions.
+
+---
+
+## SECTION 8: REFERENCES
+
+1. Arab S, Chhatwal K, Hargreaves T, et al. Time Allocation in Clinical Training (TACT): national study reveals Resident Doctors spend four hours on admin for every hour with patients. *QJM: An International Journal of Medicine*. 2025;118(10):753. doi:10.1093/qjmed/hcaf141.
+
+2. Olson KD, Meeker D, Troup M, et al. Use of Ambient AI Scribes to Reduce Administrative Burden and Professional Burnout. *JAMA Network Open*. 2025;8(10):e2534976. doi:10.1001/jamanetworkopen.2025.34976.
+
+3. Pearlman K, Wan W, Shah S, Laiteerapong N. Use of an AI Scribe and Electronic Health Record Efficiency. *JAMA Network Open*. 2025;8(10):e2537000. doi:10.1001/jamanetworkopen.2025.37000.
+
+4. You JG, Landman A, Ting DY, et al. Ambient Documentation Technology in Clinician Experience of Documentation Burden and Burnout. *JAMA Network Open*. 2025. doi:10.1001/jamanetworkopen.2025.28056.
+
+5. Moura LMVR, Mishuris R, Metlay JP, et al. Hybrid Ambient Clinical Documentation and Physician Performance: Work Outside of Work, Documentation Delay, and Financial Productivity. *Journal of General Internal Medicine*. 2025. doi:10.1007/s11606-025-09979-5.
+
+6. NHS Digital. NHS Workforce Statistics — August 2025. Published November 2025. https://digital.nhs.uk/data-and-information/publications/statistical/nhs-workforce-statistics/august-2025.
+
+7. NHS Digital. General Practice Workforce — 31 December 2025. https://digital.nhs.uk/data-and-information/publications/statistical/general-and-personal-medical-services/31-december-2025.
+
+8. BMA. NHS Backlog Data Analysis. Accessed February 2026. https://www.bma.org.uk/advice-and-support/nhs-delivery-and-workforce/pressures/nhs-backlog-data-analysis.
+
+9. BMA. Medical Staffing in the NHS — Data Analysis. Accessed February 2026. https://www.bma.org.uk/advice-and-support/nhs-delivery-and-workforce/workforce/medical-staffing-in-the-nhs.
+
+10. GMC. National Training Survey 2025. Published July 2025. Referenced via NHS Employers: https://www.nhsemployers.org/news/gmc-national-training-survey-2025.
+
+11. Google Research. Next generation medical image interpretation with MedGemma 1.5 and medical speech to text with MedASR. Published January 2026. https://research.google/blog/next-generation-medical-image-interpretation-with-medgemma-15-and-medical-speech-to-text-with-medasr/.
+
+12. Google. MedASR Model Card. Hugging Face. https://huggingface.co/google/medasr.
+
+13. Google. MedASR Developer Documentation. https://developers.google.com/health-ai-developer-foundations/medasr.
+
+14. Google. MedGemma Technical Report. arXiv:2507.05201.
+
+15. Google. Health AI Developer Foundations (HAI-DEF) Technical Report. arXiv:2411.15128.
+
+16. King's Fund. Waiting Times for Elective (Non-Urgent) Treatment: Referral to Treatment (RTT). Updated December 2025. https://www.kingsfund.org.uk/insight-and-analysis/data-and-charts/waiting-times-non-urgent-treatment.
+
+17. MedGamma Clinician Survey. 47 responses from NHS and healthcare clinicians. Collected January 16 – February 8, 2026. Internal document.
+
+18. TechFundingNews. Heidi raises $65M to scale its AI scribe across global health systems. October 2025. https://techfundingnews.com/heidi-ai-care-partner-65m-series-b-global-expansion/.
+
+19. Mass General Brigham. Ambient Documentation Technologies Reduce Physician Burnout and Restore 'Joy' in Medicine. Press release, August 2025. https://www.massgeneralbrigham.org/en/about/newsroom/press-releases/ambient-documentation-technologies-reduce-physician-burnout.
+
+20. Medscape UK. Medscape UK Survey: Burnout Hits Doctors Amid NHS Pressures. June 2025.
+
+21. iatroX. The rise of AI medical scribes in UK primary care. August 2025. https://www.iatrox.com/blog/ai-medical-scribes-uk-gp-guide-tortus-accurx-heidi.
+
+22. Burnett S, Franklin BD, Moorthy K, et al. Missing Clinical Information in NHS hospital outpatient clinics: prevalence, causes and effects on patient care. *BMC Health Services Research*. 2011;11:114. doi:10.1186/1472-6963-11-114.
+
+23. NHS Resolution. Annual Report and Accounts 2024 to 2025. Published July 2025. https://www.gov.uk/government/publications/nhs-resolution-annual-report-and-accounts-2024-to-2025.
+
+24. NHS England. NHS Patient Safety Strategy — Progress Update — April 2025. https://www.england.nhs.uk/patient-safety/the-nhs-patient-safety-strategy/.
+
+25. PRSB. eDischarge Summary Standard. Updated January 2026. https://theprsb.org/standards/edischargesummary/.
+
+26. NHS Providers. NHS Digital Workforce Statistics — November 2025. https://nhsproviders.org/resources/nhs-digital-workforce-statistics-november-2025.
+
+---
+
+*Document prepared for Clarke PRD generation — Version 2.0 — February 2026*

Dockerfile

@@ -0,0 +1,19 @@
+FROM nvidia/cuda:12.4.1-runtime-ubuntu22.04
+
+RUN apt-get update && apt-get install -y \
+    python3.11 python3.11-venv python3-pip \
+    ffmpeg curl wget git && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN ln -s /usr/bin/python3.11 /usr/bin/python
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --break-system-packages --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Load FHIR data and start application
+RUN chmod +x scripts/start.sh
+EXPOSE 7860
+CMD ["scripts/start.sh"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

MedGemma High-Level Context.md

@@ -0,0 +1,174 @@
+# Competition Overview
+
+Google has released open-weight models designed to help developers more efficiently create novel healthcare and life science applications. Many clinical environments can’t rely on large, closed models that require constant internet access or centralized infrastructure. They need adaptable, privacy-focused tools that can run anywhere care is delivered.
+
+MedGemma and the rest of the HAI-DEF collection gives developers a starting point for building powerful tools while allowing them full control over the models and associated infrastructure.
+
+The competition requires us to use these models to build full fledged demonstration applications that can enhance healthcare. Examples include apps to streamline workflows, support patient communication, or facilitate diagnostics.
+
+## Minimum requirements
+
+To be considered a valid contribution, your submission should include:
+
+* a high-quality writeup describing use of a specific HAI-DEF model,  
+* associated reproducible code for your initial results, and  
+* a video for judging.
+
+Your complete submission consists of a single package containing your video (3 minutes or less) and write-up (3 pages or less). This single entry can be submitted to the main competition track, and one special technology award, so separate submissions are not required. Read the section *Submission Instructions* for more details. Please follow the provided write-up template and refer to the judging criteria for all content requirements.
+
+## Judging Criteria
+
+1. Effective use of HAI-DEF models (weighting \= 20%)  
+   1. Are HAI-DEF models used appropriately?  
+   2. Are HAI-DEF models used to their fullest potential?  
+   3. Why is this solution and its use of HAI-DEF models superior to other ones?  
+   4. At least one of HAI-DEF models such as MedGemma is mandatory  
+2. Problem Domain (weighting \= 15%)  
+   1. How important is this problem to solve?  
+   2. How plausible is it that AI is the right solution?  
+   3. Is your storytelling unbeliably captivating and inspiring?  
+   4. Is your problem definition clear?  
+   5. Is the unmet need true and clear?  
+   6. Is the problem of large magnitude in severity and ubiquity?  
+   7. Who is the target user?  
+   8. Does the solution genuinely improve the user journey?  
+3. Impact potential (weighting \= 15%)  
+   1. If the solution works, what impact would it have?  
+   2. Have you clearly and honestly articulated the real and/or anticipated impact of the application within the given problem domain?  
+   3. Have you honestly and accurately calculated your estimates, and what are those estimates?  
+4. Product feasibility (weighting \= 20%)  
+   1. Is the technical solution clearly feasible?  
+   2. Have you accurately and completely detailed model fine-tuning, model’s performance analysis, user-facing application stack, deployment challenges and how you plan on overcoming them?  
+   3. Have you communicated exactly how a product might be used in practice?  
+5. Execution and communication (weighting \= 30%)  
+   1. Is the quality of your project world-class?  
+   2. Is the communication of your work concise (using as few words as possible to most completely and comprehensibly communicate information)?  
+   3. Does the submission package follow the provided template, including a video demo and a write-up with links to source material?  
+      1. Do you have a public interactive live demo app?  
+      2. Open-weight Hugging Face model tracing to a HAI-DEF model?   
+   4. Is your communication in the video of maximal clarity?  
+   5. Is the video polished and stylish?  
+   6. Does the video effectively communicate and demonstrate your application?  
+   7. Is your technical write-up easy-to-read?  
+   8. Is your source code organised, annotated and reusable?  
+   9. Do you have a cohesive and compelling narrative across all submitted materials that effectivley articulates how you meet the rest of the judging criteria?
+
+## Dataset Description
+
+Welcome to the MedGemma Impact Challenge
+
+This is a Hackathon with no provided dataset.
+
+Please refer to the following resources, and note that use of HAI-DEF and MedGemma are subject to the [HAI-DEF Terms of Use](https://developers.google.com/health-ai-developer-foundations/terms):
+
+* Hugging Face model collections:  
+  * [Complete HAI-DEF collection](https://huggingface.co/collections/google/health-ai-developer-foundations-hai-def)  
+  * [MedGemma collection](https://huggingface.co/collections/google/medgemma-release)  
+* [Developer forum](https://discuss.ai.google.dev/c/hai-def)  
+* [HAI-DEF concept apps for inspiration](https://huggingface.co/collections/google/hai-def-concept-apps)  
+* [HAI-DEF main site](https://goo.gle/hai-def)
+
+# Goal
+
+1. Win the Main Track 1st place prize ($30,000)  
+   1. this prizes are awarded to the best overall project that demonstrate exceptional vision, technical execution, and potential for real-world impact.  
+2. Wins one of the special track prizes ($$5000)  
+   1. Agentic Workflow Prize \- It is awarded for the project that most effectively reimagines a complex workflow by deploying HAI-DEF models as intelligent agents or callable tools. The winning solution will demonstrate a significant overhaul of a challenging process, showcasing the power of agentic AI to improve efficiency and outcomes.  
+   2. Novel Task Prize \- Awarded for the most impressive fine-tuned model that successfully adapts a HAI-DEF model to perform a useful task for which it was not originally trained on pre-release.  
+   3. The Edge AI Prize \- This prize is awarded to the most impressive solution that brings AI out of the cloud and into the field. It will be awarded to the team that best adapts a HAI-DEF model to run effectively on a local device like a mobile phone, portable scanner, lab instrument, or other edge hardware.
+
+# Constraints
+
+1. Complete the product in 3 days (using an AI tool like Claude or Codex to do this successfully)  
+   * Assuming I have 8 hours per day to complete the product (24 hours in total)  
+2. Writeup structure  
+   * \#\#\# Project name   
+   * \[A concise name for your project.\]  
+   *   
+   * \#\#\# Your team   
+   * \[Name your team members, their speciality and the role they played.\]  
+   *   
+   * \#\#\# Problem statement  
+   * \[Your answer to the “Problem domain” & “Impact potential” criteria\]  
+   *   
+   * \#\#\# Overall solution:   
+   * \[Your answer to “Effective use of HAI-DEF models” criterion\]   
+   *   
+   * \#\#\# Technical details   
+   * \[Your answer to “Product feasibility” criterion\]
+
+# Target Timeline
+
+**Thursday 12 February**
+
+1. Conjecture the best possible ideas to maximise chance of winning the competition within the constraints and pick the best one  
+   1. Use Claude Opus 4.6, ChatGPT 5.2 Thinking, Gemini 3 Pro, and Grok Thinking to conjecture ideas and pick the best one  
+2. Use OpenClaw to compile all the useful information as context (saved to a Google Docs titled “Additional Competition Context”) to use to create PRDs (Project Requirement Documents) along with “MedGemma High-Level Context.md”  
+3. Use Claude Opus 4.6 Extended to create first-draft version of the PRDs  
+4. Review and edit the PRDs as needed  
+5. Feed preliminary PRDs to Lovable PRD Generator along with “MedGemma High-Level Context.md”, “Additional Competition [Context.md](http://Context.md)”, and “Clarke\_Product\_Specifcation\_V1.md” and any other requests/context   
+6. Use Lovable PRD Generator to create new and improved PRDs  
+7. Select, review and edit the final PRDs as needed  
+8. Complete planning and preparation of guiding Project-Requirements-Documents (PRDs)  
+   1. clarke\_PRD\_masterplan.md   
+      1. This file should provide a complete, high-level overview of what we’re building, why we’re building it, the goals, and the constraints  
+         1. What are we building?  
+         2. Why are we building it?  
+         3. Why is it important?  
+         4. What are the goals?  
+         5. What are the constraints?  
+         6. What must be fulfilled to guarantee a successful outcome?  
+   2. clarke\_PRD\_implementation.md  
+      1. This file should outline the order in which we should build and integrate components of the product to ensure there is a clean, understandable sequence  
+         1. What steps must we take to ensure a successful outcome?  
+         2. What is the optimal order for us to take those steps to guarantee a successful outcome with the constraints?  
+   3. clarke\_PRD\_design\_guidelines.md  
+      1. This file should detail the visual aesthetics of the product and how it should make the user feel when using it  
+         1. What should the product look like?  
+         2. What should the product feel like?  
+         3. Give examples using Mobbin or Dribbble or anything else about the aesthetics and vibe I want to cultivate  
+   4. clarke\_PRD\_userflow.md  
+      1. This file should detail the intended user experience and journey, optimising for ease of use and navigation  
+         1. What is the optimal the step-by-step description of the idea user navigation journey from very start to finish?  
+   5. clarke\_PRD\_technical\_spec.md  
+      1. **Folder/file structure** — the exact project directory tree Codex should create  
+      2. **Technology stack** — every framework, library, and version (e.g., Gradio 4.x, transformers 4.45, torch 2.x)  
+      3. **Data models/schemas** — what objects exist in the system (Patient, Consultation, Transcript, ClinicalDocument), their fields, types, and relationships  
+      4. **API contracts** — what each backend endpoint accepts and returns  
+      5. **Model serving specification** — how each HAI-DEF model is loaded, called, and what input/output format it expects  
+      6. **Synthetic data spec** — exact format of demo data (FHIR resources, sample transcripts, lab reports) so Codex can generate it  
+   6. clarke\_PRD\_tasks.md  
+      1. This file should very explicitly detail every single, step-by-step task that the AI tool (e.g. Codex) should execute on to culminate in a product that completely, without fail, achieves the goal within the constraints  
+         1. What are the specific tasks the AI should execute on to successfully build a world-class product and fulfil our goal?  
+         2. for each task, specify what "done" looks like. For example, "Task 3 is done when the /transcribe endpoint accepts a .wav file and returns JSON with a transcript field."  
+   7. clarke\_PRD\_rules.md  
+      1. This file should convey how the LLM/AI tool should behave, communicate and execute actions and correct errors to ensure maximal speed, accuracy, effectiveness, transparency and efficiency  
+         1. What information can I communicate to the AI to ensure the best possible comprehension and communication of information and execution of action?
+
+**Friday 13 February to Sunday 15th February**
+
+1. Complete building of the product  
+   1. AI tool should first read and understand all the files. There should be some sort of test to check and ensure the AI has read and understood all the files before starting.  
+   2. The AI should then execute one task at a time (using tasks.md), making sure to explain everything and every step that it is doing in a way that a layman could understand as well as testing or creating a way to test that the task has indeed been completed successfully  
+      1. The AI should also correct any errors that arise in the execution
+
+**Monday 16th February**
+
+1. Complete the 3-page write up for the competition submission  
+   1. The writeup should use the “Propose Writeup template”  
+   2. The writeup should ensure that it completely satisfies and exceeds the judging criteria to maximise chance of achieving the goal  
+   3. The writeup should be as high-level and easy-to-read as possible
+
+**Tuesday 17th February to Saturday 21st February**
+
+1. Complete the 3-minute video  
+   1. The video will be the main, attention-grabbing medium of communication so should be optimised to exceed every aspect of the judging criteria 
+
+**Sunday 22nd February**
+
+1. Submit everything  
+   1. 3-page writeup  
+   2. Video (3 mins or less)  
+   3. Public code repository  
+   4. PUblic interactive live demo app  
+   5. Open-weight Hugging Face model tracing to a HAI-DEF model

README.md

@@ -1,2 +1,257 @@
-# clarke
-Clarke — AI-powered ambient clinical documentation system for NHS clinicians
+---
+title: Clarke
+emoji: 🩺
+colorFrom: blue
+colorTo: yellow
+sdk: docker
+app_port: 7860
+---
+
+# Clarke
+
+**AI-powered NHS clinic letter generation: from consultation audio to structured clinical document in under 60 seconds.**
+
+Clarke is an ambient clinical documentation system that converts doctor-patient audio consultations into structured NHS clinic letters. It coordinates three [HAI-DEF](https://goo.gle/hai-def) models as autonomous agents in a unified agentic pipeline: medical speech recognition, EHR context retrieval via FHIR, and context-enriched document generation.
+
+Built for the [MedGemma Impact Challenge](https://www.kaggle.com/competitions/medgemma-impact-challenge) on Kaggle, targeting the **Agentic Workflow Prize**.
+
+| Resource | Link |
+|----------|------|
+| Live demo | [yashvshetty-clarke.hf.space](https://yashvshetty-clarke.hf.space) |
+| Source code | [github.com/yvs-tinker/clarke](https://github.com/yvs-tinker/clarke) |
+| Evaluation report | [evaluation/EVALUATION.md](evaluation/EVALUATION.md) |
+| LoRA adapter | [yashvshetty/clarke-medgemma-27b-lora](https://huggingface.co/yashvshetty/clarke-medgemma-27b-lora) |
+| Demo video | *Coming soon* |
+
+---
+
+## Results
+
+Clarke was evaluated across five NHS outpatient consultations spanning endocrine, cardiology, respiratory, heart failure, and mental health. Full methodology and per-patient breakdowns are in the [evaluation report](evaluation/EVALUATION.md).
+
+| Component | Metric | Score |
+|-----------|--------|-------|
+| MedASR (speech-to-text) | Word Error Rate | 13.28% across 1,438 words |
+| EHR Agent (record retrieval) | Fact Recall | 100% (70/70 facts retrieved) |
+| EHR Agent | Precision | 98.6% (1 hallucination in 71 facts) |
+| Document Generation (base) | BLEU-1 / ROUGE-L | 0.54 / 0.44 |
+| Document Generation (after QLoRA) | BLEU-1 / ROUGE-L | **0.71 / 0.47** (+31% BLEU-1) |
+
+QLoRA fine-tuning on just 5 gold-standard NHS clinic letters improved lexical accuracy by 31%, trained in 15 minutes on a single A100 GPU. The adapter is published at [`yashvshetty/clarke-medgemma-27b-lora`](https://huggingface.co/yashvshetty/clarke-medgemma-27b-lora).
+
+---
+
+## The Problem
+
+NHS doctors spend 73% of their working time on non-patient-facing tasks, with only 17.9% on direct patient care (Arab et al., QJM 2025; TACT study, 137 doctors, 7 months). Documentation alone consumes approximately 15 minutes per patient encounter. Across a typical 10-12 patient clinic, that is 2.5-3 hours of writing per session (clinician survey, n=47). At the scale of 190,200 FTE doctors in England (NHS Digital, Aug 2025), the impact compounds: 7,248 unfilled medical vacancies, 7.31 million patients on the waiting list (BMA/King's Fund, Nov 2025), and 61% of trainees at moderate-to-high burnout risk (GMC NTS, 2025).
+
+Ambient AI scribes have shown promise, reducing clinician burnout from 51.9% to 38.8% within 30 days (Olson et al., JAMA Netw Open 2025). But every existing solution (Heidi Health, DAX Copilot, Tortus) generates documents from conversation audio alone. None retrieves EHR context, meaning clinicians must still manually add lab values, medication lists, and allergy checks. All are cloud-dependent, closed-source, and costly: Heidi alone would cost an estimated 226M GBP/year at NHS scale.
+
+Clarke closes both gaps: ambient documentation fused with intelligent EHR retrieval, fully open-source, designed for local deployment.
+
+### Clinician Validation
+
+A 47-respondent clinician survey confirmed the problem. Respondents reported spending substantial time on documentation, identified clinical letter writing as the most time-consuming task, and expressed strong interest in AI-assisted documentation tools with EHR integration.
+
+---
+
+## Architecture
+
+Clarke orchestrates three HAI-DEF models in a five-stage agentic workflow. Each model operates as an autonomous agent, making its own decisions about what to process, retrieve, or generate:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        CLARKE PIPELINE                          │
+│                                                                 │
+│   ┌─────────────┐                                               │
+│   │  Audio Input │  Upload or record consultation audio         │
+│   └──────┬──────┘                                               │
+│          │                                                      │
+│          ▼                                                      │
+│   ┌─────────────────────────────────────────┐                   │
+│   │  1. MedASR  (google/medasr)             │                   │
+│   │     Medical speech recognition agent    │                   │
+│   │     Audio -> clinical transcript        │                   │
+│   └──────┬──────────────────────────────────┘                   │
+│          │                                                      │
+│          ▼                                                      │
+│   ┌─────────────────────────────────────────┐    ┌────────────┐ │
+│   │  2. MedGemma 4B IT                      │<-->│ FHIR Server│ │
+│   │     (google/medgemma-1.5-4b-it)         │    │ Patient    │ │
+│   │     EHR context retrieval agent         │    │ records    │ │
+│   │     Patient ID -> structured context    │    └────────────┘ │
+│   └──────┬──────────────────────────────────┘                   │
+│          │  transcript + patient context                        │
+│          ▼                                                      │
+│   ┌─────────────────────────────────────────┐                   │
+│   │  3. MedGemma 27B Text-IT                │                   │
+│   │     (google/medgemma-27b-text-it)       │                   │
+│   │     Document generation agent           │                   │
+│   │     Transcript + context -> NHS letter  │                   │
+│   └──────┬──────────────────────────────────┘                   │
+│          │                                                      │
+│          ▼                                                      │
+│   ┌─────────────┐                                               │
+│   │  Draft Letter│  Clinician review, edit, and sign-off       │
+│   └─────────────┘                                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Why three models, not one?** Each HAI-DEF model contributes a distinct capability that no single model can replicate. MedASR provides medical-domain speech recognition optimised for clinical terminology. MedGemma 4B understands FHIR resources natively, retrieving and synthesising relevant patient history. MedGemma 27B generates clinically accurate prose grounded in both the conversation and the medical record. The pipeline produces documents that reference actual lab values, include current medication lists, and cross-check for consistency. No conversation-only scribe can achieve this.
+
+---
+
+## Features
+
+- **End-to-end ambient documentation** from patient selection through letter sign-off.
+- **Three-model agentic pipeline** with MedASR, MedGemma 4B, and MedGemma 27B operating as coordinated agents.
+- **FHIR-backed context enrichment** retrieving demographics, conditions, medications, lab results, allergies, and diagnostic reports.
+- **Structured NHS clinic letter output** following standard clinical correspondence format.
+- **QLoRA fine-tuning** with a published LoRA adapter achieving 31% BLEU-1 improvement.
+- **Privacy-preserving architecture** designed for local deployment; no patient data leaves the hospital network.
+- **Deterministic safety architecture** in the EHR agent ensures 100% fact recall by design.
+- **Human-in-the-loop review** with mandatory clinician sign-off before any document is exported.
+- **Mock-safe local development** enabling the full pipeline to run without GPU or gated model access.
+
+---
+
+## Models
+
+Clarke uses three models from Google's [Health AI Developer Foundations (HAI-DEF)](https://goo.gle/hai-def) collection:
+
+| Role | Model | What it does |
+|------|-------|-------------|
+| Speech recognition | [`google/medasr`](https://huggingface.co/google/medasr) | Converts consultation audio to text with medical vocabulary optimisation |
+| EHR retrieval | [`google/medgemma-1.5-4b-it`](https://huggingface.co/google/medgemma-1.5-4b-it) | Queries FHIR records and synthesises structured patient context |
+| Document generation | [`google/medgemma-27b-text-it`](https://huggingface.co/google/medgemma-27b-text-it) | Generates NHS clinic letters from transcript + EHR context |
+
+Additionally, a QLoRA fine-tuned adapter is published at [`yashvshetty/clarke-medgemma-27b-lora`](https://huggingface.co/yashvshetty/clarke-medgemma-27b-lora) (173.4 MB, LoRA rank 16, trained on 5 NHS clinic letter examples).
+
+---
+
+## Evaluation Summary
+
+Full methodology, per-patient results, error taxonomy, and limitations are documented in the [evaluation report](evaluation/EVALUATION.md). Headline findings:
+
+**MedASR (Word Error Rate: 13.28%)** Most clinical terms transcribed correctly. Errors concentrated on patient names (resolved from EHR, not transcript) and rare medical terms. Downstream agents correct most transcription errors using authoritative EHR data.
+
+**EHR Agent (100% recall, 98.6% precision)** Every allergy, medication, lab result, and diagnosis was retrieved across all five patients. One borderline hallucination occurred (a clinically correct trend annotation). The deterministic query architecture guarantees no stored fact is missed.
+
+**Document Generation (BLEU-1 0.71 after QLoRA)** The base model scored BLEU-1 0.54. After QLoRA fine-tuning on 5 gold-standard NHS letters (15 minutes of training, single A100), BLEU-1 rose to 0.71 (+31%). All generated letters correctly captured diagnoses, medications, lab results, and management plans.
+
+---
+
+## QLoRA Fine-Tuning
+
+Clarke includes a QLoRA fine-tuning pipeline for adapting MedGemma 27B to NHS letter conventions.
+
+| Parameter | Value |
+|-----------|-------|
+| Method | QLoRA (4-bit base + LoRA rank 16, alpha 32) |
+| Target modules | q_proj, k_proj, v_proj, o_proj |
+| Training data | 5 gold-standard NHS clinic letters |
+| Training time | ~15 minutes on A100 40 GB (Google Colab) |
+| Framework | Unsloth |
+| Adapter size | 173.4 MB |
+| Result | BLEU-1 improved from 0.54 to 0.71 (+31%) |
+
+Training scripts are in [`finetuning/`](finetuning/). The adapter is published at [`yashvshetty/clarke-medgemma-27b-lora`](https://huggingface.co/yashvshetty/clarke-medgemma-27b-lora).
+
+---
+
+## Quick Start
+
+### Run in mock mode (no GPU required)
+
+```bash
+git clone https://github.com/yvs-tinker/clarke.git
+cd clarke
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+USE_MOCK_FHIR=true MEDASR_MODEL_ID=mock MEDGEMMA_4B_MODEL_ID=mock MEDGEMMA_27B_MODEL_ID=mock python3 app.py
+```
+
+Open [http://localhost:7860](http://localhost:7860).
+
+### Run with real models (requires A100 GPU + HuggingFace access)
+
+Create a `.env` file:
+
+```
+MEDASR_MODEL_ID=google/medasr
+MEDGEMMA_4B_MODEL_ID=google/medgemma-1.5-4b-it
+MEDGEMMA_27B_MODEL_ID=google/medgemma-27b-text-it
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
+FHIR_BASE_URL=http://localhost:8080/fhir
+APP_HOST=0.0.0.0
+APP_PORT=7860
+```
+
+Then launch with `python3 app.py`. Requires NVIDIA A100 80 GB for the full three-model pipeline.
+
+---
+
+## Repository Structure
+
+```
+clarke/
+├── app.py                    # Application entry point (FastAPI + Gradio)
+├── backend/
+│   ├── api.py                # FastAPI REST endpoints
+│   ├── orchestrator.py       # Pipeline coordinator
+│   ├── config.py             # Environment and settings
+│   ├── schemas.py            # Pydantic data models
+│   ├── models/
+│   │   ├── medasr.py         # MedASR transcription wrapper
+│   │   ├── ehr_agent.py      # MedGemma 4B EHR retrieval agent
+│   │   └── doc_generator.py  # MedGemma 27B letter generation agent
+│   ├── fhir/
+│   │   ├── client.py         # FHIR server client
+│   │   ├── queries.py        # FHIR resource queries
+│   │   ├── tools.py          # Agent tool definitions
+│   │   └── mock_api.py       # Mock FHIR server for development
+│   └── prompts/              # Jinja2 prompt templates
+├── frontend/
+│   ├── ui.py                 # Gradio interface builder
+│   ├── components.py         # UI screen components
+│   ├── state.py              # Session state management
+│   └── assets/               # CSS, logo, static files
+├── data/                     # Demo audio, transcripts, synthetic FHIR bundles
+├── evaluation/               # Evaluation scripts and report
+│   ├── EVALUATION.md         # Full evaluation report
+│   ├── eval_medasr.py        # Word Error Rate evaluation
+│   ├── eval_ehr_agent.py     # EHR fact recall evaluation
+│   ├── eval_doc_gen.py       # BLEU/ROUGE-L evaluation
+│   └── gold_standards/       # Reference letters for scoring
+├── finetuning/               # LoRA training scripts and adapter
+└── tests/                    # Unit, integration, and end-to-end tests
+```
+
+---
+
+## Development
+
+Clarke was built by a solo 4th-year medical student over the competition period. Development used Claude (Anthropic) for architectural design, evaluation methodology, and technical problem-solving, and Codex (GitHub) for code implementation via pull requests.
+
+Key technical decisions documented in the [evaluation report](evaluation/EVALUATION.md):
+- **Deterministic EHR retrieval over agentic tool-calling** after prototyping showed MedGemma 4B's agentic queries were unreliable.
+- **Full bfloat16 precision for inference** after discovering 4-bit quantisation breaks weight tying in MedGemma 27B.
+- **Multi-agent error correction** where each pipeline stage compensates for upstream errors.
+
+---
+
+## Licence
+
+- **Code:** [Apache 2.0](LICENSE)
+- **Models:** Subject to [HAI-DEF Terms of Use](https://developers.google.com/health-ai-developer-foundations/terms) and HuggingFace gating requirements.
+
+---
+
+## Acknowledgements
+
+- [MedGemma Impact Challenge](https://www.kaggle.com/competitions/medgemma-impact-challenge) by Google Health AI
+- [HAI-DEF](https://goo.gle/hai-def) model releases
+- [Synthea](https://synthetichealth.github.io/synthea/) for synthetic patient data
+- [HAPI FHIR](https://hapifhir.io/) server ecosystem

app.py

@@ -0,0 +1,33 @@
+"""Application entry point mounting Clarke Gradio UI within FastAPI."""
+
+from __future__ import annotations
+
+import uvicorn
+from fastapi import FastAPI
+import gradio as gr
+
+from backend.api import app as fast_api
+from backend.config import get_settings
+from frontend.ui import build_ui
+
+
+def create_app() -> FastAPI:
+    """Create the FastAPI application with mounted Gradio interface.
+
+    Args:
+        None: Uses existing FastAPI API app and Gradio UI builder.
+
+    Returns:
+        FastAPI: Unified ASGI app serving API and web UI.
+    """
+
+    demo = build_ui()
+    return gr.mount_gradio_app(fast_api, demo, path="/")
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    settings = get_settings()
+    uvicorn.run(app, host=settings.APP_HOST, port=settings.APP_PORT)

backend/__init__.py

@@ -0,0 +1 @@
+"""Backend package for Clarke services."""

backend/api.py

@@ -0,0 +1,490 @@
+"""FastAPI API surface for Clarke consultation and health endpoints."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from shutil import copyfileobj
+from typing import Any
+
+from fastapi import BackgroundTasks, Body, FastAPI, File, Form, HTTPException, UploadFile
+
+from backend.audio import convert_to_wav_16k, validate_audio
+from backend.config import get_settings
+from backend.errors import AudioError, ModelExecutionError, get_component_logger
+from backend.orchestrator import PipelineOrchestrator
+from backend.schemas import ConsultationStatus, Patient
+
+app = FastAPI(title="Clarke API", version="0.1.0")
+settings = get_settings()
+logger = get_component_logger("api")
+orchestrator = PipelineOrchestrator()
+
+
+def _iso_timestamp() -> str:
+    """Return UTC timestamp in ISO 8601 format with Z suffix.
+
+    Args:
+        None: No input parameters.
+
+    Returns:
+        str: UTC timestamp string.
+    """
+
+    return datetime.now(tz=timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _load_clinic_list_payload() -> dict[str, Any]:
+    """Load clinic list fixture JSON from disk.
+
+    Args:
+        None: Reads static clinic list fixture file.
+
+    Returns:
+        dict[str, Any]: Parsed clinic list JSON payload.
+    """
+
+    clinic_path = Path("data/clinic_list.json")
+    if not clinic_path.exists():
+        raise HTTPException(status_code=500, detail="Clinic list file is missing")
+    return json.loads(clinic_path.read_text(encoding="utf-8"))
+
+
+def _load_patient_resource(patient_id: str) -> dict[str, Any]:
+    """Load patient resource for a patient id from local FHIR bundle fixture.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        dict[str, Any]: FHIR Patient resource from bundle fixture.
+    """
+
+    bundle_path = Path("data/fhir_bundles") / f"{patient_id}.json"
+    if not bundle_path.exists():
+        return {}
+    bundle = json.loads(bundle_path.read_text(encoding="utf-8"))
+    for entry in bundle.get("entry", []):
+        resource = entry.get("resource", {})
+        if resource.get("resourceType") == "Patient":
+            return resource
+    return {}
+
+
+def _patient_from_records(clinic_row: dict[str, Any], patient_resource: dict[str, Any]) -> Patient:
+    """Build a Patient schema object from clinic list and FHIR records.
+
+    Args:
+        clinic_row (dict[str, Any]): Patient row from `clinic_list.json`.
+        patient_resource (dict[str, Any]): FHIR Patient resource dictionary.
+
+    Returns:
+        Patient: Normalised patient object for API responses.
+    """
+
+    nhs_number = ""
+    for identifier in patient_resource.get("identifier", []):
+        value = str(identifier.get("value", "")).strip()
+        if value:
+            nhs_number = value
+            break
+
+    date_of_birth = str(patient_resource.get("birthDate", ""))
+    if date_of_birth and "-" in date_of_birth:
+        yyyy, mm, dd = date_of_birth.split("-")
+        date_of_birth = f"{dd}/{mm}/{yyyy}"
+
+    return Patient(
+        id=str(clinic_row.get("id", "")),
+        nhs_number=nhs_number,
+        name=str(clinic_row.get("name", "")),
+        date_of_birth=date_of_birth,
+        age=int(clinic_row.get("age", 0)),
+        sex=str(clinic_row.get("sex", "")),
+        appointment_time=str(clinic_row.get("time", "")),
+        summary=str(clinic_row.get("summary", "")),
+    )
+
+
+def _get_patient(patient_id: str) -> Patient:
+    """Resolve a patient from local fixture data.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        Patient: Patient record for the requested id.
+    """
+
+    payload = _load_clinic_list_payload()
+    for row in payload.get("patients", []):
+        if str(row.get("id")) == patient_id:
+            resource = _load_patient_resource(patient_id)
+            return _patient_from_records(row, resource)
+    raise HTTPException(status_code=404, detail=f"Patient not found: {patient_id}")
+
+
+def _health_fhir_status() -> dict[str, Any]:
+    """Compute lightweight FHIR service health metadata for health endpoint.
+
+    Args:
+        None: Reads settings and local data fixtures.
+
+    Returns:
+        dict[str, Any]: FHIR connectivity status and available patient count.
+    """
+
+    clinic_list_path = Path("data/clinic_list.json")
+    if settings.USE_MOCK_FHIR and clinic_list_path.exists():
+        payload = json.loads(clinic_list_path.read_text(encoding="utf-8"))
+        patients = payload.get("patients", [])
+        return {"status": "connected", "patient_count": len(patients)}
+
+    return {"status": "unknown", "patient_count": 0}
+
+
+def _save_upload_temp(upload: UploadFile, destination: Path) -> Path:
+    """Persist an uploaded file to disk for subsequent conversion/validation.
+
+    Args:
+        upload (UploadFile): Uploaded file object from multipart payload.
+        destination (Path): Output path for storing file bytes.
+
+    Returns:
+        Path: Saved destination path.
+    """
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with destination.open("wb") as output_stream:
+        copyfileobj(upload.file, output_stream)
+    return destination
+
+
+@app.get("/api/v1/health")
+def get_health() -> dict[str, Any]:
+    """Return current service, model, and GPU health state.
+
+    Args:
+        None: Uses process-level singletons for status.
+
+    Returns:
+        dict[str, Any]: Health response payload.
+    """
+
+    gpu_info = orchestrator._medasr_model.model_manager.check_gpu()
+    models = {
+        "medasr": {
+            "loaded": orchestrator._medasr_model.model_manager.get_model("medasr") is not None,
+            "device": "cuda:0" if gpu_info["vram_total_bytes"] > 0 else "cpu",
+        },
+        "medgemma_4b": {"loaded": False, "device": "n/a", "quantised": "4bit"},
+        "medgemma_27b": {"loaded": False, "device": "n/a", "quantised": "4bit"},
+    }
+
+    return {
+        "status": "healthy",
+        "models": models,
+        "fhir": _health_fhir_status(),
+        "gpu": {
+            "name": gpu_info["gpu_name"],
+            "vram_used_gb": round(float(gpu_info["vram_used_bytes"]) / 1_000_000_000, 2),
+            "vram_total_gb": round(float(gpu_info["vram_total_bytes"]) / 1_000_000_000, 2),
+        },
+        "timestamp": _iso_timestamp(),
+    }
+
+
+@app.get("/api/v1/patients")
+def get_patients() -> dict[str, list[dict[str, Any]]]:
+    """Return clinic patient list with normalised schema fields.
+
+    Args:
+        None: Reads local clinic list and FHIR bundle fixtures.
+
+    Returns:
+        dict[str, list[dict[str, Any]]]: Patient list payload.
+    """
+
+    payload = _load_clinic_list_payload()
+    patients: list[dict[str, Any]] = []
+    for row in payload.get("patients", []):
+        patient_id = str(row.get("id", ""))
+        if not patient_id:
+            continue
+        patient_model = _patient_from_records(row, _load_patient_resource(patient_id))
+        patients.append(patient_model.model_dump())
+    return {"patients": patients}
+
+
+@app.get("/api/v1/patients/{patient_id}")
+def get_patient(patient_id: str) -> dict[str, Any]:
+    """Return a single patient by id.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        dict[str, Any]: Patient payload.
+    """
+
+    patient = _get_patient(patient_id)
+    return patient.model_dump()
+
+
+@app.post("/api/v1/patients/{patient_id}/context")
+def generate_patient_context(patient_id: str) -> dict[str, Any]:
+    """Generate patient context via EHR agent and return context JSON.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        dict[str, Any]: Structured patient context payload.
+    """
+
+    _get_patient(patient_id)
+    context = orchestrator._ehr_agent.get_patient_context(patient_id)
+    return context.model_dump(mode="json")
+
+
+@app.post("/api/v1/consultations/start", status_code=201)
+def start_consultation(payload: dict[str, str], background_tasks: BackgroundTasks) -> dict[str, Any]:
+    """Start a consultation session and trigger context prefetch in background.
+
+    Args:
+        payload (dict[str, str]): Request body containing patient_id.
+        background_tasks (BackgroundTasks): FastAPI background task runner.
+
+    Returns:
+        dict[str, Any]: Consultation identifier and initial state.
+    """
+
+    patient_id = payload.get("patient_id", "")
+    if not patient_id:
+        raise HTTPException(status_code=400, detail="patient_id is required")
+    patient = _get_patient(patient_id)
+
+    consultation = orchestrator.start_consultation(patient)
+    background_tasks.add_task(orchestrator.prefetch_context, consultation.id)
+
+    return {
+        "consultation_id": consultation.id,
+        "patient_id": patient_id,
+        "status": ConsultationStatus.RECORDING.value,
+        "started_at": consultation.started_at,
+    }
+
+
+@app.post("/api/v1/consultations/{consultation_id}/audio")
+def upload_audio(
+    consultation_id: str,
+    audio_file: UploadFile = File(...),
+    is_final: bool = Form(...),
+) -> dict[str, Any]:
+    """Accept consultation audio, convert to MedASR format, and store metadata.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+        audio_file (UploadFile): Uploaded WAV/WebM audio file.
+        is_final (bool): Whether upload is the final complete recording.
+
+    Returns:
+        dict[str, Any]: Upload acknowledgement and validated duration seconds.
+    """
+
+    try:
+        consultation = orchestrator.get_consultation(consultation_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    extension = Path(audio_file.filename or "").suffix.lower()
+    if extension not in {".wav", ".webm"}:
+        raise HTTPException(status_code=400, detail="Only WAV or WebM audio uploads are supported")
+
+    uploads_root = Path("data/uploads") / consultation_id
+    raw_path = uploads_root / f"raw{extension}"
+    original_stem = Path(audio_file.filename or "audio").stem or "audio"
+    wav_path = uploads_root / f"{original_stem}_16k.wav"
+
+    try:
+        _save_upload_temp(audio_file, raw_path)
+        processed_path = raw_path if extension == ".wav" else Path(convert_to_wav_16k(str(raw_path), str(wav_path)))
+        if extension == ".wav":
+            processed_path = Path(convert_to_wav_16k(str(raw_path), str(wav_path)))
+
+        audio_metadata = validate_audio(str(processed_path))
+    except AudioError as exc:
+        logger.error("Audio processing failed", consultation_id=consultation_id, error=str(exc))
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    consultation.audio_file_path = str(processed_path)
+
+    logger.info(
+        "Stored consultation audio",
+        consultation_id=consultation_id,
+        duration_s=audio_metadata["duration_s"],
+        is_final=is_final,
+    )
+
+    return {
+        "consultation_id": consultation_id,
+        "audio_received": True,
+        "duration_s": audio_metadata["duration_s"],
+    }
+
+
+@app.post("/api/v1/consultations/{consultation_id}/end", status_code=202)
+def end_consultation(consultation_id: str) -> dict[str, Any]:
+    """End a consultation and execute full processing pipeline.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+
+    Returns:
+        dict[str, Any]: Pipeline kickoff and status metadata.
+    """
+
+    try:
+        consultation = orchestrator.end_consultation(consultation_id)
+        progress = orchestrator.get_progress(consultation_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except TimeoutError as exc:
+        raise HTTPException(status_code=504, detail={"error": "timeout", "message": str(exc)}) from exc
+    except AudioError as exc:
+        raise HTTPException(status_code=400, detail={"error": "audio_error", "message": str(exc)}) from exc
+    except ModelExecutionError as exc:
+        error_type = "audio_error" if "transcribed" in str(exc).lower() else "model_error"
+        status_code = 400 if error_type == "audio_error" else 500
+        raise HTTPException(status_code=status_code, detail={"error": error_type, "message": str(exc)}) from exc
+
+    return {
+        "consultation_id": consultation.id,
+        "status": consultation.status.value,
+        "pipeline_stage": progress.stage.value,
+        "message": "Pipeline completed. Document is ready for review.",
+    }
+
+
+@app.get("/api/v1/consultations/{consultation_id}/transcript")
+def get_transcript(consultation_id: str) -> dict[str, Any]:
+    """Return transcript for a consultation when available.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+
+    Returns:
+        dict[str, Any]: Transcript payload.
+    """
+
+    try:
+        consultation = orchestrator.get_consultation(consultation_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    if consultation.transcript is None:
+        raise HTTPException(status_code=404, detail="Transcript not generated yet")
+    return consultation.transcript.model_dump(mode="json")
+
+
+@app.get("/api/v1/consultations/{consultation_id}/document")
+def get_document(consultation_id: str) -> dict[str, Any]:
+    """Return generated document placeholder for a consultation.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+
+    Returns:
+        dict[str, Any]: Consultation document object or null.
+    """
+
+    try:
+        consultation = orchestrator.get_consultation(consultation_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    return {
+        "consultation_id": consultation_id,
+        "document": consultation.document.model_dump(mode="json") if consultation.document else None,
+    }
+
+
+@app.get("/api/v1/consultations/{consultation_id}/progress")
+def get_progress(consultation_id: str) -> dict[str, Any]:
+    """Return latest pipeline progress object for a consultation.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+
+    Returns:
+        dict[str, Any]: Pipeline progress payload.
+    """
+
+    try:
+        progress = orchestrator.get_progress(consultation_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    return progress.model_dump(mode="json")
+
+
+@app.post("/api/v1/consultations/{consultation_id}/document/sign-off")
+def sign_off_document(consultation_id: str, payload: dict[str, Any] | None = Body(default=None)) -> dict[str, Any]:
+    """Sign off a generated document and set consultation status to signed off.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+
+    Returns:
+        dict[str, Any]: Signed-off document payload with updated status.
+    """
+
+    sections = (payload or {}).get("sections", [])
+
+    try:
+        if sections:
+            orchestrator.update_document_sections(consultation_id, sections)
+        document = orchestrator.sign_off_document(consultation_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ModelExecutionError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {
+        "consultation_id": consultation_id,
+        "status": ConsultationStatus.SIGNED_OFF.value,
+        "document": document.model_dump(mode="json"),
+    }
+
+
+@app.post("/api/v1/consultations/{consultation_id}/document/regenerate-section")
+def regenerate_document_section(
+    consultation_id: str,
+    payload: dict[str, str] = Body(...),
+) -> dict[str, Any]:
+    """Regenerate one document section while keeping other sections unchanged.
+
+    Args:
+        consultation_id (str): Consultation identifier.
+        payload (dict[str, str]): Request body containing `section_heading`.
+
+    Returns:
+        dict[str, Any]: Updated document payload.
+    """
+
+    section_heading = payload.get("section_heading", "").strip()
+    if not section_heading:
+        raise HTTPException(status_code=400, detail="section_heading is required")
+
+    try:
+        document = orchestrator.regenerate_document_section(consultation_id, section_heading)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ModelExecutionError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {
+        "consultation_id": consultation_id,
+        "status": ConsultationStatus.REVIEW.value,
+        "document": document.model_dump(mode="json"),
+    }

backend/audio.py

@@ -0,0 +1,85 @@
+"""Audio conversion and validation utilities for MedASR-ready WAV files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import librosa
+from pydub import AudioSegment
+
+from backend.errors import AudioError
+
+
+MIN_AUDIO_DURATION_S = 5.0
+MAX_AUDIO_DURATION_S = 1800.0
+EXPECTED_SAMPLE_RATE = 16000
+EXPECTED_CHANNELS = 1
+
+
+def convert_to_wav_16k(input_path: str, output_path: str) -> str:
+    """Convert supported audio input to 16kHz mono PCM WAV.
+
+    Args:
+        input_path (str): Source audio path (e.g. webm, mp3, wav).
+        output_path (str): Destination WAV path.
+
+    Returns:
+        str: Output path for converted 16kHz mono WAV file.
+    """
+    source_path = Path(input_path)
+    destination_path = Path(output_path)
+
+    if not source_path.exists():
+        raise AudioError(f"Audio input not found: {source_path}")
+
+    try:
+        audio = AudioSegment.from_file(source_path)
+    except Exception as exc:  # pragma: no cover - pydub/ffmpeg message is external
+        raise AudioError(f"Failed to decode audio file {source_path}: {exc}") from exc
+
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    processed = audio.set_frame_rate(EXPECTED_SAMPLE_RATE).set_channels(EXPECTED_CHANNELS).set_sample_width(2)
+
+    try:
+        processed.export(destination_path, format="wav")
+    except Exception as exc:  # pragma: no cover - pydub/ffmpeg message is external
+        raise AudioError(f"Failed to export WAV audio {destination_path}: {exc}") from exc
+
+    return str(destination_path)
+
+
+def validate_audio(file_path: str) -> dict[str, float | int]:
+    """Validate an audio file meets pipeline constraints.
+
+    Args:
+        file_path (str): Path to WAV file to inspect.
+
+    Returns:
+        dict[str, float | int]: duration_s, sample_rate, channels values.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise AudioError(f"Audio file not found: {path}")
+
+    try:
+        waveform, sample_rate = librosa.load(path, sr=None, mono=False)
+    except Exception as exc:
+        raise AudioError(f"Unable to load audio for validation: {path}: {exc}") from exc
+
+    channels = int(waveform.shape[0]) if getattr(waveform, "ndim", 1) > 1 else 1
+    duration_s = float(librosa.get_duration(y=waveform, sr=sample_rate))
+
+    if sample_rate != EXPECTED_SAMPLE_RATE:
+        raise AudioError(f"Invalid sample rate {sample_rate}; expected {EXPECTED_SAMPLE_RATE}")
+    if channels != EXPECTED_CHANNELS:
+        raise AudioError(f"Invalid channel count {channels}; expected {EXPECTED_CHANNELS}")
+    if duration_s <= MIN_AUDIO_DURATION_S:
+        raise AudioError(f"Audio duration {duration_s:.2f}s must be > {MIN_AUDIO_DURATION_S}s")
+    if duration_s >= MAX_AUDIO_DURATION_S:
+        raise AudioError(f"Audio duration {duration_s:.2f}s must be < {MAX_AUDIO_DURATION_S}s")
+
+    return {
+        "duration_s": duration_s,
+        "sample_rate": int(sample_rate),
+        "channels": channels,
+    }

backend/config.py

@@ -0,0 +1,66 @@
+"""Centralised application configuration loaded from environment variables."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from dotenv import load_dotenv
+from pydantic import ConfigDict
+from pydantic_settings import BaseSettings
+
+load_dotenv()
+
+
+class Settings(BaseSettings):
+    """Application settings schema loaded from environment variables.
+
+    Params:
+        None: Values are read from process environment and optional `.env` file.
+    Returns:
+        Settings: Parsed and validated settings object.
+    """
+
+    model_config = ConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    MEDASR_MODEL_ID: str = "google/medasr"
+    MEDGEMMA_4B_MODEL_ID: str = "google/medgemma-1.5-4b-it"
+    MEDGEMMA_27B_MODEL_ID: str = "google/medgemma-27b-text-it"
+    HF_TOKEN: str = ""
+    QUANTIZE_4BIT: bool = True
+    USE_FLASH_ATTENTION: bool = True
+
+    FHIR_SERVER_URL: str = "http://localhost:8080/fhir"
+    USE_MOCK_FHIR: bool = True
+    FHIR_TIMEOUT_S: int = 10
+
+    APP_HOST: str = "0.0.0.0"
+    APP_PORT: int = 7860
+    LOG_LEVEL: str = "INFO"
+    MAX_AUDIO_DURATION_S: int = 1800
+    PIPELINE_TIMEOUT_S: int = 120
+    DOC_GEN_MAX_TOKENS: int = 2048
+    DOC_GEN_TEMPERATURE: float = 0.3
+
+    WANDB_API_KEY: str = ""
+    WANDB_PROJECT: str = "clarke-finetuning"
+    LORA_RANK: int = 16
+    LORA_ALPHA: int = 32
+    LORA_DROPOUT: float = 0.05
+    TRAINING_EPOCHS: int = 3
+    LEARNING_RATE: float = 2e-4
+    BATCH_SIZE: int = 2
+    GRAD_ACCUM_STEPS: int = 8
+    MAX_SEQ_LENGTH: int = 4096
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return a cached settings instance for process-wide reuse.
+
+    Params:
+        None: Reads values from environment variables and `.env` if present.
+    Returns:
+        Settings: Cached configuration object.
+    """
+
+    return Settings()

backend/errors.py

@@ -0,0 +1,94 @@
+"""Error types and logging bootstrap for Clarke backend services."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loguru import logger
+
+
+class ClarkeError(Exception):
+    """Base exception for Clarke backend failures.
+
+    Params:
+        message (str): Human-readable error message.
+    Returns:
+        None: Raises an exception instance.
+    """
+
+
+class ConfigError(ClarkeError):
+    """Raised when configuration values are missing or invalid.
+
+    Params:
+        message (str): Human-readable error message.
+    Returns:
+        None: Raises an exception instance.
+    """
+
+
+class FHIRClientError(ClarkeError):
+    """Raised for FHIR retrieval and parsing failures.
+
+    Params:
+        message (str): Human-readable error message.
+    Returns:
+        None: Raises an exception instance.
+    """
+
+
+class ModelExecutionError(ClarkeError):
+    """Raised when model loading or inference fails.
+
+    Params:
+        message (str): Human-readable error message.
+    Returns:
+        None: Raises an exception instance.
+    """
+
+
+class AudioError(ClarkeError):
+    """Raised when audio input fails conversion or validation checks.
+
+    Params:
+        message (str): Human-readable error message.
+    Returns:
+        None: Raises an exception instance.
+    """
+
+
+def configure_logging(log_level: str = "DEBUG") -> None:
+    """Configure loguru sinks for console and rotating file logs.
+
+    Params:
+        log_level (str): Minimum enabled log severity level.
+    Returns:
+        None: Configures global logger side effects.
+    """
+
+    Path("logs").mkdir(parents=True, exist_ok=True)
+    logger.remove()
+    logger.add(
+        "logs/clarke_{time}.log",
+        format="{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<7} | {extra[component]:<15} | {message}",
+        rotation="50 MB",
+        retention="7 days",
+        level="DEBUG",
+    )
+    logger.add(
+        sink="stderr",
+        format="{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<7} | {extra[component]:<15} | {message}",
+        level=log_level,
+    )
+
+
+def get_component_logger(component: str):
+    """Return a logger bound to a component name for structured logs.
+
+    Params:
+        component (str): Logical module/component identifier.
+    Returns:
+        loguru.Logger: Bound logger with `component` context.
+    """
+
+    return logger.bind(component=component)

backend/fhir/__init__.py

@@ -0,0 +1 @@
+"""FHIR integration package for Clarke."""

backend/fhir/client.py

@@ -0,0 +1,194 @@
+"""Asynchronous FHIR REST client for retrieving patient-scoped resources."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from backend.config import get_settings
+from backend.errors import FHIRClientError, get_component_logger
+
+logger = get_component_logger("fhir_client")
+
+
+class FHIRClient:
+    """HTTP client for FHIR query patterns used by Clarke orchestration.
+
+    Args:
+        fhir_server_url (str): Base URL of FHIR API including `/fhir` path.
+        timeout_s (int): Request timeout in seconds.
+
+    Returns:
+        None: Initialises a client instance.
+    """
+
+    def __init__(self, fhir_server_url: str, timeout_s: int) -> None:
+        self.fhir_server_url = fhir_server_url.rstrip("/")
+        self.timeout_s = timeout_s
+
+    async def _request_json(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Execute a GET request with timeout, 404-empty behaviour, and one 5xx retry.
+
+        Args:
+            path (str): FHIR relative path beginning with `/`.
+            params (dict[str, Any] | None): Query parameters for the request.
+
+        Returns:
+            dict[str, Any]: Parsed JSON response, or empty dictionary for 404 responses.
+        """
+
+        url = f"{self.fhir_server_url}{path}"
+        attempts = 0
+        while attempts < 2:
+            attempts += 1
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout_s) as client:
+                    response = await client.get(url, params=params)
+            except httpx.TimeoutException as exc:
+                logger.error("FHIR request timed out", url=url, params=params, timeout_s=self.timeout_s)
+                raise FHIRClientError(
+                    f"FHIR timeout for {url} with params={params} after {self.timeout_s}s"
+                ) from exc
+            except httpx.HTTPError as exc:
+                logger.error("FHIR transport error", url=url, params=params, error=str(exc))
+                raise FHIRClientError(f"FHIR transport error for {url}: {exc}") from exc
+
+            if response.status_code == 404:
+                return {}
+
+            if response.status_code >= 500 and attempts < 2:
+                logger.warning("FHIR server 5xx, retrying once", url=url, status_code=response.status_code)
+                continue
+
+            if response.status_code >= 400:
+                raise FHIRClientError(
+                    f"FHIR request failed for {url} status={response.status_code} body={response.text}"
+                )
+
+            return response.json()
+
+        raise FHIRClientError(f"FHIR server error persisted after retry for {url}")
+
+    async def get_patient(self, patient_id: str) -> dict[str, Any]:
+        """Fetch a Patient resource by id.
+
+        Args:
+            patient_id (str): Patient identifier.
+
+        Returns:
+            dict[str, Any]: Patient JSON resource or empty dict when not found.
+        """
+
+        return await self._request_json(f"/Patient/{patient_id}")
+
+    async def search_patients(self, name: str, count: int = 10) -> dict[str, Any]:
+        """Search patients by name using FHIR Patient endpoint.
+
+        Args:
+            name (str): Name fragment to search.
+            count (int): Maximum number of records to request.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle search response.
+        """
+
+        return await self._request_json("/Patient", params={"name": name, "_count": count})
+
+    async def get_conditions(self, patient_id: str, clinical_status: str = "active") -> dict[str, Any]:
+        """Fetch Condition resources for a patient.
+
+        Args:
+            patient_id (str): Patient identifier.
+            clinical_status (str): Desired clinical status value.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle response.
+        """
+
+        return await self._request_json(
+            "/Condition", params={"patient": patient_id, "clinical-status": clinical_status}
+        )
+
+    async def get_medications(self, patient_id: str, status: str = "active") -> dict[str, Any]:
+        """Fetch MedicationRequest resources for a patient.
+
+        Args:
+            patient_id (str): Patient identifier.
+            status (str): Medication status filter.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle response.
+        """
+
+        return await self._request_json("/MedicationRequest", params={"patient": patient_id, "status": status})
+
+    async def get_observations(
+        self,
+        patient_id: str,
+        category: str = "laboratory",
+        sort: str = "-date",
+        count: int = 20,
+    ) -> dict[str, Any]:
+        """Fetch Observation resources for a patient.
+
+        Args:
+            patient_id (str): Patient identifier.
+            category (str): Observation category code filter.
+            sort (str): Sort directive for date-like fields.
+            count (int): Maximum number of records.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle response.
+        """
+
+        return await self._request_json(
+            "/Observation",
+            params={"patient": patient_id, "category": category, "_sort": sort, "_count": count},
+        )
+
+    async def get_allergies(self, patient_id: str) -> dict[str, Any]:
+        """Fetch AllergyIntolerance resources for a patient.
+
+        Args:
+            patient_id (str): Patient identifier.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle response.
+        """
+
+        return await self._request_json("/AllergyIntolerance", params={"patient": patient_id})
+
+    async def get_diagnostic_reports(self, patient_id: str, sort: str = "-date", count: int = 5) -> dict[str, Any]:
+        """Fetch DiagnosticReport resources for a patient.
+
+        Args:
+            patient_id (str): Patient identifier.
+            sort (str): Sort directive for date-like fields.
+            count (int): Maximum number of records.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle response.
+        """
+
+        return await self._request_json(
+            "/DiagnosticReport", params={"patient": patient_id, "_sort": sort, "_count": count}
+        )
+
+    async def get_recent_encounters(self, patient_id: str, sort: str = "-date", count: int = 3) -> dict[str, Any]:
+        """Fetch recent Encounter resources for a patient.
+
+        Args:
+            patient_id (str): Patient identifier.
+            sort (str): Sort directive for date-like fields.
+            count (int): Maximum number of records.
+
+        Returns:
+            dict[str, Any]: FHIR Bundle response.
+        """
+
+        return await self._request_json("/Encounter", params={"patient": patient_id, "_sort": sort, "_count": count})
+
+
+settings = get_settings()
+DEFAULT_FHIR_CLIENT = FHIRClient(fhir_server_url=settings.FHIR_SERVER_URL, timeout_s=settings.FHIR_TIMEOUT_S)

backend/fhir/mock_api.py

@@ -0,0 +1,412 @@
+"""Mock FHIR API server for local development and fallback deployments."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, Query
+from loguru import logger
+
+FHIR_BASE_URL = "http://localhost:8080/fhir"
+DEFAULT_BUNDLES_DIR = Path(__file__).resolve().parents[2] / "data" / "fhir_bundles"
+
+app = FastAPI(title="Clarke Mock FHIR API", version="1.0.0")
+
+
+class BundleIndex:
+    """In-memory index for patient bundles keyed by patient id and resource type."""
+
+    def __init__(self, bundles_dir: Path) -> None:
+        """Initialise and preload all FHIR bundles from disk.
+
+        Args:
+            bundles_dir (Path): Directory containing per-patient bundle JSON files.
+
+        Returns:
+            None: Instance state is populated in-place.
+        """
+        self.bundles_dir = bundles_dir
+        self.patient_resources: dict[str, dict[str, Any]] = {}
+        self.resources_by_type: dict[str, dict[str, list[dict[str, Any]]]] = {}
+        self._load_bundles()
+
+    def _load_bundles(self) -> None:
+        """Load all bundle files and build lookup indexes for API routes.
+
+        Args:
+            None: Uses instance `bundles_dir`.
+
+        Returns:
+            None: Internal index maps are rebuilt.
+        """
+        if not self.bundles_dir.exists():
+            logger.bind(component="mock_fhir_api").warning(
+                "Bundle directory does not exist", bundles_dir=str(self.bundles_dir)
+            )
+            return
+
+        for bundle_file in sorted(self.bundles_dir.glob("*.json")):
+            with bundle_file.open("r", encoding="utf-8") as file_handle:
+                bundle = json.load(file_handle)
+
+            for entry in bundle.get("entry", []):
+                resource = entry.get("resource", {})
+                resource_type = resource.get("resourceType")
+                if not resource_type:
+                    continue
+
+                patient_id = self._extract_patient_id(resource)
+                if not patient_id and resource_type == "Patient":
+                    patient_id = resource.get("id")
+
+                if not patient_id:
+                    continue
+
+                if resource_type == "Patient":
+                    self.patient_resources[patient_id] = resource
+
+                self.resources_by_type.setdefault(resource_type, {}).setdefault(patient_id, []).append(resource)
+
+        logger.bind(component="mock_fhir_api").info(
+            "Loaded mock FHIR bundles",
+            patients=len(self.patient_resources),
+            bundles_dir=str(self.bundles_dir),
+        )
+
+    @staticmethod
+    def _extract_patient_id(resource: dict[str, Any]) -> str | None:
+        """Extract patient identifier from common FHIR reference fields.
+
+        Args:
+            resource (dict[str, Any]): A FHIR resource object.
+
+        Returns:
+            str | None: Patient id (e.g. `pt-001`) when detectable, otherwise None.
+        """
+        reference_candidates = [
+            resource.get("subject", {}).get("reference"),
+            resource.get("patient", {}).get("reference"),
+        ]
+        for candidate in reference_candidates:
+            if candidate and isinstance(candidate, str) and candidate.startswith("Patient/"):
+                return candidate.split("/", maxsplit=1)[1]
+        return None
+
+    def get_patient(self, patient_id: str) -> dict[str, Any] | None:
+        """Return a single patient resource by id.
+
+        Args:
+            patient_id (str): Patient identifier.
+
+        Returns:
+            dict[str, Any] | None: Patient resource when present, else None.
+        """
+        return self.patient_resources.get(patient_id)
+
+    def get_resources(self, resource_type: str, patient_id: str) -> list[dict[str, Any]]:
+        """Return all indexed resources of a given type for a patient.
+
+        Args:
+            resource_type (str): FHIR resource type name.
+            patient_id (str): Patient identifier.
+
+        Returns:
+            list[dict[str, Any]]: Matching resources, empty list when none found.
+        """
+        return self.resources_by_type.get(resource_type, {}).get(patient_id, [])
+
+    def search_patients(self, name_term: str) -> list[dict[str, Any]]:
+        """Search patients by case-insensitive name matching across given/family/prefix.
+
+        Args:
+            name_term (str): Name fragment entered by caller.
+
+        Returns:
+            list[dict[str, Any]]: Matching patient resources.
+        """
+        lowered = name_term.lower().strip()
+        matches: list[dict[str, Any]] = []
+        for patient in self.patient_resources.values():
+            for name in patient.get("name", []):
+                tokens = []
+                tokens.extend(name.get("prefix", []))
+                tokens.extend(name.get("given", []))
+                if family := name.get("family"):
+                    tokens.append(family)
+                if any(lowered in str(token).lower() for token in tokens):
+                    matches.append(patient)
+                    break
+        return matches
+
+
+BUNDLE_INDEX = BundleIndex(Path(os.getenv("MOCK_FHIR_BUNDLES_DIR", str(DEFAULT_BUNDLES_DIR))))
+
+
+def build_search_bundle(resource_type: str, resources: list[dict[str, Any]]) -> dict[str, Any]:
+    """Build a FHIR searchset bundle payload from resource rows.
+
+    Args:
+        resource_type (str): Resource type represented in `resources`.
+        resources (list[dict[str, Any]]): FHIR resources to include.
+
+    Returns:
+        dict[str, Any]: FHIR Bundle with `entry` and `total` fields.
+    """
+    entries = [
+        {
+            "fullUrl": f"{FHIR_BASE_URL}/{resource_type}/{resource.get('id', '')}",
+            "resource": resource,
+        }
+        for resource in resources
+    ]
+    return {
+        "resourceType": "Bundle",
+        "type": "searchset",
+        "total": len(resources),
+        "entry": entries,
+    }
+
+
+def get_effective_sort_key(resource: dict[str, Any]) -> str:
+    """Resolve date-like sort key for FHIR resources supporting `_sort=-date`.
+
+    Args:
+        resource (dict[str, Any]): Resource candidate.
+
+    Returns:
+        str: Date-like string usable for lexicographic descending sort.
+    """
+    return (
+        resource.get("effectiveDateTime")
+        or resource.get("issued")
+        or resource.get("authoredOn")
+        or resource.get("onsetDateTime")
+        or resource.get("period", {}).get("start")
+        or ""
+    )
+
+
+def get_patient_or_404(patient_id: str) -> dict[str, Any]:
+    """Resolve patient resource or raise a 404 HTTP exception.
+
+    Args:
+        patient_id (str): Patient identifier to lookup.
+
+    Returns:
+        dict[str, Any]: Existing patient resource.
+    """
+    patient_resource = BUNDLE_INDEX.get_patient(patient_id)
+    if not patient_resource:
+        raise HTTPException(status_code=404, detail=f"Patient not found: {patient_id}")
+    return patient_resource
+
+
+@app.get("/fhir/Patient/{patient_id}")
+async def read_patient(patient_id: str) -> dict[str, Any]:
+    """Return a Patient resource by id.
+
+    Args:
+        patient_id (str): Patient identifier path parameter.
+
+    Returns:
+        dict[str, Any]: Patient resource payload.
+    """
+    return get_patient_or_404(patient_id)
+
+
+@app.get("/fhir/Patient")
+async def search_patient(name: str = Query(default=""), _count: int = Query(default=10, ge=1)) -> dict[str, Any]:
+    """Search patients by name and return a FHIR searchset bundle.
+
+    Args:
+        name (str): Name fragment for case-insensitive matching.
+        _count (int): Maximum result size.
+
+    Returns:
+        dict[str, Any]: Search bundle of Patient resources.
+    """
+    resources = BUNDLE_INDEX.search_patients(name) if name else list(BUNDLE_INDEX.patient_resources.values())
+    return build_search_bundle("Patient", resources[:_count])
+
+
+def list_patient_resources(resource_type: str, patient: str, limit: int, sort_desc_by_date: bool = False) -> dict[str, Any]:
+    """Fetch filtered patient resources and wrap them as a searchset bundle.
+
+    Args:
+        resource_type (str): FHIR resource type to return.
+        patient (str): Patient identifier.
+        limit (int): Maximum number of resources to include.
+        sort_desc_by_date (bool): Whether to sort descending by date-like fields.
+
+    Returns:
+        dict[str, Any]: Search bundle for the requested resource type.
+    """
+    get_patient_or_404(patient)
+    resources = list(BUNDLE_INDEX.get_resources(resource_type, patient))
+    if sort_desc_by_date:
+        resources.sort(key=get_effective_sort_key, reverse=True)
+    return build_search_bundle(resource_type, resources[:limit])
+
+
+@app.get("/fhir/Condition")
+async def list_conditions(
+    patient: str,
+    clinical_status: str | None = Query(default=None, alias="clinical-status"),
+    _count: int = Query(default=20, ge=1),
+) -> dict[str, Any]:
+    """List Condition resources for a patient with optional active-status filtering.
+
+    Args:
+        patient (str): Patient identifier query parameter.
+        clinical_status (str | None): Optional status filter (e.g. `active`).
+        _count (int): Maximum number of rows.
+
+    Returns:
+        dict[str, Any]: Condition search bundle.
+    """
+    bundle = list_patient_resources("Condition", patient, _count)
+    if clinical_status:
+        filtered_entries = [
+            item
+            for item in bundle["entry"]
+            if any(
+                coding.get("code") == clinical_status
+                for coding in item["resource"].get("clinicalStatus", {}).get("coding", [])
+            )
+        ]
+        bundle["entry"] = filtered_entries
+        bundle["total"] = len(filtered_entries)
+    return bundle
+
+
+@app.get("/fhir/MedicationRequest")
+async def list_medication_requests(
+    patient: str,
+    status: str | None = Query(default=None),
+    _count: int = Query(default=20, ge=1),
+) -> dict[str, Any]:
+    """List MedicationRequest resources for a patient with optional status filter.
+
+    Args:
+        patient (str): Patient identifier query parameter.
+        status (str | None): Optional medication status filter.
+        _count (int): Maximum number of rows.
+
+    Returns:
+        dict[str, Any]: MedicationRequest search bundle.
+    """
+    bundle = list_patient_resources("MedicationRequest", patient, _count, sort_desc_by_date=True)
+    if status:
+        filtered_entries = [item for item in bundle["entry"] if item["resource"].get("status") == status]
+        bundle["entry"] = filtered_entries
+        bundle["total"] = len(filtered_entries)
+    return bundle
+
+
+@app.get("/fhir/Observation")
+async def list_observations(
+    patient: str,
+    category: str | None = Query(default=None),
+    _sort: str | None = Query(default=None),
+    _count: int = Query(default=20, ge=1),
+) -> dict[str, Any]:
+    """List Observation resources for a patient with category/count/sort controls.
+
+    Args:
+        patient (str): Patient identifier query parameter.
+        category (str | None): Optional observation category code.
+        _sort (str | None): Optional sort string (`-date` expected).
+        _count (int): Maximum number of rows.
+
+    Returns:
+        dict[str, Any]: Observation search bundle.
+    """
+    sort_desc_by_date = _sort == "-date"
+    bundle = list_patient_resources("Observation", patient, _count, sort_desc_by_date=sort_desc_by_date)
+    if category:
+        filtered_entries = [
+            item
+            for item in bundle["entry"]
+            if any(
+                coding.get("code") == category
+                for block in item["resource"].get("category", [])
+                for coding in block.get("coding", [])
+            )
+        ]
+        bundle["entry"] = filtered_entries
+        bundle["total"] = len(filtered_entries)
+    return bundle
+
+
+@app.get("/fhir/AllergyIntolerance")
+async def list_allergies(patient: str, _count: int = Query(default=20, ge=1)) -> dict[str, Any]:
+    """List AllergyIntolerance resources for a patient.
+
+    Args:
+        patient (str): Patient identifier query parameter.
+        _count (int): Maximum number of rows.
+
+    Returns:
+        dict[str, Any]: AllergyIntolerance search bundle.
+    """
+    return list_patient_resources("AllergyIntolerance", patient, _count)
+
+
+@app.get("/fhir/DiagnosticReport")
+async def list_diagnostic_reports(
+    patient: str,
+    _sort: str | None = Query(default=None),
+    _count: int = Query(default=5, ge=1),
+) -> dict[str, Any]:
+    """List DiagnosticReport resources for a patient with optional date sorting.
+
+    Args:
+        patient (str): Patient identifier query parameter.
+        _sort (str | None): Optional sort string (`-date` expected).
+        _count (int): Maximum number of rows.
+
+    Returns:
+        dict[str, Any]: DiagnosticReport search bundle.
+    """
+    return list_patient_resources("DiagnosticReport", patient, _count, sort_desc_by_date=_sort == "-date")
+
+
+@app.get("/fhir/Encounter")
+async def list_encounters(
+    patient: str,
+    _sort: str | None = Query(default=None),
+    _count: int = Query(default=3, ge=1),
+) -> dict[str, Any]:
+    """List Encounter resources for a patient with optional date sorting.
+
+    Args:
+        patient (str): Patient identifier query parameter.
+        _sort (str | None): Optional sort string (`-date` expected).
+        _count (int): Maximum number of rows.
+
+    Returns:
+        dict[str, Any]: Encounter search bundle.
+    """
+    return list_patient_resources("Encounter", patient, _count, sort_desc_by_date=_sort == "-date")
+
+
+def main() -> None:
+    """Run the mock FHIR API server.
+
+    Args:
+        None: Reads host/port from environment variables.
+
+    Returns:
+        None: Starts uvicorn process.
+    """
+    host = os.getenv("MOCK_FHIR_HOST", "0.0.0.0")
+    port = int(os.getenv("MOCK_FHIR_PORT", "8080"))
+    uvicorn.run("backend.fhir.mock_api:app", host=host, port=port, reload=False)
+
+
+if __name__ == "__main__":
+    main()

backend/fhir/queries.py

@@ -0,0 +1,62 @@
+"""Deterministic FHIR query aggregation used as EHR fallback context retrieval."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from backend.fhir.client import DEFAULT_FHIR_CLIENT
+from backend.fhir.tools import (
+    get_allergies,
+    get_conditions,
+    get_diagnostic_reports,
+    get_medications,
+    get_observations,
+    get_recent_encounters,
+    search_patients,
+)
+
+
+async def get_full_patient_context(patient_id: str) -> dict[str, Any]:
+    """Aggregate all FHIR tool outputs for deterministic patient context assembly.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        dict[str, Any]: Aggregated context containing all seven tool result sections.
+    """
+
+    (
+        patients,
+        conditions,
+        medications,
+        observations,
+        allergies,
+        diagnostic_reports,
+        encounters,
+    ) = await asyncio.gather(
+        search_patients(patient_id),
+        get_conditions(patient_id),
+        get_medications(patient_id),
+        get_observations(patient_id),
+        get_allergies(patient_id),
+        get_diagnostic_reports(patient_id),
+        get_recent_encounters(patient_id),
+    )
+
+    if not patients:
+        patient_resource = await DEFAULT_FHIR_CLIENT.get_patient(patient_id)
+        if patient_resource:
+            patients = [patient_resource]
+
+    return {
+        "patient_id": patient_id,
+        "patients": patients,
+        "conditions": conditions,
+        "medications": medications,
+        "observations": observations,
+        "allergies": allergies,
+        "diagnostic_reports": diagnostic_reports,
+        "encounters": encounters,
+    }

backend/fhir/tools.py

@@ -0,0 +1,120 @@
+"""FHIR tool-call wrappers that extract resources from bundle responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from backend.fhir.client import DEFAULT_FHIR_CLIENT
+
+
+def _bundle_entries(bundle: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract resource rows from a FHIR Bundle payload.
+
+    Args:
+        bundle (dict[str, Any]): Raw FHIR Bundle response.
+
+    Returns:
+        list[dict[str, Any]]: Resource dictionaries found in bundle entries.
+    """
+
+    entries = bundle.get("entry", []) if isinstance(bundle, dict) else []
+    return [item.get("resource", {}) for item in entries if isinstance(item, dict) and isinstance(item.get("resource"), dict)]
+
+
+async def search_patients(name: str) -> list[dict[str, Any]]:
+    """Search patient resources by name.
+
+    Args:
+        name (str): Name term for patient search.
+
+    Returns:
+        list[dict[str, Any]]: Matching Patient resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.search_patients(name=name)
+    return _bundle_entries(response)
+
+
+async def get_conditions(patient_id: str) -> list[dict[str, Any]]:
+    """Return active condition resources for a patient.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        list[dict[str, Any]]: Condition resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.get_conditions(patient_id=patient_id)
+    return _bundle_entries(response)
+
+
+async def get_medications(patient_id: str) -> list[dict[str, Any]]:
+    """Return active medication request resources for a patient.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        list[dict[str, Any]]: MedicationRequest resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.get_medications(patient_id=patient_id)
+    return _bundle_entries(response)
+
+
+async def get_observations(patient_id: str, category: str = "laboratory") -> list[dict[str, Any]]:
+    """Return observation resources for a patient and category.
+
+    Args:
+        patient_id (str): Patient identifier.
+        category (str): Observation category code.
+
+    Returns:
+        list[dict[str, Any]]: Observation resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.get_observations(patient_id=patient_id, category=category)
+    return _bundle_entries(response)
+
+
+async def get_allergies(patient_id: str) -> list[dict[str, Any]]:
+    """Return allergy resources for a patient.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        list[dict[str, Any]]: AllergyIntolerance resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.get_allergies(patient_id=patient_id)
+    return _bundle_entries(response)
+
+
+async def get_diagnostic_reports(patient_id: str) -> list[dict[str, Any]]:
+    """Return diagnostic report resources for a patient.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        list[dict[str, Any]]: DiagnosticReport resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.get_diagnostic_reports(patient_id=patient_id)
+    return _bundle_entries(response)
+
+
+async def get_recent_encounters(patient_id: str) -> list[dict[str, Any]]:
+    """Return recent encounter resources for a patient.
+
+    Args:
+        patient_id (str): Patient identifier.
+
+    Returns:
+        list[dict[str, Any]]: Encounter resources.
+    """
+
+    response = await DEFAULT_FHIR_CLIENT.get_recent_encounters(patient_id=patient_id)
+    return _bundle_entries(response)

backend/models/__init__.py

@@ -0,0 +1 @@
+"""Model wrappers for Clarke backend pipelines."""

backend/models/doc_generator.py

@@ -0,0 +1,342 @@
+"""MedGemma 27B document generation wrapper with prompt rendering and section parsing."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader
+
+try:
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+except ModuleNotFoundError:  # pragma: no cover - mock mode support
+    torch = None
+    AutoModelForCausalLM = None
+    AutoTokenizer = None
+    BitsAndBytesConfig = None
+
+from backend.config import get_settings
+from backend.errors import ModelExecutionError, get_component_logger
+from backend.schemas import ClinicalDocument, ConsultationStatus, DocumentSection, PatientContext
+
+logger = get_component_logger("doc_generator")
+
+PROMPTS_DIR = Path("backend/prompts")
+KNOWN_SECTION_HEADINGS = [
+    "History of presenting complaint",
+    "Examination findings",
+    "Investigation results",
+    "Assessment and plan",
+    "Current medications",
+]
+
+
+class DocumentGenerator:
+    """Generate NHS clinic letters from transcript + patient context using MedGemma 27B.
+
+    Args:
+        model_id (str | None): Optional model identifier override.
+
+    Returns:
+        None: Initialises lazy model/tokenizer handles and runtime settings.
+    """
+
+    def __init__(self, model_id: str | None = None) -> None:
+        """Initialise document generator model wrapper state.
+
+        Args:
+            model_id (str | None): Optional model identifier override.
+
+        Returns:
+            None: Stores settings and lazy-loaded model state.
+        """
+
+        self.settings = get_settings()
+        self.model_id = model_id or self.settings.MEDGEMMA_27B_MODEL_ID
+        self._tokenizer: Any | None = None
+        self._model: Any | None = None
+        self.is_mock_mode = self.model_id.lower() == "mock"
+
+    def load_model(self) -> None:
+        """Load MedGemma 27B tokenizer and model in 4-bit quantised mode.
+
+        Args:
+            None: Reads class configuration and settings values.
+
+        Returns:
+            None: Populates model/tokenizer attributes or mock sentinel state.
+        """
+
+        if self.is_mock_mode:
+            logger.info("Document generator initialised in mock mode")
+            self._tokenizer = "mock"
+            self._model = "mock"
+            return
+        if self._model is not None and self._tokenizer is not None:
+            return
+
+        if AutoModelForCausalLM is None or AutoTokenizer is None or BitsAndBytesConfig is None or torch is None:
+            raise ModelExecutionError("transformers and torch are required for non-mock document generation")
+
+        try:
+            bnb_config = BitsAndBytesConfig(
+                load_in_4bit=True,
+                bnb_4bit_quant_type="nf4",
+                bnb_4bit_compute_dtype=torch.bfloat16,
+                bnb_4bit_use_double_quant=True,
+            )
+            self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+            self._model = AutoModelForCausalLM.from_pretrained(
+                self.model_id,
+                quantization_config=bnb_config,
+                device_map="auto",
+                torch_dtype=torch.bfloat16,
+            )
+            logger.info("Loaded MedGemma document model", model_id=self.model_id)
+        except Exception as exc:
+            raise ModelExecutionError(f"Failed to load MedGemma 27B model: {exc}") from exc
+
+    def generate(self, prompt: str, max_new_tokens: int | None = None) -> str:
+        """Generate raw letter text from a rendered prompt.
+
+        Args:
+            prompt (str): Fully rendered prompt string.
+            max_new_tokens (int | None): Optional generation token cap override.
+
+        Returns:
+            str: Raw decoded generated text output from the model.
+        """
+
+        if self._model is None or self._tokenizer is None:
+            self.load_model()
+
+        if self.is_mock_mode:
+            return self._mock_reference_letter()
+
+        generation_max_tokens = max_new_tokens or self.settings.DOC_GEN_MAX_TOKENS
+        try:
+            inputs = self._tokenizer(prompt, return_tensors="pt")
+            if hasattr(self._model, "device"):
+                inputs = {key: value.to(self._model.device) for key, value in inputs.items()}
+            output_tokens = self._model.generate(
+                **inputs,
+                max_new_tokens=generation_max_tokens,
+                temperature=0.3,
+                top_p=0.9,
+                top_k=40,
+                do_sample=True,
+                repetition_penalty=1.1,
+            )
+        except Exception as exc:
+            raise ModelExecutionError(f"MedGemma 27B inference failed: {exc}") from exc
+
+        decoded_output = self._tokenizer.decode(output_tokens[0], skip_special_tokens=True)
+        return self._strip_prompt_prefix(decoded_output, prompt)
+
+    def generate_document(
+        self,
+        transcript: str,
+        context: PatientContext,
+        max_new_tokens: int | None = None,
+    ) -> ClinicalDocument:
+        """Render prompt, generate text with retry policy, and build ClinicalDocument.
+
+        Args:
+            transcript (str): Consultation transcript text.
+            context (PatientContext): Structured patient context payload.
+            max_new_tokens (int | None): Optional generation token limit override.
+
+        Returns:
+            ClinicalDocument: Parsed clinical letter representation with section objects.
+        """
+
+        prompt = self._render_prompt(transcript, context)
+        generation_start = time.perf_counter()
+
+        last_error: Exception | None = None
+        first_limit = max_new_tokens or 2048
+        retry_limit = max(256, first_limit // 2)
+        for attempt, token_limit in enumerate((first_limit, retry_limit), start=1):
+            try:
+                generated_text = self.generate(prompt, max_new_tokens=token_limit)
+                sections = self._parse_sections(generated_text)
+                if len(sections) < 4:
+                    raise ValueError("Generated output did not contain enough parseable sections")
+                generation_time_s = round(time.perf_counter() - generation_start, 3)
+                return self._build_document(context, sections, generation_time_s)
+            except Exception as exc:  # noqa: BLE001
+                last_error = exc
+                logger.warning("Document generation attempt failed", attempt=attempt, error=str(exc))
+
+        raise ModelExecutionError(f"Document generation failed after retry: {last_error}")
+
+    def _render_prompt(self, transcript: str, context: PatientContext) -> str:
+        """Render the document generation Jinja2 template with consultation inputs.
+
+        Args:
+            transcript (str): Consultation transcript text.
+            context (PatientContext): Structured patient context data.
+
+        Returns:
+            str: Rendered prompt string supplied to the language model.
+        """
+
+        env = Environment(loader=FileSystemLoader(PROMPTS_DIR))
+        template = env.get_template("document_generation.j2")
+        context_json = json.dumps(context.model_dump(mode="json"), ensure_ascii=False, indent=2)
+        return template.render(
+            letter_date=datetime.now(tz=timezone.utc).strftime("%d %b %Y"),
+            clinician_name="Dr. Sarah Chen",
+            clinician_title="Consultant Diabetologist",
+            transcript=transcript,
+            context_json=context_json,
+        )
+
+    @staticmethod
+    def _parse_sections(generated_text: str) -> list[DocumentSection]:
+        """Parse generated letter text into section objects using heading detection rules.
+
+        Args:
+            generated_text (str): Raw generated letter text.
+
+        Returns:
+            list[DocumentSection]: Ordered parsed sections with heading and content fields.
+        """
+
+        section_pattern = re.compile(
+            r"^(?:\*\*|##\s*)?(History of presenting complaint|Examination findings|Investigation results|Assessment and plan|Current medications)[:\*\s]*$",
+            flags=re.IGNORECASE,
+        )
+        sections: list[DocumentSection] = []
+        current_heading: str | None = None
+        current_lines: list[str] = []
+
+        for raw_line in generated_text.splitlines():
+            line = raw_line.strip()
+            heading_match = section_pattern.match(line)
+            if heading_match:
+                if current_heading and current_lines:
+                    sections.append(
+                        DocumentSection(
+                            heading=current_heading,
+                            content="\n".join(current_lines).strip(),
+                            editable=True,
+                            fhir_sources=[],
+                        )
+                    )
+                current_heading = heading_match.group(1).strip().title()
+                current_lines = []
+                continue
+
+            if current_heading and line:
+                current_lines.append(line)
+
+        if current_heading and current_lines:
+            sections.append(
+                DocumentSection(
+                    heading=current_heading,
+                    content="\n".join(current_lines).strip(),
+                    editable=True,
+                    fhir_sources=[],
+                )
+            )
+
+        if not sections:
+            sections = [
+                DocumentSection(
+                    heading=heading,
+                    content="Content unavailable in generated output.",
+                    editable=True,
+                    fhir_sources=[],
+                )
+                for heading in KNOWN_SECTION_HEADINGS
+            ]
+        return sections
+
+    @staticmethod
+    def _build_document(
+        context: PatientContext,
+        sections: list[DocumentSection],
+        generation_time_s: float,
+    ) -> ClinicalDocument:
+        """Construct ClinicalDocument schema object from parsed generation outputs.
+
+        Args:
+            context (PatientContext): Structured patient context data.
+            sections (list[DocumentSection]): Parsed generated document sections.
+            generation_time_s (float): Generation wall-clock duration in seconds.
+
+        Returns:
+            ClinicalDocument: Final structured letter ready for API response.
+        """
+
+        demographics = context.demographics
+        patient_name = str(demographics.get("name", "Unknown patient"))
+        patient_dob = str(demographics.get("dob", ""))
+        nhs_number = str(demographics.get("nhs_number", ""))
+        medications_list = [med.get("name", "") for med in context.medications if med.get("name")]
+
+        return ClinicalDocument(
+            consultation_id=context.patient_id,
+            letter_date=datetime.now(tz=timezone.utc).strftime("%Y-%m-%d"),
+            patient_name=patient_name,
+            patient_dob=patient_dob,
+            nhs_number=nhs_number,
+            addressee="GP Practice",
+            salutation="Dear Dr.,",
+            sections=sections,
+            medications_list=medications_list,
+            sign_off="Dr. Sarah Chen, Consultant Diabetologist",
+            status=ConsultationStatus.REVIEW,
+            generated_at=datetime.now(tz=timezone.utc).isoformat(),
+            generation_time_s=generation_time_s,
+            discrepancies=[],
+        )
+
+    @staticmethod
+    def _strip_prompt_prefix(decoded_output: str, prompt: str) -> str:
+        """Remove prompt text prefix when decoder echoes the full prompt + completion.
+
+        Args:
+            decoded_output (str): Tokenizer-decoded text from model output ids.
+            prompt (str): Original model prompt string.
+
+        Returns:
+            str: Completion-only output when prompt prefix is present.
+        """
+
+        if decoded_output.startswith(prompt):
+            return decoded_output[len(prompt) :].strip()
+        return decoded_output.strip()
+
+    @staticmethod
+    def _mock_reference_letter() -> str:
+        """Return deterministic reference letter text for mock mode generation.
+
+        Args:
+            None: Uses embedded fixture text.
+
+        Returns:
+            str: Structured letter text with known section headings.
+        """
+
+        return (
+            "History of presenting complaint\n"
+            "Mrs Thompson reported worsening fatigue and reduced exercise tolerance over the last three months. "
+            "She confirmed she is taking metformin and gliclazide but occasionally misses evening doses.\n\n"
+            "Examination findings\n"
+            "No acute distress was described during the consultation. She denied chest pain, syncope, or focal neurological symptoms.\n\n"
+            "Investigation results\n"
+            "Recent blood results showed HbA1c 55 mmol/mol with eGFR 52 mL/min/1.73m². "
+            "Penicillin allergy with previous anaphylaxis was reconfirmed.\n\n"
+            "Assessment and plan\n"
+            "Overall picture is suboptimal glycaemic control with associated fatigue. Plan is lifestyle reinforcement, medicine adherence review, "
+            "repeat renal profile in 3 months, and consideration of treatment escalation if HbA1c remains above target.\n\n"
+            "Current medications\n"
+            "Metformin 1 g twice daily; Gliclazide 80 mg twice daily."
+        )

backend/models/ehr_agent.py

@@ -0,0 +1,459 @@
+"""EHR Agent module for deterministic FHIR retrieval and MedGemma 4B summarisation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from datetime import date, datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Template
+from pydantic import ValidationError
+
+try:
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+except ModuleNotFoundError:  # pragma: no cover - mock mode support
+    torch = None
+    AutoModelForCausalLM = None
+    AutoTokenizer = None
+    BitsAndBytesConfig = None
+
+from backend.config import get_settings
+from backend.errors import ModelExecutionError, get_component_logger
+from backend.fhir.queries import get_full_patient_context
+from backend.schemas import LabResult, PatientContext
+
+logger = get_component_logger("ehr_agent")
+
+
+DEFAULT_CONTEXT_PROMPT = """You are a clinical EHR synthesis agent.
+Given the raw FHIR payload below, output only valid JSON for this schema:
+{
+  \"patient_id\": \"...\",
+  \"demographics\": {...},
+  \"problem_list\": [\"...\"],
+  \"medications\": [{...}],
+  \"allergies\": [{...}],
+  \"recent_labs\": [{...}],
+  \"recent_imaging\": [{...}],
+  \"clinical_flags\": [\"...\"],
+  \"last_letter_excerpt\": null,
+  \"retrieval_warnings\": [],
+  \"retrieved_at\": \"...\"
+}
+
+Raw FHIR context JSON:
+{{ raw_context_json }}
+"""
+
+
+def parse_agent_output(raw_output: str) -> dict[str, Any]:
+    """Extract first JSON object from MedGemma output after stripping prompt leaks.
+
+    Args:
+        raw_output (str): Raw model generation text that may contain extra formatting.
+
+    Returns:
+        dict[str, Any]: Parsed JSON object extracted from model output.
+    """
+
+    cleaned_output = re.sub(r"<\|system\|>.*?<\|end\|>", "", raw_output, flags=re.DOTALL)
+    cleaned_output = re.sub(r"```json\s*", "", cleaned_output)
+    cleaned_output = re.sub(r"```\s*", "", cleaned_output)
+    match = re.search(r"\{[\s\S]*\}", cleaned_output)
+    if match:
+        return json.loads(match.group())
+    raise ValueError("No valid JSON found in agent output")
+
+
+class EHRAgent:
+    """Retrieve raw FHIR context and synthesise a validated PatientContext object.
+
+    Args:
+        model_id (str | None): Optional override for MedGemma 4B model ID.
+
+    Returns:
+        None: Creates an agent instance with lazy model loading.
+    """
+
+    def __init__(self, model_id: str | None = None) -> None:
+        settings = get_settings()
+        self.model_id = model_id or settings.MEDGEMMA_4B_MODEL_ID
+        self.timeout_s = settings.FHIR_TIMEOUT_S
+        self._model: Any | None = None
+        self._tokenizer: Any | None = None
+        self.is_mock_mode = self.model_id.lower() == "mock"
+
+    def load_model(self) -> None:
+        """Load the MedGemma 4B model/tokenizer in 4-bit mode unless running in mock mode.
+
+        Args:
+            None: Uses configured model ID and quantisation settings.
+
+        Returns:
+            None: Populates tokenizer/model attributes for inference.
+        """
+
+        if self.is_mock_mode:
+            logger.info("EHR agent initialised in mock mode")
+            return
+        if self._model is not None and self._tokenizer is not None:
+            return
+
+        if AutoModelForCausalLM is None or AutoTokenizer is None or BitsAndBytesConfig is None or torch is None:
+            raise ModelExecutionError("transformers and torch are required for non-mock EHR mode")
+
+        try:
+            bnb_config = BitsAndBytesConfig(
+                load_in_4bit=True,
+                bnb_4bit_quant_type="nf4",
+                bnb_4bit_compute_dtype=torch.bfloat16,
+                bnb_4bit_use_double_quant=True,
+            )
+            self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+            self._model = AutoModelForCausalLM.from_pretrained(
+                self.model_id,
+                quantization_config=bnb_config,
+                device_map="auto",
+                torch_dtype=torch.bfloat16,
+            )
+            logger.info("Loaded EHR agent model", model_id=self.model_id)
+        except Exception as exc:
+            raise ModelExecutionError(f"Failed to load MedGemma EHR model: {exc}") from exc
+
+    def get_patient_context(self, patient_id: str) -> PatientContext:
+        """Return structured patient context using deterministic FHIR retrieval with robust fallback.
+
+        Args:
+            patient_id (str): Patient identifier used across FHIR resources.
+
+        Returns:
+            PatientContext: Validated patient context instance for downstream pipeline use.
+        """
+
+        raw_context = asyncio.run(get_full_patient_context(patient_id))
+
+        if self.is_mock_mode:
+            return self._build_context_from_raw(raw_context)
+
+        self.load_model()
+        for attempt in range(1, 3):
+            try:
+                summarised_context = self._summarise_with_model(raw_context)
+                return PatientContext.model_validate(summarised_context)
+            except (ValidationError, ValueError, ModelExecutionError, json.JSONDecodeError) as exc:
+                logger.warning(
+                    "EHR model summarisation failed; retrying or falling back",
+                    patient_id=patient_id,
+                    attempt=attempt,
+                    error=str(exc),
+                )
+
+        fallback_context = self._build_context_from_raw(raw_context)
+        fallback_context.retrieval_warnings.append(
+            "MedGemma summarisation unavailable; context built via deterministic extraction."
+        )
+        return fallback_context
+
+    def _summarise_with_model(self, raw_context: dict[str, Any]) -> dict[str, Any]:
+        """Run MedGemma generation and parse into a dictionary payload.
+
+        Args:
+            raw_context (dict[str, Any]): Deterministic FHIR aggregation from tool queries.
+
+        Returns:
+            dict[str, Any]: Parsed context dictionary extracted from model output JSON.
+        """
+
+        if self._model is None or self._tokenizer is None:
+            raise ModelExecutionError("Model and tokenizer must be loaded before inference")
+
+        prompt = self._render_context_prompt(raw_context)
+        inputs = self._tokenizer(prompt, return_tensors="pt")
+        if hasattr(self._model, "device"):
+            inputs = {key: value.to(self._model.device) for key, value in inputs.items()}
+
+        try:
+            output_tokens = self._model.generate(
+                **inputs,
+                max_new_tokens=1024,
+                do_sample=True,
+                temperature=0.2,
+                top_p=0.9,
+                repetition_penalty=1.1,
+            )
+        except Exception as exc:
+            raise ModelExecutionError(f"MedGemma EHR generation failed: {exc}") from exc
+
+        raw_output = self._tokenizer.decode(output_tokens[0], skip_special_tokens=True)
+        return parse_agent_output(raw_output)
+
+    def _render_context_prompt(self, raw_context: dict[str, Any]) -> str:
+        """Render context synthesis prompt from Jinja template or built-in fallback template.
+
+        Args:
+            raw_context (dict[str, Any]): Deterministic FHIR context dictionary.
+
+        Returns:
+            str: Prompt text for MedGemma summarisation.
+        """
+
+        prompt_template_path = Path("backend/prompts/context_synthesis.j2")
+        if prompt_template_path.exists():
+            template_text = prompt_template_path.read_text(encoding="utf-8")
+        else:
+            template_text = DEFAULT_CONTEXT_PROMPT
+
+        template = Template(template_text)
+        return template.render(raw_context_json=json.dumps(raw_context, ensure_ascii=False, indent=2))
+
+    def _build_context_from_raw(self, raw_context: dict[str, Any]) -> PatientContext:
+        """Construct PatientContext directly from raw FHIR resources as deterministic fallback.
+
+        Args:
+            raw_context (dict[str, Any]): Deterministic FHIR context dictionary.
+
+        Returns:
+            PatientContext: Fully structured context generated without model summarisation.
+        """
+
+        patient = raw_context.get("patients", [{}])[0] if raw_context.get("patients") else {}
+        demographics = self._extract_demographics(patient)
+        problem_list = self._extract_problem_list(raw_context.get("conditions", []))
+        medications = self._extract_medications(raw_context.get("medications", []))
+        allergies = self._extract_allergies(raw_context.get("allergies", []))
+        recent_labs = self._extract_labs(raw_context.get("observations", []))
+        recent_imaging = self._extract_imaging(raw_context.get("diagnostic_reports", []))
+
+        clinical_flags: list[str] = []
+        hba1c_values = [lab for lab in recent_labs if lab.name.lower() == "hba1c"]
+        if len(hba1c_values) >= 2:
+            latest = float(hba1c_values[0].value)
+            previous = float(hba1c_values[1].value)
+            if latest > previous:
+                clinical_flags.append(f"HbA1c rising trend ({hba1c_values[1].value} → {hba1c_values[0].value})")
+
+        return PatientContext(
+            patient_id=str(raw_context.get("patient_id", "")),
+            demographics=demographics,
+            problem_list=problem_list,
+            medications=medications,
+            allergies=allergies,
+            recent_labs=recent_labs,
+            recent_imaging=recent_imaging,
+            clinical_flags=clinical_flags,
+            last_letter_excerpt=None,
+            retrieval_warnings=[],
+            retrieved_at=datetime.now(tz=timezone.utc).isoformat(),
+        )
+
+    @staticmethod
+    def _extract_demographics(patient: dict[str, Any]) -> dict[str, Any]:
+        """Extract demographics map from FHIR Patient resource.
+
+        Args:
+            patient (dict[str, Any]): FHIR Patient resource dictionary.
+
+        Returns:
+            dict[str, Any]: Simplified demographics payload.
+        """
+
+        names = patient.get("name", [])
+        first_name = names[0] if names else {}
+        full_name_parts = first_name.get("prefix", []) + first_name.get("given", []) + [first_name.get("family", "")]
+        full_name = " ".join(part for part in full_name_parts if part).strip()
+
+        nhs_number = ""
+        for identifier in patient.get("identifier", []):
+            if "nhs" in str(identifier.get("system", "")).lower() or identifier.get("value"):
+                nhs_number = str(identifier.get("value", ""))
+                if nhs_number:
+                    break
+
+        birth_date_value = patient.get("birthDate", "")
+        birth_date_raw = str(birth_date_value).strip() if birth_date_value is not None else ""
+        dob_display = birth_date_raw
+        age: int | None = None
+        if birth_date_raw and birth_date_raw != 'None':
+            try:
+                parsed_dob = date.fromisoformat(birth_date_raw)
+                dob_display = parsed_dob.strftime("%d/%m/%Y")
+                today = date.today()
+                age = today.year - parsed_dob.year - ((today.month, today.day) < (parsed_dob.month, parsed_dob.day))
+            except ValueError:
+                dob_display = birth_date_raw
+
+        nhs_clean = "".join(ch for ch in nhs_number if ch.isdigit())
+        if len(nhs_clean) == 10:
+            nhs_number = f"{nhs_clean[:3]}-{nhs_clean[3:6]}-{nhs_clean[6:]}"
+
+        return {
+            "name": full_name,
+            "dob": dob_display,
+            "nhs_number": nhs_number,
+            "age": age,
+            "sex": str(patient.get("gender", "")).capitalize(),
+            "address": "",
+        }
+
+    @staticmethod
+    def _extract_problem_list(conditions: list[dict[str, Any]]) -> list[str]:
+        """Extract active problem list from FHIR Condition resources.
+
+        Args:
+            conditions (list[dict[str, Any]]): List of FHIR Condition resources.
+
+        Returns:
+            list[str]: Human-readable problem entries.
+        """
+
+        problems: list[str] = []
+        for condition in conditions:
+            status_codes = condition.get("clinicalStatus", {}).get("coding", [])
+            is_active = any(code.get("code") == "active" for code in status_codes) if status_codes else True
+            label = str(condition.get("code", {}).get("text", "")).strip()
+            if is_active and label:
+                problems.append(label)
+        return problems
+
+    @staticmethod
+    def _extract_medications(medications: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Extract simplified medication entries from MedicationRequest resources.
+
+        Args:
+            medications (list[dict[str, Any]]): List of FHIR MedicationRequest resources.
+
+        Returns:
+            list[dict[str, Any]]: Medication records with source IDs.
+        """
+
+        extracted: list[dict[str, Any]] = []
+        for medication in medications:
+            dosage_text = ""
+            dosage_instructions = medication.get("dosageInstruction", [])
+            if dosage_instructions:
+                dosage_text = str(dosage_instructions[0].get("text", "")).strip()
+
+            dose = ""
+            frequency = ""
+            if dosage_text:
+                parts = dosage_text.rsplit(" ", maxsplit=1)
+                if len(parts) == 2:
+                    dose, frequency = parts[0], parts[1]
+                else:
+                    dose = dosage_text
+
+            extracted.append(
+                {
+                    "name": str(medication.get("medicationCodeableConcept", {}).get("text", "")).strip(),
+                    "dose": dose,
+                    "frequency": frequency,
+                    "fhir_id": str(medication.get("id", "")),
+                }
+            )
+        return extracted
+
+    @staticmethod
+    def _extract_allergies(allergies: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Extract allergy summary records from AllergyIntolerance resources.
+
+        Args:
+            allergies (list[dict[str, Any]]): List of FHIR AllergyIntolerance resources.
+
+        Returns:
+            list[dict[str, Any]]: Simplified allergy entries.
+        """
+
+        extracted: list[dict[str, Any]] = []
+        for allergy in allergies:
+            reaction = ""
+            reactions = allergy.get("reaction", [])
+            if reactions:
+                manifestations = reactions[0].get("manifestation", [])
+                if manifestations:
+                    reaction = str(manifestations[0].get("text", ""))
+            extracted.append(
+                {
+                    "substance": str(allergy.get("code", {}).get("text", "")).strip(),
+                    "reaction": reaction,
+                    "severity": str(allergy.get("criticality", "")).strip() or "unknown",
+                }
+            )
+        return extracted
+
+    @staticmethod
+    def _extract_labs(observations: list[dict[str, Any]]) -> list[LabResult]:
+        """Extract laboratory results from Observation resources with simple trend linkage.
+
+        Args:
+            observations (list[dict[str, Any]]): List of FHIR Observation resources.
+
+        Returns:
+            list[LabResult]: Structured laboratory results sorted by effective date.
+        """
+
+        labs: list[LabResult] = []
+        sorted_observations = sorted(
+            observations,
+            key=lambda obs: str(obs.get("effectiveDateTime", "")),
+            reverse=True,
+        )
+        previous_by_name: dict[str, LabResult] = {}
+
+        for observation in sorted_observations:
+            quantity = observation.get("valueQuantity", {})
+            name = str(observation.get("code", {}).get("text", "")).strip()
+            value = str(quantity.get("value", ""))
+            unit = str(quantity.get("unit", ""))
+            date = str(observation.get("effectiveDateTime", ""))
+            lab = LabResult(
+                name=name,
+                value=value,
+                unit=unit,
+                date=date,
+                fhir_resource_id=str(observation.get("id", "")),
+            )
+            if name in previous_by_name:
+                previous = previous_by_name[name]
+                lab.previous_value = previous.value
+                lab.previous_date = previous.date
+                try:
+                    current_val = float(lab.value)
+                    previous_val = float(previous.value)
+                    if current_val > previous_val:
+                        lab.trend = "rising"
+                    elif current_val < previous_val:
+                        lab.trend = "falling"
+                    else:
+                        lab.trend = "stable"
+                except (TypeError, ValueError):
+                    lab.trend = None
+            previous_by_name[name] = lab
+            labs.append(lab)
+
+        return labs
+
+    @staticmethod
+    def _extract_imaging(reports: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Extract concise imaging/report summaries from DiagnosticReport resources.
+
+        Args:
+            reports (list[dict[str, Any]]): List of FHIR DiagnosticReport resources.
+
+        Returns:
+            list[dict[str, Any]]: Recent report summary entries.
+        """
+
+        extracted: list[dict[str, Any]] = []
+        for report in reports:
+            extracted.append(
+                {
+                    "type": str(report.get("code", {}).get("text", "Diagnostic report")),
+                    "date": str(report.get("effectiveDateTime", "")),
+                    "summary": str(report.get("conclusion", "")).strip(),
+                }
+            )
+        return extracted

backend/models/medasr.py

@@ -0,0 +1,180 @@
+"""MedASR model wrapper with mock-mode fallback transcription."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import librosa
+try:
+    from transformers import pipeline
+except ModuleNotFoundError:  # pragma: no cover - mock mode support
+    pipeline = None
+
+from backend.config import get_settings
+from backend.errors import ModelExecutionError
+from backend.models.model_manager import ModelManager
+from backend.schemas import Transcript
+
+
+class MedASRModel:
+    """Load and run MedASR speech recognition or a deterministic mock implementation.
+
+    Args:
+        model_manager (ModelManager | None): Optional shared model registry manager.
+
+    Returns:
+        None: Initialised model wrapper with lazy-loaded pipeline.
+    """
+
+    def __init__(self, model_manager: ModelManager | None = None) -> None:
+        """Initialise MedASR wrapper.
+
+        Args:
+            model_manager (ModelManager | None): Optional model manager instance.
+
+        Returns:
+            None: Sets internal settings and model state.
+        """
+        self.settings = get_settings()
+        self.model_manager = model_manager or ModelManager()
+        self._pipeline = None
+
+    @property
+    def is_mock_mode(self) -> bool:
+        """Return whether MedASR should operate in deterministic mock mode.
+
+        Args:
+            None: Reads current settings.
+
+        Returns:
+            bool: True when configured model id is "mock".
+        """
+        return self.settings.MEDASR_MODEL_ID.lower() == "mock"
+
+    def load_model(self) -> None:
+        """Load the MedASR transformer pipeline unless running in mock mode.
+
+        Args:
+            None: Uses settings for model id and device selection.
+
+        Returns:
+            None: Caches loaded pipeline instance.
+        """
+        if self.is_mock_mode:
+            self._pipeline = "mock"
+            self.model_manager.register_model("medasr", self._pipeline)
+            return
+
+        if self._pipeline is not None:
+            return
+
+        if pipeline is None:
+            raise ModelExecutionError("transformers is required for non-mock MedASR mode")
+
+        device = "cuda:0"
+        if self.model_manager.check_gpu()["vram_total_bytes"] == 0:
+            device = "cpu"
+
+        try:
+            self._pipeline = pipeline(
+                "automatic-speech-recognition",
+                model=self.settings.MEDASR_MODEL_ID,
+                device=device,
+            )
+        except Exception as exc:
+            raise ModelExecutionError(f"Failed to load MedASR model: {exc}") from exc
+
+        self.model_manager.register_model("medasr", self._pipeline)
+
+    def transcribe(self, audio_path: str) -> Transcript:
+        """Transcribe audio input into a Transcript schema object.
+
+        Args:
+            audio_path (str): Path to 16kHz mono audio WAV.
+
+        Returns:
+            Transcript: Structured transcript result.
+        """
+        source = Path(audio_path)
+        if not source.exists():
+            raise ModelExecutionError(f"Audio path not found: {source}")
+
+        if self._pipeline is None:
+            self.load_model()
+
+        if self.is_mock_mode:
+            text = self._get_mock_text(source)
+            duration_s = self._duration(source)
+            return self._make_transcript(source, text, duration_s)
+
+        waveform, _ = librosa.load(source, sr=16000, mono=True)
+        duration_s = float(librosa.get_duration(y=waveform, sr=16000))
+
+        try:
+            result = self._pipeline(
+                waveform,
+                chunk_length_s=20,
+                stride_length_s=(4, 2),
+                return_timestamps=True,
+                generate_kwargs={"language": "en", "task": "transcribe"},
+            )
+        except Exception as exc:
+            raise ModelExecutionError(f"MedASR inference failed: {exc}") from exc
+
+        transcript_text = str(result.get("text", "")).strip()
+        return self._make_transcript(source, transcript_text, duration_s)
+
+    def _make_transcript(self, audio_path: Path, text: str, duration_s: float) -> Transcript:
+        """Build a Transcript object from model output values.
+
+        Args:
+            audio_path (Path): Source audio path.
+            text (str): Transcript text.
+            duration_s (float): Audio duration seconds.
+
+        Returns:
+            Transcript: Pydantic transcript model.
+        """
+        now = datetime.now(tz=timezone.utc).isoformat()
+        consultation_id = audio_path.stem
+        return Transcript(
+            consultation_id=consultation_id,
+            text=text,
+            duration_s=duration_s,
+            word_count=len(text.split()),
+            created_at=now,
+        )
+
+    @staticmethod
+    def _duration(audio_path: Path) -> float:
+        """Compute audio duration in seconds using librosa.
+
+        Args:
+            audio_path (Path): Audio file path.
+
+        Returns:
+            float: Duration in seconds.
+        """
+        waveform, sample_rate = librosa.load(audio_path, sr=16000, mono=True)
+        return float(librosa.get_duration(y=waveform, sr=sample_rate))
+
+    @staticmethod
+    def _get_mock_text(audio_path: Path) -> str:
+        """Return ground-truth transcript for known demo files in mock mode.
+
+        Args:
+            audio_path (Path): Audio file path used for lookup.
+
+        Returns:
+            str: Transcript text from fixture file or fallback placeholder.
+        """
+        transcript_map = {
+            "mrs_thompson": Path("data/demo/mrs_thompson_transcript.txt"),
+            "mr_okafor": Path("data/demo/mr_okafor_transcript.txt"),
+            "ms_patel": Path("data/demo/ms_patel_transcript.txt"),
+        }
+        for key, transcript_path in transcript_map.items():
+            if key in audio_path.stem:
+                return transcript_path.read_text(encoding="utf-8").strip()
+        return "Mock transcript placeholder for non-demo audio input."

backend/models/model_manager.py

@@ -0,0 +1,91 @@
+"""Shared model lifecycle management utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import torch
+except ModuleNotFoundError:  # pragma: no cover - lightweight environments
+    torch = None
+
+
+class ModelManager:
+    """Track loaded model objects and expose GPU/cache health helpers.
+
+    Args:
+        None: Manager starts with an empty registry.
+
+    Returns:
+        None: Instance stores mutable model registry state.
+    """
+
+    def __init__(self) -> None:
+        """Initialise model registry.
+
+        Args:
+            None: No constructor parameters.
+
+        Returns:
+            None: Creates an empty dictionary for loaded models.
+        """
+        self._models: dict[str, Any] = {}
+
+    def register_model(self, name: str, model: Any) -> None:
+        """Register a loaded model object under a unique name.
+
+        Args:
+            name (str): Registry key for the model.
+            model (Any): Loaded model or pipeline object.
+
+        Returns:
+            None: Updates internal model registry.
+        """
+        self._models[name] = model
+
+    def get_model(self, name: str) -> Any | None:
+        """Return a model object by name when present.
+
+        Args:
+            name (str): Registry key for the model.
+
+        Returns:
+            Any | None: Registered model object or None.
+        """
+        return self._models.get(name)
+
+    def clear_cache(self) -> None:
+        """Clear torch CUDA cache when GPU is available.
+
+        Args:
+            None: No parameters.
+
+        Returns:
+            None: Invokes CUDA cache clear side effects.
+        """
+        if torch is not None and torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    def check_gpu(self) -> dict[str, str | int]:
+        """Return GPU name and VRAM usage metrics.
+
+        Args:
+            None: No parameters.
+
+        Returns:
+            dict[str, str | int]: gpu_name, vram_used_bytes, vram_total_bytes.
+        """
+        if torch is None or not torch.cuda.is_available():
+            return {
+                "gpu_name": "cpu-mock",
+                "vram_used_bytes": 0,
+                "vram_total_bytes": 0,
+            }
+
+        device_index = torch.cuda.current_device()
+        props = torch.cuda.get_device_properties(device_index)
+        return {
+            "gpu_name": props.name,
+            "vram_used_bytes": int(torch.cuda.memory_allocated(device_index)),
+            "vram_total_bytes": int(props.total_memory),
+        }

backend/orchestrator.py

@@ -0,0 +1,496 @@
+"""Pipeline orchestrator coordinating transcription, context retrieval, and prompt assembly."""
+
+from __future__ import annotations
+
+import json
+import asyncio
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+try:
+    import torch
+except ModuleNotFoundError:  # pragma: no cover - mock/lightweight runtime
+    torch = None
+
+
+from backend.errors import ModelExecutionError, get_component_logger
+from backend.audio import validate_audio
+from backend.models.doc_generator import DocumentGenerator
+from backend.models.ehr_agent import EHRAgent
+from backend.models.medasr import MedASRModel
+from backend.schemas import ClinicalDocument, Consultation, ConsultationStatus, Patient, PatientContext, PipelineProgress, PipelineStage
+
+logger = get_component_logger("orchestrator")
+
+
+class PipelineOrchestrator:
+    """Coordinate the consultation lifecycle across all model pipeline stages.
+
+    Args:
+        medasr_model (MedASRModel | None): Optional MedASR model wrapper instance.
+        ehr_agent (EHRAgent | None): Optional EHR agent instance.
+
+    Returns:
+        None: Initialises orchestrator state stores in memory.
+    """
+
+    def __init__(
+        self,
+        medasr_model: MedASRModel | None = None,
+        ehr_agent: EHRAgent | None = None,
+        doc_generator: DocumentGenerator | None = None,
+    ) -> None:
+        self.consultations: dict[str, Consultation] = {}
+        self.progress: dict[str, PipelineProgress] = {}
+        self._medasr_model = medasr_model or MedASRModel()
+        self._ehr_agent = ehr_agent or EHRAgent()
+        self._doc_generator = doc_generator or DocumentGenerator()
+
+    @staticmethod
+    def _clear_cuda_cache() -> None:
+        """Release cached CUDA memory between heavy model stages when CUDA is available.
+
+        Args:
+            None: Uses current torch CUDA runtime state.
+
+        Returns:
+            None: Performs in-place cache cleanup only.
+        """
+
+        if torch is not None and torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    @staticmethod
+    def _timestamp() -> str:
+        """Return current UTC timestamp string for consultation lifecycle fields.
+
+        Args:
+            None: Reads current clock only.
+
+        Returns:
+            str: ISO timestamp with timezone.
+        """
+
+        return datetime.now(tz=timezone.utc).isoformat()
+
+    def start_consultation(self, patient: Patient) -> Consultation:
+        """Create and store a consultation in recording state.
+
+        Args:
+            patient (Patient): Patient selected for this consultation.
+
+        Returns:
+            Consultation: Newly created consultation object.
+        """
+
+        consultation_id = f"cons-{uuid4()}"
+        consultation = Consultation(
+            id=consultation_id,
+            patient=patient,
+            status=ConsultationStatus.RECORDING,
+            started_at=self._timestamp(),
+        )
+        self.consultations[consultation_id] = consultation
+        self.progress[consultation_id] = PipelineProgress(
+            consultation_id=consultation_id,
+            stage=PipelineStage.RETRIEVING_CONTEXT,
+            progress_pct=5,
+            message="Consultation started. Recording in progress.",
+        )
+        return consultation
+
+    def prefetch_context(self, consultation_id: str) -> None:
+        """Preload patient context for a consultation to reduce end-stage latency.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            None: Updates consultation context cache in place.
+        """
+
+        consultation = self.get_consultation(consultation_id)
+        if consultation.context is not None:
+            return
+
+        try:
+            consultation.context = self._ehr_agent.get_patient_context(consultation.patient.id)
+            self.progress[consultation_id] = PipelineProgress(
+                consultation_id=consultation_id,
+                stage=PipelineStage.RETRIEVING_CONTEXT,
+                progress_pct=25,
+                message="Patient context prefetched.",
+            )
+        except Exception as exc:
+            logger.warning("Context prefetch failed", consultation_id=consultation_id, error=str(exc))
+
+    def end_consultation(self, consultation_id: str) -> Consultation:
+        """Finalize recording and run the staged processing pipeline.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            Consultation: Updated consultation after pipeline completion.
+        """
+
+        try:
+            return asyncio.run(
+                asyncio.wait_for(
+                    asyncio.to_thread(self._run_pipeline, consultation_id),
+                    timeout=float(self._doc_generator.settings.PIPELINE_TIMEOUT_S),
+                )
+            )
+        except TimeoutError:
+            raise
+        except asyncio.TimeoutError as exc:
+            raise TimeoutError("Pipeline timed out") from exc
+
+    def _run_pipeline(self, consultation_id: str) -> Consultation:
+        """Execute all pipeline stages for an existing consultation.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            Consultation: Updated consultation after pipeline completion.
+        """
+
+        consultation = self.get_consultation(consultation_id)
+        if not consultation.audio_file_path:
+            raise ModelExecutionError("No uploaded audio available for this consultation")
+
+        validate_audio(consultation.audio_file_path)
+
+        total_start = time.perf_counter()
+        stage_start = time.perf_counter()
+        consultation.status = ConsultationStatus.PROCESSING
+        consultation.ended_at = self._timestamp()
+
+        self.progress[consultation_id] = PipelineProgress(
+            consultation_id=consultation_id,
+            stage=PipelineStage.TRANSCRIBING,
+            progress_pct=33,
+            message="Finalising transcript...",
+        )
+        transcript = self._medasr_model.transcribe(consultation.audio_file_path)
+        if not transcript.text.strip():
+            raise ModelExecutionError("Audio could not be transcribed.")
+        consultation.transcript = transcript.model_copy(update={"consultation_id": consultation_id})
+        transcribe_s = round(time.perf_counter() - stage_start, 3)
+        logger.info("Pipeline stage complete", consultation_id=consultation_id, stage="transcribe", duration_s=transcribe_s)
+        self._clear_cuda_cache()
+
+        stage_start = time.perf_counter()
+        self.progress[consultation_id] = PipelineProgress(
+            consultation_id=consultation_id,
+            stage=PipelineStage.RETRIEVING_CONTEXT,
+            progress_pct=66,
+            message="Synthesising patient context...",
+        )
+        if consultation.context is None:
+            try:
+                consultation.context = self._ehr_agent.get_patient_context(consultation.patient.id)
+            except Exception as exc:
+                warning = f"FHIR retrieval unavailable; continuing with transcript only: {exc}"
+                logger.warning("FHIR degradation activated", consultation_id=consultation_id, warning=warning)
+                consultation.context = self._build_transcript_only_context(consultation, warning)
+        context_s = round(time.perf_counter() - stage_start, 3)
+        logger.info("Pipeline stage complete", consultation_id=consultation_id, stage="retrieve_context", duration_s=context_s)
+        self._clear_cuda_cache()
+
+        stage_start = time.perf_counter()
+        self.progress[consultation_id] = PipelineProgress(
+            consultation_id=consultation_id,
+            stage=PipelineStage.GENERATING_DOCUMENT,
+            progress_pct=90,
+            message="Combining transcript and context for document generation...",
+        )
+        if consultation.transcript and consultation.context:
+            consultation.context = self._truncate_context(consultation.context)
+            consultation.document = self._generate_document_with_oom_retry(
+                consultation.transcript.text,
+                consultation.context,
+                consultation_id,
+            ).model_copy(update={"consultation_id": consultation_id})
+        else:
+            raise ModelExecutionError("Transcript and patient context are required before document generation")
+        generate_s = round(time.perf_counter() - stage_start, 3)
+        logger.info("Pipeline stage complete", consultation_id=consultation_id, stage="generate_document", duration_s=generate_s)
+        self._clear_cuda_cache()
+
+        consultation.pipeline_stage = PipelineStage.COMPLETE
+        consultation.status = ConsultationStatus.REVIEW
+        self.progress[consultation_id] = PipelineProgress(
+            consultation_id=consultation_id,
+            stage=PipelineStage.COMPLETE,
+            progress_pct=100,
+            message="Pipeline complete. Clinical document ready for review.",
+        )
+        total_s = round(time.perf_counter() - total_start, 3)
+        logger.info(
+            "Pipeline completed",
+            consultation_id=consultation_id,
+            total_duration_s=total_s,
+            transcribe_s=transcribe_s,
+            context_s=context_s,
+            generate_s=generate_s,
+        )
+        return consultation
+
+    def _generate_document_with_oom_retry(
+        self,
+        transcript_text: str,
+        context: PatientContext,
+        consultation_id: str,
+    ) -> ClinicalDocument:
+        """Generate a document with one OOM recovery retry.
+
+        Args:
+            transcript_text (str): Consultation transcript text.
+            context (PatientContext): Context payload for document generation.
+            consultation_id (str): Consultation identifier for logging.
+
+        Returns:
+            ClinicalDocument: Generated document payload.
+        """
+
+        max_tokens = int(self._doc_generator.settings.DOC_GEN_MAX_TOKENS)
+        try:
+            return self._doc_generator.generate_document(transcript_text, context, max_new_tokens=max_tokens)
+        except TypeError as exc:
+            if "max_new_tokens" not in str(exc):
+                raise
+            logger.warning(
+                "Document generator does not accept max_new_tokens override; falling back to default signature",
+                consultation_id=consultation_id,
+            )
+            return self._doc_generator.generate_document(transcript_text, context)
+        except torch.cuda.OutOfMemoryError as exc:
+            self._clear_cuda_cache()
+            reduced_tokens = max(256, max_tokens // 2)
+            logger.warning(
+                "OOM during document generation; retrying with reduced token budget",
+                consultation_id=consultation_id,
+                previous_max_new_tokens=max_tokens,
+                retry_max_new_tokens=reduced_tokens,
+            )
+            return self._doc_generator.generate_document(transcript_text, context, max_new_tokens=reduced_tokens)
+
+    def _build_transcript_only_context(self, consultation: Consultation, warning: str) -> PatientContext:
+        """Build minimal patient context when EHR retrieval fails.
+
+        Args:
+            consultation (Consultation): Consultation containing patient demographics.
+            warning (str): Retrieval warning text to persist.
+
+        Returns:
+            PatientContext: Transcript-only fallback context.
+        """
+
+        return PatientContext(
+            patient_id=consultation.patient.id,
+            demographics={
+                "name": consultation.patient.name,
+                "dob": consultation.patient.date_of_birth,
+                "nhs_number": consultation.patient.nhs_number,
+                "age": consultation.patient.age,
+                "sex": consultation.patient.sex,
+            },
+            problem_list=[],
+            medications=[],
+            allergies=[],
+            recent_labs=[],
+            recent_imaging=[],
+            clinical_flags=[],
+            last_letter_excerpt=None,
+            retrieval_warnings=[warning],
+            retrieved_at=self._timestamp(),
+        )
+
+    def _truncate_context(self, context: PatientContext) -> PatientContext:
+        """Truncate oversized context payloads to fit the max-sequence envelope.
+
+        Args:
+            context (PatientContext): Structured patient context before generation.
+
+        Returns:
+            PatientContext: Potentially truncated context payload.
+        """
+
+        max_tokens = int(self._doc_generator.settings.MAX_SEQ_LENGTH)
+        context_payload = context.model_dump(mode="json")
+        estimated_tokens = len(json.dumps(context_payload, ensure_ascii=False).split())
+        if estimated_tokens <= max_tokens:
+            return context
+
+        for list_field in ("recent_labs", "medications", "problem_list", "allergies", "recent_imaging", "clinical_flags"):
+            values = context_payload.get(list_field, [])
+            if isinstance(values, list) and len(values) > 2:
+                context_payload[list_field] = values[: max(2, len(values) // 2)]
+            estimated_tokens = len(json.dumps(context_payload, ensure_ascii=False).split())
+            if estimated_tokens <= max_tokens:
+                break
+
+        warnings = list(context_payload.get("retrieval_warnings", []))
+        warnings.append("Context exceeded token budget and was truncated to fit generation limits.")
+        context_payload["retrieval_warnings"] = warnings
+        return PatientContext.model_validate(context_payload)
+
+
+    def update_document_sections(self, consultation_id: str, sections: list[dict[str, str]]) -> ClinicalDocument:
+        """Update editable document sections before sign-off.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+            sections (list[dict[str, str]]): Edited sections with heading and content keys.
+
+        Returns:
+            ClinicalDocument: Updated in-memory document.
+        """
+
+        consultation = self.get_consultation(consultation_id)
+        if consultation.document is None:
+            raise ModelExecutionError("No generated document available to edit")
+
+        existing_sections = list(consultation.document.sections)
+        updates_by_heading = {str(item.get("heading", "")).strip().lower(): str(item.get("content", "")) for item in sections if str(item.get("heading", "")).strip()}
+
+        for idx, section in enumerate(existing_sections):
+            key = section.heading.strip().lower()
+            if key in updates_by_heading:
+                existing_sections[idx] = section.model_copy(update={"content": updates_by_heading[key]})
+
+        consultation.document = consultation.document.model_copy(update={"sections": existing_sections})
+        return consultation.document
+
+    def sign_off_document(self, consultation_id: str) -> ClinicalDocument:
+        """Mark a generated consultation document as signed off.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            ClinicalDocument: Signed-off document for the consultation.
+        """
+
+        consultation = self.get_consultation(consultation_id)
+        if consultation.document is None:
+            raise ModelExecutionError("No generated document available to sign off")
+
+        consultation.status = ConsultationStatus.SIGNED_OFF
+        consultation.document = consultation.document.model_copy(update={"status": ConsultationStatus.SIGNED_OFF})
+        logger.info("Document signed off", consultation_id=consultation_id)
+        return consultation.document
+
+    def regenerate_document_section(self, consultation_id: str, section_heading: str) -> ClinicalDocument:
+        """Regenerate a single section by re-running generation and replacing matching heading content.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+            section_heading (str): Heading name for the section to regenerate.
+
+        Returns:
+            ClinicalDocument: Updated clinical document with refreshed section content.
+        """
+
+        consultation = self.get_consultation(consultation_id)
+        if consultation.transcript is None or consultation.context is None:
+            raise ModelExecutionError("Transcript and context are required to regenerate a section")
+        if consultation.document is None:
+            raise ModelExecutionError("No generated document available to regenerate")
+
+        refreshed_document = self._doc_generator.generate_document(
+            consultation.transcript.text,
+            consultation.context,
+        ).model_copy(update={"consultation_id": consultation_id})
+        replacement_section = next(
+            (
+                section
+                for section in refreshed_document.sections
+                if section.heading.lower() == section_heading.strip().lower()
+            ),
+            None,
+        )
+        if replacement_section is None:
+            raise ModelExecutionError(f"Section not found in regenerated output: {section_heading}")
+
+        updated_sections = []
+        replaced = False
+        for section in consultation.document.sections:
+            if section.heading.lower() == section_heading.strip().lower():
+                updated_sections.append(replacement_section)
+                replaced = True
+            else:
+                updated_sections.append(section)
+
+        if not replaced:
+            raise ModelExecutionError(f"Section not found in existing document: {section_heading}")
+
+        consultation.document = consultation.document.model_copy(
+            update={
+                "sections": updated_sections,
+                "generated_at": refreshed_document.generated_at,
+                "generation_time_s": refreshed_document.generation_time_s,
+                "status": ConsultationStatus.REVIEW,
+            }
+        )
+        consultation.status = ConsultationStatus.REVIEW
+        logger.info("Document section regenerated", consultation_id=consultation_id, section_heading=section_heading)
+        return consultation.document
+
+    def _build_document_prompt_payload(self, consultation_id: str) -> str:
+        """Compose stage-3 prompt payload from transcript and context as JSON.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            str: Combined payload string for downstream document generation model.
+        """
+
+        consultation = self.get_consultation(consultation_id)
+        if consultation.transcript is None or consultation.context is None:
+            raise ModelExecutionError("Transcript and context are required for prompt assembly")
+
+        payload = {
+            "consultation_id": consultation_id,
+            "transcript": consultation.transcript.text,
+            "context": consultation.context.model_dump(mode="json"),
+        }
+        return json.dumps(payload, ensure_ascii=False)
+
+    def get_consultation(self, consultation_id: str) -> Consultation:
+        """Get a consultation by id from in-memory store.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            Consultation: Stored consultation object.
+        """
+
+        consultation = self.consultations.get(consultation_id)
+        if consultation is None:
+            raise KeyError(f"Consultation not found: {consultation_id}")
+        return consultation
+
+    def get_progress(self, consultation_id: str) -> PipelineProgress:
+        """Get latest pipeline progress for a consultation.
+
+        Args:
+            consultation_id (str): Consultation identifier.
+
+        Returns:
+            PipelineProgress: Last recorded progress event.
+        """
+
+        progress = self.progress.get(consultation_id)
+        if progress is None:
+            raise KeyError(f"Progress not found for consultation: {consultation_id}")
+        return progress
+
+
+PROMPTS_DIR = Path("backend/prompts")

backend/prompts/context_synthesis.j2

@@ -0,0 +1,38 @@
+<|system|>
+You are a clinical EHR navigation agent. Your task is to retrieve and synthesise a patient's medical context from FHIR resources to support clinical documentation.
+
+Given a patient ID, use the available FHIR tools to retrieve:
+1. Demographics (Patient resource)
+2. Active conditions/diagnoses (Condition resources)
+3. Current medications (MedicationRequest resources)
+4. Allergies (AllergyIntolerance resources)
+5. Recent laboratory results — last 6 months (Observation resources, category=laboratory)
+6. Recent imaging reports (DiagnosticReport resources)
+
+After retrieval, synthesise the data into the following JSON structure ONLY. Do not include any explanation, commentary, or markdown formatting. Output ONLY valid JSON:
+
+{
+  "patient_id": "...",
+  "demographics": {...},
+  "problem_list": ["..."],
+  "medications": [{...}],
+  "allergies": [{...}],
+  "recent_labs": [{...}],
+  "recent_imaging": [{...}],
+  "clinical_flags": ["..."],
+  "last_letter_excerpt": "...",
+  "retrieval_warnings": [],
+  "retrieved_at": "..."
+}
+<|end|>
+
+<|user|>
+PATIENT ID: {{ patient_id }}
+
+RAW FHIR DATA:
+{{ raw_fhir_data }}
+
+Synthesise the patient context now.
+<|end|>
+
+<|assistant|>

backend/prompts/document_generation.j2

@@ -0,0 +1,60 @@
+<|system|>
+You are an NHS clinical documentation assistant. Generate a structured NHS outpatient clinic letter from the consultation transcript and patient context provided below.
+
+STRICT OUTPUT FORMAT (follow exactly)
+- Date: {{ letter_date }}
+- Addressee: GP name and practice address from the patient record
+- Re: Full patient name, DOB, NHS number
+- Salutation: Dear Dr [GP surname],
+- Body sections in this exact order:
+  1) History of presenting complaint
+  2) Examination findings
+  3) Investigation results
+  4) Assessment and plan
+  5) Current medications
+- Sign-off line: Warm regards,
+  {{ clinician_name }}
+  {{ clinician_title }}
+
+STYLE AND SAFETY RULES
+1. Use formal British medical English, third person, past tense.
+2. Include both positive and negative findings from the consultation.
+3. Keep length between 300 and 500 words.
+4. Use ONLY facts from transcript + patient context.
+5. Use EXACT numeric values from patient context (no rounding, no unit changes, no fabrication).
+6. If the transcript states a value that differs from EHR context, include the EHR value and mark the mismatch as [DISCREPANCY].
+7. Do not add bullet points unless the source explicitly lists items.
+8. If a section has no discussed information, write a short factual sentence stating this.
+
+NEGATIVE EXAMPLES (DO NOT DO THESE)
+- Do NOT invent examination findings that were not discussed.
+- Do NOT replace exact values (e.g., "55 mmol/mol") with vague language (e.g., "raised").
+- Do NOT use US spelling (e.g., "anemia", "behavior").
+- Do NOT omit safety-critical negatives that were explicitly denied.
+
+MICRO-EXEMPLAR OF EXPECTED REGISTER
+Date: 13 Feb 2026
+Re: Mary Thompson, DOB 12/04/1964, NHS No. 943 476 5919
+Dear Dr Ahmed,
+History of presenting complaint
+Mrs Thompson reported persistent fatigue and polydipsia over the preceding three months.
+Investigation results
+Latest blood tests showed HbA1c 55 mmol/mol and eGFR 52 mL/min/1.73m².
+Assessment and plan
+The impression was suboptimal glycaemic control; metformin was continued and repeat bloods were arranged in three months.
+Warm regards,
+Dr Sarah Chen
+Consultant Diabetologist
+<|end|>
+
+<|user|>
+## CONSULTATION TRANSCRIPT
+{{ transcript }}
+
+## PATIENT CONTEXT (from Electronic Health Record)
+{{ context_json }}
+
+Generate the NHS clinic letter now.
+<|end|>
+
+<|assistant|>

backend/prompts/ehr_agent_system.txt

@@ -0,0 +1,25 @@
+You are a clinical EHR navigation agent. Your task is to retrieve and synthesise a patient's medical context from FHIR resources to support clinical documentation.
+
+Given a patient ID, use the available FHIR tools to retrieve:
+1. Demographics (Patient resource)
+2. Active conditions/diagnoses (Condition resources)
+3. Current medications (MedicationRequest resources)
+4. Allergies (AllergyIntolerance resources)
+5. Recent laboratory results — last 6 months (Observation resources, category=laboratory)
+6. Recent imaging reports (DiagnosticReport resources)
+
+After retrieval, synthesise the data into the following JSON structure ONLY. Do not include any explanation, commentary, or markdown formatting. Output ONLY valid JSON:
+
+{
+  "patient_id": "...",
+  "demographics": {...},
+  "problem_list": ["..."],
+  "medications": [{...}],
+  "allergies": [{...}],
+  "recent_labs": [{...}],
+  "recent_imaging": [{...}],
+  "clinical_flags": ["..."],
+  "last_letter_excerpt": "...",
+  "retrieval_warnings": [],
+  "retrieved_at": "..."
+}

backend/schemas.py

@@ -0,0 +1,149 @@
+"""Clarke data models — Pydantic v2 schemas for all system objects."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ConsultationStatus(str, Enum):
+    """Status lifecycle for a consultation session."""
+
+    IDLE = "idle"
+    RECORDING = "recording"
+    PAUSED = "paused"
+    PROCESSING = "processing"
+    REVIEW = "review"
+    SIGNED_OFF = "signed_off"
+
+
+class PipelineStage(str, Enum):
+    """Discrete execution stages for the consultation pipeline."""
+
+    TRANSCRIBING = "transcribing"
+    RETRIEVING_CONTEXT = "retrieving_context"
+    GENERATING_DOCUMENT = "generating_document"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
+class Patient(BaseModel):
+    """A patient in the clinic list."""
+
+    id: str = Field(description="FHIR Patient resource ID")
+    nhs_number: str = Field(description="NHS number (format: XXX XXX XXXX)")
+    name: str = Field(description="Full name (e.g., 'Mrs. Margaret Thompson')")
+    date_of_birth: str = Field(description="DOB in DD/MM/YYYY format")
+    age: int
+    sex: str = Field(description="'Male' or 'Female'")
+    appointment_time: str = Field(description="HH:MM format")
+    summary: str = Field(description="One-line clinical summary for dashboard card")
+
+
+class LabResult(BaseModel):
+    """A single laboratory result with trend."""
+
+    name: str = Field(description="e.g., 'HbA1c'")
+    value: str = Field(description="e.g., '55'")
+    unit: str = Field(description="e.g., 'mmol/mol'")
+    reference_range: Optional[str] = Field(default=None, description="e.g., '20-42'")
+    date: str = Field(description="ISO date of result")
+    trend: Optional[str] = Field(default=None, description="'rising', 'falling', 'stable', or None")
+    previous_value: Optional[str] = Field(default=None, description="Previous result value")
+    previous_date: Optional[str] = Field(default=None)
+    fhir_resource_id: Optional[str] = Field(default=None, description="Source FHIR Observation ID")
+
+
+class PatientContext(BaseModel):
+    """Structured patient context synthesised by the EHR Agent from FHIR data."""
+
+    patient_id: str
+    demographics: dict = Field(description="name, dob, nhs_number, age, sex, address")
+    problem_list: list[str] = Field(description="Active diagnoses, e.g., ['Type 2 Diabetes Mellitus (2019)', ...]")
+    medications: list[dict] = Field(
+        description="[{'name': 'Metformin', 'dose': '1g', 'frequency': 'BD', 'fhir_id': '...'}]"
+    )
+    allergies: list[dict] = Field(
+        description="[{'substance': 'Penicillin', 'reaction': 'Anaphylaxis', 'severity': 'high'}]"
+    )
+    recent_labs: list[LabResult] = Field(default_factory=list)
+    recent_imaging: list[dict] = Field(default_factory=list, description="[{'type': 'CXR', 'date': '...', 'summary': '...'}]")
+    clinical_flags: list[str] = Field(default_factory=list, description="['HbA1c rising trend over 6 months']")
+    last_letter_excerpt: Optional[str] = Field(default=None, description="Key excerpt from most recent clinic letter")
+    retrieval_warnings: list[str] = Field(default_factory=list, description="Warnings if some FHIR queries failed")
+    retrieved_at: str = Field(description="ISO timestamp of retrieval")
+
+
+class Transcript(BaseModel):
+    """Consultation transcript produced by MedASR."""
+
+    consultation_id: str
+    text: str = Field(description="Full transcript text")
+    duration_s: float = Field(description="Audio duration in seconds")
+    word_count: int
+    created_at: str
+
+
+class DocumentSection(BaseModel):
+    """A single section of the generated clinical letter."""
+
+    heading: str = Field(description="e.g., 'History of presenting complaint'")
+    content: str = Field(description="Section body text")
+    editable: bool = Field(default=True)
+    fhir_sources: list[str] = Field(default_factory=list, description="FHIR resource IDs cited in this section")
+
+
+class ClinicalDocument(BaseModel):
+    """A generated NHS clinical letter."""
+
+    consultation_id: str
+    letter_date: str
+    patient_name: str
+    patient_dob: str
+    nhs_number: str
+    addressee: str = Field(description="GP name and address")
+    salutation: str = Field(description="e.g., 'Dear Dr. Patel,'")
+    sections: list[DocumentSection]
+    medications_list: list[str] = Field(description="Current medications (formatted)")
+    sign_off: str = Field(description="e.g., 'Dr. S. Chen, Consultant Diabetologist'")
+    status: ConsultationStatus = ConsultationStatus.REVIEW
+    generated_at: str
+    generation_time_s: float = Field(description="Time taken for MedGemma 27B inference")
+    discrepancies: list[dict] = Field(default_factory=list, description="[{'type': 'allergy_mismatch', 'detail': '...'}]")
+
+
+class Consultation(BaseModel):
+    """A complete consultation session — links patient, transcript, context, and document."""
+
+    id: str = Field(description="Unique consultation ID (UUID)")
+    patient: Patient
+    status: ConsultationStatus = ConsultationStatus.IDLE
+    pipeline_stage: Optional[PipelineStage] = None
+    context: Optional[PatientContext] = None
+    transcript: Optional[Transcript] = None
+    document: Optional[ClinicalDocument] = None
+    started_at: Optional[str] = None
+    ended_at: Optional[str] = None
+    audio_file_path: Optional[str] = None
+
+
+class PipelineProgress(BaseModel):
+    """Real-time pipeline progress updates pushed to the UI."""
+
+    consultation_id: str
+    stage: PipelineStage
+    progress_pct: int = Field(ge=0, le=100)
+    message: str = Field(description="Human-readable status, e.g., 'Finalising transcript...'")
+
+
+class ErrorResponse(BaseModel):
+    """Standardised error response format."""
+
+    error: str = Field(description="Error category: 'model_error', 'fhir_error', 'audio_error', 'timeout'")
+    message: str = Field(description="Human-readable error message for UI display")
+    detail: Optional[str] = Field(default=None, description="Technical detail (logged, not shown to user)")
+    consultation_id: Optional[str] = None
+    timestamp: str

backend/utils.py

@@ -0,0 +1,78 @@
+"""Shared utility helpers used across backend modules."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from backend.errors import get_component_logger
+
+
+def timed(component: str) -> Callable:
+    """Measure function runtime and log duration with structured metadata.
+
+    Params:
+        component (str): Component name used in structured logs.
+    Returns:
+        Callable: Decorator wrapping the target callable.
+    """
+
+    log = get_component_logger(component)
+
+    def decorator(func: Callable) -> Callable:
+        """Wrap a function with timing instrumentation.
+
+        Params:
+            func (Callable): Function to time.
+        Returns:
+            Callable: Timed wrapper preserving function signature metadata.
+        """
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Execute wrapped function and emit success/failure timing logs.
+
+            Params:
+                *args (Any): Positional arguments passed to wrapped function.
+                **kwargs (Any): Keyword arguments passed to wrapped function.
+            Returns:
+                Any: Original function return value.
+            """
+
+            start_time = time.perf_counter()
+            try:
+                result = func(*args, **kwargs)
+                duration_s = time.perf_counter() - start_time
+                log.info(
+                    "Function execution complete",
+                    function_name=func.__name__,
+                    duration_s=round(duration_s, 4),
+                )
+                return result
+            except Exception:
+                duration_s = time.perf_counter() - start_time
+                log.exception(
+                    "Function execution failed",
+                    function_name=func.__name__,
+                    duration_s=round(duration_s, 4),
+                )
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def sanitize_json_payload(payload: Any) -> Any:
+    """Return a JSON-serialisable deep copy of an arbitrary payload.
+
+    Params:
+        payload (Any): Input object that should be JSON serialisable.
+    Returns:
+        Any: Normalised payload safe for JSON transport/storage.
+    """
+
+    return json.loads(json.dumps(payload, default=str))

clarke/.env.template

@@ -0,0 +1 @@
+# Placeholder

clarke/Dockerfile

@@ -0,0 +1 @@
+# Placeholder

clarke/LICENSE

@@ -0,0 +1 @@
+# Placeholder

clarke/README.md

@@ -0,0 +1 @@
+# Placeholder

clarke/app.py

@@ -0,0 +1 @@
+"""Legacy placeholder module for the nested `clarke` package app entrypoint."""

clarke/backend/__init__.py

@@ -0,0 +1 @@
+"""Package initializer."""

clarke/backend/api.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/audio.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/config.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/errors.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/fhir/__init__.py

@@ -0,0 +1 @@
+"""Package initializer."""

clarke/backend/fhir/client.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/fhir/mock_api.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/fhir/queries.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/fhir/tools.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/models/__init__.py

@@ -0,0 +1 @@
+"""Package initializer."""

clarke/backend/models/doc_generator.py

@@ -0,0 +1 @@
+"""Placeholder module."""

clarke/backend/models/ehr_agent.py

@@ -0,0 +1 @@
+"""Placeholder module."""