# Project export: MedRAG This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: UC Berkeley AI Hackathon 2026 - Tagline: AI-powered medication decision support — synthesizing patient FHIR data and RAG-retrieved clinical knowledge to help physicians prescribe safely. - Devpost: https://devpost.com/software/medrag-m4x6qv - GitHub: https://github.com/anthonychen1925/MedRAG - Video: https://www.youtube.com/embed/ME1FFIYFea4?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 2 GitHub contributor(s) — Anthony Chen (11 commits), Cursor (1 commits) ## Devpost submission (written by the team) ### Inspiration Medication errors are one of the most preventable causes of patient harm, but managing polypharmacy in real time is genuinely hard. A physician considering a new drug for a patient on ten medications with kidney disease can't realistically cross-reference every interaction and contraindication on the spot. We wanted to build a tool that takes a patient's record, a proposed drug, and a clinical question, and returns a structured, grounded safety report. ### What it does MedRAG lets a physician upload a FHIR R4 patient bundle, enter a proposed medication and their clinical question, and receive a structured safety report covering drug–drug interactions, contraindications, lab flags, and monitoring recommendations. Every claim is cited back to a retrieved source — openFDA drug labels, DDInter 2.0 interaction pairs, or openFDA FAERS adverse-event data — and the system explicitly flags what it doesn't know. The physician makes the final call. ### How we built it We built a RAG pipeline backed by Redis 8 native vector sets. An ingestion script pulls FDA drug labels, DDInter interaction pairs, and FAERS adverse-event signals for ~270 generics, chunks and embeds them with a local BGE model, and stores them in Redis. At query time, we parse the uploaded FHIR bundle, run source-balanced retrieval with per-source quotas to ensure interaction, label, and safety data are all represented, assemble a structured prompt, and send it to Claude Opus 4.8. The report comes back with numbered chunk citations that the Flask UI renders as clickable links to the original sources. Challenges we faced We ran the BGE embedding model entirely on CPU, which made ingestion slow and required careful optimization to get through ~20k chunks in a reasonable time. We also had no access to real patient data since it's private, so we relied entirely on synthetic FHIR bundles generated by Synthea to build and test the pipeline. ### Accomplishments we're proud of We're also proud that the system is honest about its limits: it never tells a physician an interaction wasn't found when it really means the pair wasn't in the index. ### What we learned Local embeddings with BAAI/bge-large-en-v1.5 gave us strong retrieval quality at zero API cost, which made rapid iteration during development practical. ## README (from the GitHub repository) # MedRAG — Medication Decision Support via RAG A Retrieval-Augmented Generation system that helps physicians evaluate whether a new medication is appropriate for a specific patient, given their medical history, active diagnoses, and current medication regimen. --- ## What This System Does When a physician is considering prescribing a new drug, MedRAG: 1. Accepts a **FHIR R4 patient bundle** (`.json`) uploaded by the physician and parses it into a structured clinical summary. 2. Accepts a **proposed medication** and a **free-text clinical question** from the physician. 3. Retrieves the most relevant medical knowledge from a curated index (openFDA drug labels, DDInter 2.0 interaction pairs, openFDA FAERS adverse-event signals). 4. Feeds the parsed patient record + retrieved documents to **Claude Opus 4.8**, which reasons over the combined context. 5. Returns a structured safety report covering interactions, contraindications, relevant lab flags, monitoring recommendations, and a top-line recommendation. The physician reviews this report and makes the final prescribing decision. --- ## System Architecture ``` ── INDEX BUILD (ingest.py, runs once) ─────────────────────────────── Three sources (free, citable): • openFDA drug labels (per-drug safety/dosing) • DDInter 2.0 (severity-rated interaction pairs) • openFDA FAERS (real-world adverse-event signals) ▼ Chunker │ Section-level chunking with metadata │ (source, drug name, section type, date, verification URL) ▼ BGE (BAAI/bge-large-en-v1.5, local, 1024-dim) │ Embed each chunk → vector (no API cost) ▼ Redis 8 Vector Set (redis-py client) │ Store vectors + JSON attributes (VADD); search with VSIM, │ with server-side attribute FILTER for source/section ── QUERY (runs per physician request) ─────────────────────────────── Physician Input │ (1) FHIR R4 .json file upload │ (2) Proposed medication (name, dose, indication) │ (3) Free-text clinical question ▼ FHIR Parser │ Extract: Patient, MedicationRequest, Condition, │ AllergyIntolerance, Observation resources │ Output: structured patient record + data quality flags ▼ Source-balanced Retrieval (retrieval.py) │ Multiple targeted BGE-embedded queries with guaranteed quotas: │ • per-pair interaction chunk for EACH current medication │ • proposed drug's label safety profile │ • renal dose-adjustment chunk (if reduced kidney function) │ • proposed drug's FAERS adverse-event signal │ • general fill to the remaining budget ▼ Prompt Assembler │ Combine: parsed patient record + retrieved chunks + │ proposed medication + physician question ▼ Claude Opus 4.8 ◄──── CONTEXT.md defines behavior here │ Reason, synthesize, flag gaps, apply severity scale, │ cite each grounded claim as [chunk N] ▼ Structured Report (with clickable citations → source URLs) │ Recommendation · Interactions · Contraindications · │ Lab Flags · Monitoring · Alternatives · Uncertainty │ References panel: DailyMed · DDInter drug page · FAERS viewer ▼ Physician Review Interface (Flask, app.py — single process serves UI + pipeline) ``` --- ## How It Runs (Runtime) MedRAG is a **single-process Flask application**. There is no separate frontend server — `app.py` renders the styled UI and orchestrates the full pipeline in one Python process. The static files in `frontend/` are design mockups only; the live UI is embedded in `app.py`. ### Processes required at runtime | Process | Purpose | Start command | |---|---|---| | **Redis 8** | Stores ~20k embedded knowledge chunks | `brew services start redis` or `redis-server` | | **Flask app** | UI + pipeline orchestration | `source .venv/bin/activate && python app.py` | The **BGE embedding model** is loaded into RAM when `app.py` starts (not on every request). You will see: ``` [MedRAG] Loading embedder… [MedRAG] Embedder ready. * Running on http://127.0.0.1:5001 ``` The app listens on **port 5001** (5000 is often occupied by macOS AirPlay). Open **http://127.0.0.1:5001** in a browser. > **Use the `.venv` Python.** Running `python app.py` from conda base or system Python will fail at analysis time because `sentence-transformers` is installed in the project venv only. ### Startup sequence (`python app.py`) 1. Load settings from `.env` via `config.py` 2. Preload **BGE** (`BAAI/bge-large-en-v1.5`) — takes ~10–30 seconds on first start 3. Start Flask on `127.0.0.1:5001` (debug mode on, auto-reloader **off** — the reloader conflicts with ML model loading) The embedder is cached as a **process singleton** in `embeddings.py` so it is loaded once per server lifetime. ### Per-request flow (when you submit an analysis) 1. **FHIR parse** (`fhir_parser.py`) — uploaded `.json` (or demo patient) → structured patient record + data quality flags 2. **Retrieval** (`retrieval.py`) — multiple targeted vector searches against Redis (~14 chunks max by default): - Best interaction chunk per current medication (DDInter) - Proposed drug's label safety sections (openFDA → DailyMed) - Renal dose chunk if patient has reduced kidney function - FAERS adverse-event signal for the proposed drug - General semantic fill to the remaining budget 3. **Prompt assembly** (`prompt_assembly.py`) — patient + chunks + proposed drug + question 4. **Claude Opus 4.8** (`api_client.py`) — `CONTEXT.md` as system prompt; returns markdown report with `[chunk N]` citations (~30–60 s) 5. **Report render** (`app.py`) — markdown parsed into styled section cards; citations link to References & Sources panel ### Index build vs. query | Step | When | Command | |---|---|---| | **Index build** | One-time (or when drugs/sources change) | `python ingest.py --recreate` (~25 min, ~20k chunks) | | **Query / UI** | Every session | `python app.py` (requires Redis already populated) | `ingest.py` is **not** run on every startup. ## Tech Stack ### Core pipeline | Layer | Technology | Role | |---|---|---| | **Language** | Python 3.11+ | Entire backend pipeline, ingestion, retrieval, and web server | | **Reasoning engine** | [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python) → **Claude Opus 4.8** (`claude-opus-4-8`) | Reads retrieved chunks + patient record; generates structured safety report. System prompt = `CONTEXT.md`. | | **Embedding model (default)** | [sentence-transformers](https://github.com/UKPLab/sentence-transformers) → **BGE** `BAAI/bge-large-en-v1.5` (1024-dim, via [Hugging Face Hub](https://huggingface.co/BAAI/bge-large-en-v1.5)) | Local document/query embeddings for semantic search — no per-embedding API cost | | **Embedding model (optional)** | [Voyage AI SDK](https://github.com/voyage-ai/voyageai-python) → `voyage-3-large` | Cloud embeddings when `EMBED_PROVIDER=voyage` | | **Vector database** | **Redis 8** native **vector sets** via [redis-py](https://github.com/redis/redis-py) (`redis>=5.0.0`) | Stores ~20k chunk embeddings + JSON metadata. Commands: `VADD`, `VSIM`, `VGETATTR`, `VSETATTR`, `VCARD`. Cosine KNN with server-side `FILTER` on attributes. | | **Numerics** | [NumPy](https://numpy.org/) | Vector serialization (FLOAT32), stub embedder, similarity ops | | **Config** | [python-dotenv](https://github.com/theskumar/python-dotenv) | Loads `.env` secrets and tuning parameters | | **HTTP client** | [Requests](https://requests.readthedocs.io/) | Fetches openFDA APIs and DDInter CSVs during ingestion | ### Web UI & orchestration | Layer | Technology | Role | |---|---|---| | **Web framework** | [Flask](https://flask.palletsprojects.com/) 3.x (`app.py`) | Single process: serves UI, orchestrates pipeline, hosts FAERS viewer at `/source/faers/` | | **Templating** | Jinja2 (via Flask `render_template_string`) | Server-side HTML for setup page, report cards, and FAERS viewer | | **CSS / styling** | [Tailwind CSS](https://tailwindcss.com/) (CDN) | Dark glass-panel "bento" layout | | **Typography [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 15 recognized source files, 198 KB. - Anthropic (technology) — detected in the code - Flask (technology) — detected in the code - HTML (language) — detected in the code - Python (language) — detected in the code - Redis (technology) — detected in the code - AI coding agent: Cursor — evidence: commit authorship or trailers ## Codebase structure (from repository index) ### Files (23 of 23) ``` .env.example .gitignore api_client.py app.py config.py CONTEXT.md data/drug_list.txt embeddings.py fhir_parser.py frontend/index.html frontend/report.html frontend/setup.html ingest.py LICENSE prompt_assembly.py README.md requirements.txt retrieval.py run_case.py synthetic_patients/ckd4_metformin_contraindication.json synthetic_patients/elderly_polypharmacy.json synthetic_patients/low_risk_statin_control.json vector_store.py ``` ### Dependencies - requirements.txt: anthropic@>=0.40.0, flask@>=3.0.0, numpy@>=1.26.0, python-dotenv@>=1.0.0, redis@>=5.0.0, requests@>=2.31.0, sentence-transformers@>=3.0.0, voyageai@>=0.3.0 ### Recent commits (newest first) - Update README and Context - Update README and context, fix faers link to be human readable. Project MVP is completed - app.py and frontend changed - Updated README and context file - Fixed links for DDInter 2.0 - Stop tracking generated/licensed data (dump.rdb, DDInter CSVs) - Merge remote-tracking branch 'origin/main' - Increased chunks in vector DB - Add frontend: landing page, patient setup, and clinical safety report - RAG prototype - Add files via upload - Add files via upload - Initial commit ## Key source files (fetched from GitHub, selected and truncated for size) ### CONTEXT.md ```markdown # MedRAG: Medication Decision Support System — Context for Claude Opus 4.8 ## What You Are You are the reasoning engine inside **MedRAG**, a Retrieval-Augmented Generation (RAG) system designed to assist licensed physicians in making informed decisions about prescribing new medications to patients. You are **not** a replacement for clinical judgment — you are a decision-support tool that synthesizes retrieved medical knowledge with patient-specific context and surfaces the most relevant safety considerations. --- ## System Stack MedRAG is built from the following tools and frameworks. You do not call these directly — they run upstream of you — but understanding them helps you interpret what the retrieved context represents and what the system can and cannot do. ### Runtime infrastructure | Component | Technology | Role | |---|---|---| | **Web server / orchestrator** | Flask (`app.py`) | Receives physician input, runs parse → retrieve → prompt → your API call → renders report | | **Vector database** | Redis 8 (native vector sets via `redis-py`) | Stores ~20k embedded knowledge chunks; queried with `VSIM` cosine KNN + attribute `FILTER` | | **Embedding model (default)** | BGE `BAAI/bge-large-en-v1.5` via `sentence-transformers` (Hugging Face Hub) | Embeds retrieval queries at request time; preloaded once at server startup | | **Embedding model (optional)** | Voyage AI `voyage-3-large` | Cloud alternative when `EMBED_PROVIDER=voyage` | | **Reasoning engine** | Claude Opus 4.8 via Anthropic SDK | **You.** System prompt = this file (`CONTEXT.md`) | | **Config** | `python-dotenv` + `.env` | API keys, Redis URL, retrieval tuning | | **Numerics** | NumPy | Vector serialization and similarity operations | ### Patient input | Component | Technology | Role | |---|---|---| | **Patient data format** | FHIR R4 Bundle (`.json`) | Uploaded by physician or loaded from demo/CLI | | **Parser** | `fhir_parser.py` | Extracts `Patient`, `MedicationRequest`, `Condition`, `AllergyIntolerance`, `Observation` | | **Coding systems** | LOINC (labs/vitals), ICD-10 (diagnoses) | Parsed from FHIR resources when present | | **Demo data generator** | Synthea | Recommended for synthetic FHIR R4 test patients | ### Knowledge base (indexed in Redis) | Source | Access | What it contributes | |---|---|---| | **openFDA Drug Label API** | `api.fda.gov/drug/label.json` | FDA structured product labels (contraindications, warnings, dosing, etc.) — cited via **DailyMed** | | **DDInter 2.0** | Downloadable CSVs + web drug-detail pages | Severity-rated drug–drug interaction pairs (Major / Moderate / Minor) | | **openFDA FAERS API** | `api.fda.gov/drug/event.json` | Most-reported adverse events per drug (spontaneous reports; signal only) — cited via MedRAG FAERS viewer | Index built by `ingest.py` using **Requests** to fetch APIs/CSVs, **BGE** to embed chunks, and **Redis `VADD`** to store vectors + metadata. ~270 drugs from `data/drug_list.txt`, ~20k chunks total. ### UI renderi [truncated — 16463 more characters] ``` ### requirements.txt ``` # Core pipeline redis>=5.0.0 # Redis 8 client (native vector sets: VADD/VSIM/VGETATTR) sentence-transformers>=3.0.0 # local BGE embeddings (default, no API cost) anthropic>=0.40.0 # Claude Opus 4.8 reasoning engine # Optional cloud embedding provider (only needed if EMBED_PROVIDER=voyage) voyageai>=0.3.0 # voyage-3-large embeddings # Web framework + utilities flask>=3.0.0 # physician-facing UI / orchestration python-dotenv>=1.0.0 # load API keys / config from .env requests>=2.31.0 # openFDA / DailyMed ingestion numpy>=1.26.0 # vector ops + stub embedder ``` ### app.py ```python """MedRAG web UI. A single-file Flask app that orchestrates the pipeline: FHIR upload -> parse -> retrieve -> assemble prompt -> Claude -> report. The UI keeps the dark, glass-panel "bento" aesthetic of the frontend/ mockups (index.html, setup.html, report.html) while being fully wired to the backend: Claude's markdown report is parsed into sections and rendered as styled cards, with the recommendation shown as a status badge and clickable [chunk N] citations linking to a References & Sources panel. Run: python app.py then open http://127.0.0.1:5001 """ from __future__ import annotations import html import json import re import traceback import urllib.parse from flask import Flask, abort, render_template_string, request, url_for from config import settings from fhir_parser import parse_fhir_bundle from prompt_assembly import build_prompt from ingest import FAERS_TOP_N, OPENFDA_EVENT_URL, fetch_faers_reactions from retrieval import retrieve_chunks app = Flask(__name__) FAERS_DASHBOARD_URL = ( "https://www.fda.gov/drugs/surveillance/questions-and-answers-fda-adverse-event-" "reporting-system-faers/fda-adverse-event-reporting-system-faers-public-dashboard" ) DEMO_PATH = "synthetic_patients/elderly_polypharmacy.json" # Shared : Tailwind config + theme tokens + report-body styling. Mirrors # the design language of the frontend/ mockups. HEAD = """ MedRAG — Medication Decision Support