Public Drug Adverse Event RAG

No-PHI/no-PII MVP for exploring public drug adverse-event signals with citation-first retrieval from openFDA, FDA labels, RxNorm, and PubMed.

No PHI / PII Policy

This app is designed for public data only. Do not enter patient names, dates of birth, addresses, phone numbers, emails, MRNs, insurance IDs, Aadhaar numbers, SSNs, hospital IDs, or exact clinical record details.

The backend runs a PII guard before public API calls. Inputs with obvious identifier patterns are rejected with HTTP 400 and should not be persisted. The MVP does not include patient uploads.

Medical Disclaimer

FAERS/openFDA reports are spontaneous reports and do not prove causality. Counts are not incidence rates because total drug exposure is unknown. Reports may be incomplete, duplicated, biased, or confounded. This tool is for research and education, not medical advice. Consult a qualified clinician for medical decisions.

The app must not produce diagnosis, treatment recommendations, dosage recommendations, emergency triage decisions, patient-specific risk conclusions, or causality conclusions.

Data Sources

• openFDA Drug Adverse Event API: https://api.fda.gov/drug/event.json
• openFDA Drug Label API: https://api.fda.gov/drug/label.json
• RxNorm API: https://rxnav.nlm.nih.gov/REST/
• PubMed E-utilities: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

Local Setup

Copy the example environment file:

Copy-Item .env.example .env

Backend:

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:3000.

Docker Compose

Docker is optional for local development:

Copy-Item .env.example .env
docker compose up --build

Services:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• PostgreSQL: localhost:5432

Environment Variables

• OPENFDA_API_KEY: optional openFDA key.
• NCBI_API_KEY: optional NCBI API key.
• NCBI_TOOL: NCBI tool name, defaults to public-drug-adverse-event-rag.
• NCBI_EMAIL: recommended contact email for NCBI E-utilities.
• DATABASE_URL: SQLAlchemy PostgreSQL URL.
• CORS_ORIGINS: comma-separated frontend origins. Trailing slashes are normalized.
• VITE_API_BASE_URL: browser-visible backend URL for the Vite frontend.
• EVIDENCE_QA_ENABLED: optional Evidence Q&A feature flag, defaults to true.
• OPENAI_API_KEY: optional primary provider key for Evidence Q&A.
• OPENAI_MODEL: optional OpenAI answer model.
• OPENAI_EMBEDDING_MODEL: optional OpenAI embedding model, defaults to text-embedding-3-small.
• GEMINI_API_KEY: optional backup provider key used only when OPENAI_API_KEY is empty.
• GEMINI_MODEL: optional Gemini answer model, defaults to gemini-2.5-flash.
• GEMINI_EMBEDDING_MODEL: optional Gemini embedding model, defaults to models/gemini-embedding-001.
• RAG_TOP_K: number of vector chunks used for Evidence Q&A, defaults to 8.
• RAG_EMBEDDING_DIMENSIONS: shared pgvector embedding size, defaults to 768.

Running Tests

Backend:

cd backend
python -m pytest

Frontend build:

cd frontend
npm run build

Example Queries

• Drug: semaglutide; adverse event: pancreatitis
• Drug: metformin; adverse event: lactic acidosis
• Drug: atorvastatin; adverse event: myopathy

Use only non-identifying public drug and event terms.

API Overview

• GET /health
• POST /api/normalize-drug
• POST /api/adverse-events/search
• POST /api/adverse-events/aggregate
• POST /api/label/search
• POST /api/pubmed/search
• POST /api/signal/calculate
• POST /api/brief/generate
• GET /api/evidence/status
• POST /api/evidence/ask

Known Limitations

• FAERS reports are spontaneous reports and are not incidence estimates.
• openFDA drug names are not systematically normalized across all reports.
• Label search uses retrieved openFDA label sections and simple term matching.
• PubMed abstracts provide supporting literature context only.
• Signal metrics are exploratory and depend on query quality and reporting biases.
• The deterministic brief generator does not use an LLM.
• Evidence Q&A is optional and requires OpenAI or Gemini configuration plus pgvector-backed PostgreSQL.
• Evidence Q&A uses pgvector when available. If a hosted PostgreSQL service does not expose the vector extension, the backend falls back to DB-backed JSONB embeddings with application-side cosine search scoped to the active query.
• Gemini is a backup provider only when the OpenAI key is empty, not a retry fallback after OpenAI failures.

Future Roadmap

• VAERS support
• MAUDE device events
• CAERS food, supplement, and cosmetic events
• EudraVigilance summary integration
• Bulk FAERS ingestion
• Advanced MedDRA normalization
• Drug synonym expansion
• Literature quality scoring
• Export PDF report
• Organization workspace with audit logs
• Fully de-identified upload workflow