README.md

metadata

title: AMR-Guard
emoji: ⚕️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.25.0
python_version: '3.12'
hardware: zero-gpu
pinned: true
license: apache-2.0
tags:
  - healthcare
  - medical
  - antimicrobial-resistance
  - clinical-decision-support
  - streamlit
  - llm
  - medgemma
short_description: Multi-agent clinical support for antimicrobial stewardship

AMR-Guard: Infection Lifecycle Orchestrator

A multi-agent clinical decision-support system for antimicrobial stewardship, submitted to the MedGemma Impact Challenge.

Powered by MedGemma (4B multimodal + 27B text) and TxGemma — HAI-DEF models from Google.

---

What it does

AMR-Guard guides clinicians through two stages of infection management with a dynamic, site-aware patient form that adapts its fields based on the selected infection site.

Stage 1 — Empirical (no lab results yet) Patient history → risk factor analysis → empirical antibiotic recommendation

Stage 2 — Targeted (lab results available) Lab report upload (PDF / image, any language) → pathogen & MIC extraction → resistance trend analysis → targeted prescription with drug interaction screening

A unique capability is MIC creep detection: the system flags when a pathogen's Minimum Inhibitory Concentration has risen ≥4-fold across admissions — even while the lab still reports "Susceptible" — giving clinicians a 6–18 month early warning before formal treatment failure.

---

Key Features

Feature	Details
Dynamic form	Fields adapt to infection site (urinary, respiratory, bloodstream, skin, intra-abdominal, CNS)
Contextual suspected source	Dropdown options change based on infection site (e.g. CAP / HAP / VAP for respiratory)
Conditional creatinine	Shown prominently for systemic infections; optional toggle for skin / intra-abdominal
Lab file upload	Upload PDF or image (PNG/JPG/TIFF) — PDF text extracted via pypdf; images sent to MedGemma vision
MIC creep detection	≥4-fold MIC rise flagged before clinical resistance develops
WHO AWaRe stewardship	ACCESS → WATCH → RESERVE prescribing hierarchy enforced
Drug interaction screening	191 K+ interactions from DDInter 2.0
Renal dose adjustment	Cockcroft-Gault CrCl → 5-tier dose adjustment

---

Agent Pipeline

Patient form ──► Agent 1: Intake Historian  ──► (no lab) ──────────────────────────────► Agent 4: Clinical Pharmacologist ──► Prescription
                       │                                                                              ▲
                       └──► (lab uploaded) ──► Agent 2: Vision Specialist ──► Agent 3: Trend Analyst ──┘

#	Agent	Model	Role
1	Intake Historian	MedGemma 4B IT	Parse EHR notes, calculate CrCl (Cockcroft-Gault), identify MDR risk factors
2	Vision Specialist	MedGemma 4B IT (multimodal)	Extract pathogen names + MIC values from lab images / PDFs in any language
3	Trend Analyst	MedGemma 27B Text IT	Detect MIC creep, compute resistance velocity against EUCAST v16.0 breakpoints
4	Clinical Pharmacologist	MedGemma 4B IT + TxGemma 9B	Select antibiotic + dose, apply WHO AWaRe stewardship, screen drug interactions

Orchestration: LangGraph state machine with conditional routing Knowledge base: SQLite (EUCAST breakpoints, WHO AWaRe, ATLAS surveillance, DDInter interactions) + ChromaDB (IDSA guidelines, WHO GLASS — semantic RAG)

---

Hugging Face Spaces Deployment

Recommended deployment target. Provides a persistent URL, native Streamlit support, GPU access, and multi-user access out of the box.

Requirements

• A HF Space with GPU hardware (T4 for MedGemma 4B; A10G or better for MedGemma 27B)
• HF access granted to MedGemma and TxGemma

Steps

1. Create a new Space

Go to huggingface.co/new-space and select:

• SDK: Streamlit
• Hardware: T4 (GPU) (free tier, limited quota) or A10G

2. Push this repository

git remote set-url space https://huggingface.co/spaces/<your-username>/amr-guard 2>/dev/null || git remote add space https://huggingface.co/spaces/<your-username>/amr-guard
git push space master:main

3. Add Space Secrets

In your Space → Settings → Variables and Secrets, add:

Secret name	Value	Notes
MEDIC_LOCAL_MEDGEMMA_4B_MODEL	google/medgemma-4b-it	Required
MEDIC_LOCAL_MEDGEMMA_27B_MODEL	google/medgemma-4b-it	Use 4B fallback on T4
MEDIC_LOCAL_TXGEMMA_9B_MODEL	google/txgemma-2b-predict	Required
MEDIC_LOCAL_TXGEMMA_2B_MODEL	google/txgemma-2b-predict	Required
MEDIC_QUANTIZATION	4bit	Required
MEDIC_ENV	production	Required
HF_TOKEN	Your HF access token	Required (gated models)

4. First boot — knowledge base initialisation

app.py detects the HF Spaces environment (SPACE_ID env var) and automatically runs setup_demo.py on first boot to build the SQLite + ChromaDB knowledge base. This takes ~2–5 minutes once and requires no manual steps.

Enable Persistent Storage (Space Settings → Persistent Storage) so the knowledge base survives restarts. Without it, setup runs on every cold boot (~2 min overhead).

5. Drug interaction dataset (optional)

To enable full drug interaction screening, place db_drug_interactions.csv in docs/drug_safety/ before pushing, or after deployment open the Space terminal and run:

kaggle datasets download -d mghobashy/drug-drug-interactions --unzip -p docs/drug_safety/
python setup_demo.py

---

Local Setup

Requirements

• Python 3.11+
• uv for dependency management
• HuggingFace account with access to MedGemma and TxGemma

1. Install dependencies

