Update README.md

README.md

@@ -1,10 +1,225 @@
 ---
 title: README
-emoji: 📚
+emoji: 🩺
 colorFrom: green
 colorTo: gray
 sdk: static
 pinned: false
 ---
 
-Edit this `README.md` markdown file to author your organization card.
+# COS30018 — Multi-Agent Clinical Reasoning System
+_Swinburne University of Technology_ | _Unit: COS30018 Intelligent Systems_  
+**Team:** Liam · Henry · Hai · Dylan · Vinh
+
+> 🧠🩺 A safety-first, agentic medical assistant that coordinates domain-specialist agents (Diagnostics, Pharmacology, Triage) via a reasoning orchestrator, with retrieval-augmented generation and rigorous evaluation.
+
+---
+
+## Table of Contents
+- [Overview](#overview)
+- [Core Capabilities](#core-capabilities)
+- [Architecture](#architecture)
+- [Data, Training & Reproducibility](#data-training--reproducibility)
+- [Evaluation](#evaluation)
+- [Safety, Ethics & Compliance](#safety-ethics--compliance)
+- [Tech Stack](#tech-stack)
+- [Repository Structure](#repository-structure)
+- [Roadmap](#roadmap)
+- [Team](#team)
+- [Academic Context](#academic-context)
+- [Disclaimer](#disclaimer)
+- [Citation](#citation)
+- [License](#license)
+
+---
+
+## Overview
+This project builds a **multi-agent system** for clinical decision support. A central **reasoning orchestrator** (MCP) routes user problems to **domain-specialist agents**—Diagnostics, Pharmacology, and Triage—then fuses their outputs with evidence from an **Agentic RAG** pipeline over EMR/EHR data and **PubMed** literature. The system prioritizes **accuracy, traceability, and safety** with strict evaluation and retrieval safety rails.
+
+---
+
+## Core Capabilities
+- **Specialist Agents**
+  - **Diagnostics:** differential reasoning, red-flag detection, uncertainty disclosure.
+  - **Pharmacology:** drug–drug/condition interactions, dosing ranges, contraindications.
+  - **Triage:** urgency stratification, disposition options, escalation triggers.
+
+- **Reasoning Orchestrator (MCP)**
+  - Tool-aware planning, routing, and self-critique with **self-consistency**.
+  - Chain-of-thought hidden; user sees concise, cited rationales.
+
+- **Agentic RAG (Node & Graph RAG)**
+  - Retrieval over **EMR/EHR** + **PubMed** with verifiable **citations**.
+  - **Safety rails**: source whitelisting, section-aware chunking, query rewriting.
+  - **Real-time updates** to reflect latest clinical literature.
+
+- **Modeling & Optimization**
+  - **500k+ curated & synthetic cases** for domain adaptation.
+  - **Knowledge Distillation**, **LoRA/QLoRA** with **GRPO** (reasoning-oriented).
+  - Data augmentation: **QAC paraphrasing/chunking**, **self-consistency**, **counterfactuals**, **back-translation**.
+
+---
+
+## Architecture
+```mermaid
+flowchart LR
+  U[Clinician / User] -->|case, symptoms, meds| ORCH(MCP Orchestrator)
+  ORCH -->|route| AG1[Diagnostics Agent]
+  ORCH -->|route| AG2[Pharmacology Agent]
+  ORCH -->|route| AG3[Triage Agent]
+
+  subgraph RAG[Agentic RAG]
+    Q[Query Router] --> RET[Retriever (Node & Graph)]
+    RET --> KB1[(EMR/EHR)]
+    RET --> KB2[(PubMed)]
+    RET --> SR[Safety Rails: filters, provenance, sectioning]
+  end
+
+  AG1 --> RAG
+  AG2 --> RAG
+  AG3 --> RAG
+  RAG --> AG1
+  RAG --> AG2
+  RAG --> AG3
+
+  AG1 --> FUSE[Evidence Fusion & Self-Consistent Reasoning]
+  AG2 --> FUSE
+  AG3 --> FUSE
+  FUSE --> OUT[Final Report: summary, citations, cautions]
+
+  subgraph EVAL[Evaluation & QA]
+    M1[MedMCQA]
+    M2[PubMedQA]
+    SIM[Semantic Similarity Audits (biomedical embeddings)]
+    LR[Early-Stopping + LR Scheduling]
+  end
+  OUT -. logged .-> EVAL
+```
+
+---
+
+## Data, Training & Reproducibility
+
+* **Corpora:** 500k+ curated & synthetic clinical cases spanning multiple specialties.
+* **Distillation & Fine-Tuning:** Teacher–student **Knowledge Distillation**; **LoRA/QLoRA** adapters for efficient specialization; **GRPO** to bias toward faithful, stepwise reasoning.
+* **Augmentation:** QAC paraphrasing & chunking, self-consistency sampling, **counterfactual** case generation, and **back-translation** for robustness.
+* **Reproducible Training (HPC):**
+
+  * Deterministic seeds, pinned package versions, mixed-precision logs.
+  * Checkpointing & artifact tracking; early-stopping with learning-rate scheduling.
+  * Config-driven runs (`configs/…`) and run sheets for auditability.
+
+---
+
+## Evaluation
+
+* **Benchmarks:** **MedMCQA**, **PubMedQA** for domain generalization and reading comprehension.
+* **Semantic Audits:** Biomedical-embedding similarity checks vs. gold rationales/evidence.
+* **Runtime Guards:** Refusal policies for out-of-scope requests, uncertainty flags when evidence is weak.
+* **Reporting:** Per-agent precision/recall, citation coverage, hallucination rate, decision-time.
+
+> *Goal: measurably reduce hallucinations while preserving coverage and answerability, with transparent citations and cautions.*
+
+---
+
+## Safety, Ethics & Compliance
+
+* **Not a medical device**; educational/research use only (see Disclaimer).
+* **Retrieval Safety Rails:** source whitelisting, date scopes, section filters, and citation requirements.
+* **Privacy:** de-identification pipelines for EMR/EHR; least-privilege access patterns.
+* **Compliance Mindset:** aligns with **Australian Privacy Principles (APPs)** and general healthcare data-handling norms.
+* **Human-in-the-Loop:** outputs framed as **clinical decision support**, not directives.
+
+---
+
+## Tech Stack
+
+* **Agent Framework:** MCP-style orchestrator for tool/agent routing.
+* **RAG:** Node & Graph RAG; biomedical embeddings; citation enforcement.
+* **LLM Adaptation:** LoRA/QLoRA, KD, GRPO; augmentation toolchain.
+* **Infra:** HPC training; experiment tracking; containerized services (dev/prod).
+* **Eval:** MedMCQA, PubMedQA harnesses; semantic similarity metrics.
+
+---
+
+## Repository Structure
+
+```
+├─ apps/
+│  ├─ orchestrator/           # MCP planner/router, self-consistency, fusion
+│  ├─ agent_diagnostics/      # differential logic, red flags, uncertainty
+│  ├─ agent_pharmacology/     # DDIs, dosing, contraindications
+│  └─ agent_triage/           # urgency/disposition policy
+├─ rag/
+│  ├─ pipelines/              # Node & Graph RAG, safety rails
+│  ├─ build_index.py          # EMR/EHR + PubMed indexing
+│  └─ server.py               # retrieval API with citation payloads
+├─ training/
+│  ├─ datasets/               # loaders for curated/synthetic cases
+│  ├─ augmentation/           # QAC, counterfactuals, back-translation
+│  ├─ finetune/               # KD, LoRA/QLoRA, GRPO loops
+│  └─ configs/                # seeds, LR schedules, early-stopping
+├─ eval/
+│  ├─ medmcqa/                # benchmark harness
+│  ├─ pubmedqa/               # benchmark harness
+│  └─ semantics/              # embedding audits, hallucination metrics
+├─ docs/                      # design notes, risk register, policies
+├─ scripts/                   # utilities, data prep, CI hooks
+├─ requirements.txt
+├─ .env.example
+└─ LICENSE
+```
+
+---
+
+## Roadmap
+
+* [ ] Expand specialty coverage (cardiology, oncology, paediatrics).
+* [ ] Add guideline-aware retrieval (e.g., section targeting for dosing tables).
+* [ ] Continual-learning loop with clinician feedback and calibration tracking.
+* [ ] UI for evidence graphs and counterfactual “what-if” explorations.
+* [ ] Stress tests for adversarial prompts and data drift.
+
+---
+
+## Team
+
+**Swinburne COS30018 — Group Members**
+Liam · Henry · Hai · Dylan · Vinh
+
+---
+
+## Academic Context
+
+This project demonstrates COS30018 learning outcomes in **intelligent systems** by integrating:
+
+* **Agent architectures** (specialist agents + central planner),
+* **Search & knowledge representation** (graph-structured RAG),
+* **Machine learning** (distillation, parameter-efficient fine-tuning),
+* **Evaluation & ethics** (benchmarking, safety rails, HIL oversight).
+
+---
+
+## Disclaimer
+
+This system is **for research and educational purposes only**. It **does not provide medical advice** and must **not** be used to diagnose, treat, or manage real patients. Always consult qualified healthcare professionals.
+
+---
+
+## Citation
+
+If you reference this work in academic contexts:
+
+```
+Swinburne University of Technology, COS30018 Team (2025).
+Multi-Agent Clinical Reasoning System with Agentic RAG and Safety Rails.
+https://huggingface.co/MedAI-COS30018
+```
+
+---
+
+## License
+Apache-2.0.
+
+
+