uv sync

2. Configure environment

cp .env.example .env

Minimum required settings in .env:

MEDIC_LOCAL_MEDGEMMA_4B_MODEL=google/medgemma-4b-it
MEDIC_LOCAL_MEDGEMMA_27B_MODEL=google/medgemma-4b-it   # 4B fallback if < 24 GB VRAM
MEDIC_LOCAL_TXGEMMA_9B_MODEL=google/txgemma-2b-predict
MEDIC_LOCAL_TXGEMMA_2B_MODEL=google/txgemma-2b-predict
MEDIC_QUANTIZATION=4bit

3. Authenticate with HuggingFace

uv run huggingface-cli login

4. Build the knowledge base

uv run python setup_demo.py

Ingests EUCAST breakpoints, WHO AWaRe classification, IDSA guidelines, ATLAS surveillance data, and DDInter drug interactions into SQLite + ChromaDB. Source files are in docs/ — generated database is written to data/ (gitignored).

5. Run the app

uv run streamlit run app.py

Open http://localhost:8501 in your browser.

---

Kaggle Reproduction

The full pipeline can also be reproduced on a free Kaggle T4 GPU (16 GB VRAM):

1. Open notebooks/kaggle_medic_demo.ipynb in Kaggle
2. Add the mghobashy/drug-drug-interactions dataset to the notebook
3. Add your HuggingFace token as a Kaggle secret named HF_TOKEN
4. Run all cells — the notebook clones this repo, installs dependencies, builds the knowledge base, and launches the app via a public tunnel

Models run with 4-bit quantization on T4 (MedGemma 4B + TxGemma 2B).

---

Dynamic Form — Field Reference

The Patient Analysis form adapts based on the selected Primary infection site.

Infection site	Site-specific fields	Creatinine
Urinary	Catheter status, urinary symptoms, urine appearance	Always shown
Respiratory	O₂ saturation, ventilation status, cough type, sputum character	Always shown
Bloodstream	Central line, temperature, heart rate, respiratory rate, WBC, lactate, shock status	Always shown
Skin	Wound type, cellulitis extent, abscess, foreign body	Optional (renal flag)
Intra-abdominal	Pain location, peritonitis signs, perforation suspected, ascites	Optional (renal flag)
CNS	CSF obtained, neurological symptoms, recent neurosurgery, GCS score	Always shown
Other	No site-specific fields	Optional (renal flag)

The Suspected source dropdown adapts contextually (e.g., respiratory → CAP / HAP / VAP / Aspiration / ...).

Lab / Culture Results accepts three input modes:

• None — empirical pathway only
• Upload file — PDF (text extracted via pypdf) or image (PNG/JPG/TIFF sent to MedGemma vision)
• Paste text — manual copy-paste from a lab system

---

Knowledge Base Sources

All data is open-access — no registration required except where noted.

Source	Contents	Used for
EUCAST v16.0	Clinical breakpoint tables	MIC interpretation, creep detection
WHO AWaRe 2024	Access / Watch / Reserve classification	Antibiotic stewardship
IDSA AMR Guidance 2024	Treatment guidelines PDF	Empirical therapy RAG
Pfizer ATLAS (free registration)	6.5M MIC surveillance measurements	Resistance patterns RAG
WHO GLASS	23M+ AMR episodes, 141 countries	Global resistance context
DDInter 2.0	191,000+ drug-drug interactions	Interaction screening
OpenFDA	Drug labeling / contraindications	Safety RAG

---

Project Structure

amr-guard/
├── app.py                  # Streamlit UI — all four pages
├── setup_demo.py           # One-command knowledge base setup
├── requirements.txt        # pip requirements (HF Spaces / CI)
├── packages.txt            # apt system packages (HF Spaces)
├── pyproject.toml          # Full dependency spec (managed by uv)
├── .env.example            # Environment variable template
│
├── src/
│   ├── agents.py           # Four agent implementations
│   ├── form_config.py      # Dynamic form field definitions per infection site
│   ├── graph.py            # LangGraph orchestrator + conditional routing
│   ├── loader.py           # Model loading: multimodal + causal LM + vision inference
│   ├── prompts.py          # System and user prompts for all agents
│   ├── rag.py              # ChromaDB ingestion and retrieval helpers
│   ├── state.py            # InfectionState TypedDict schema
│   ├── utils.py            # CrCl calculator, MIC creep detection
│   ├── config.py           # Pydantic settings (reads from .env / Space Secrets)
│   ├── tools/
│   │   ├── antibiotic_tools.py   # WHO AWaRe lookups, MIC interpretation
│   │   ├── resistance_tools.py   # Pathogen resistance pattern queries
│   │   ├── safety_tools.py       # Drug interaction screening
│   │   └── rag_tools.py          # Guideline retrieval wrappers
│   └── db/
│       ├── schema.sql            # SQLite table definitions
│       ├── database.py           # Connection and query helpers
│       ├── import_data.py        # ETL: Excel/CSV/PDF → SQLite
│       └── vector_store.py       # ChromaDB ingestion
│
├── docs/                   # Source data files (committed — used by setup_demo.py)
│   ├── antibiotic_guidelines/   # WHO AWaRe Excel exports, IDSA PDF
│   ├── mic_breakpoints/         # EUCAST v16.0 breakpoint tables
│   ├── pathogen_resistance/     # ATLAS susceptibility data
│   └── drug_safety/             # DDInter drug interaction CSV
│
├── notebooks/
│   └── kaggle_medic_demo.ipynb  # Full reproducible Kaggle notebook
│
└── tests/
    └── test_pipeline.py         # Agent and pipeline unit tests

---

Research demo only. Not validated for clinical use. All recommendations must be reviewed by a licensed clinician before any patient-care decision.