How MedLit Works
MedLit is a Retrieval-Augmented Generation (RAG) system that transforms structured clinical data into plain-language health summaries. It combines real medical coding standards (FHIR, SNOMED CT, RxNorm, LOINC), authoritative reference APIs (MedlinePlus, openFDA), and LLM generation with readability validation. Every explanation is grounded in verifiable sources. The LLM never generates from training data alone.
End-to-End Pipeline
Data flows from FHIR bundles through reference lookups, prompt construction, LLM generation, and readability scoring.
Data Sources & Standards
FHIR R4 Bundles
Patient data follows the HL7 FHIR R4 standard, the same format used by Epic, Cerner, and every US hospital system. Demo patients include hand-crafted Synthea bundles and live data pulled from the public HAPI FHIR server via the Patient/$everything endpoint.
Clinical Terminologies
Each clinical concept is identified by a code from the international standard terminology systems. These codes drive the reference API lookups and enable interoperability across healthcare systems.
MedlinePlus Connect
Free API from the National Library of Medicine. Returns patient education content for any SNOMED, RxNorm, or LOINC code. This is the primary grounding source. Every explanation cites NLM content rather than relying on LLM training data.
connect.medlineplus.gov · No auth required · 100 req/minopenFDA Drug Labels
FDA-approved drug labeling via the openFDA API. MedLit fetches the drug interactions section for each medication by RxNorm code. This provides authoritative, regulatory-grade interaction data that the LLM uses to explain potential drug-drug interactions.
api.fda.gov · No auth required · 240 req/minRAG Grounding Strategy
The LLM receives four layers of context in every prompt. This grounding strategy ensures explanations are factual and traceable to authoritative sources rather than generated from the model's training data alone.
Health Summary Generation
Parallel Data Retrieval
For each patient, MedlinePlus and openFDA are queried in parallel for every condition and medication. MedlinePlus provides patient education text; openFDA provides the FDA-approved drug interactions section. Results are cached for 24 hours.
Structured Prompt Construction
A RAG prompt is built with the patient's FHIR data (conditions, medications, lab values), all retrieved MedlinePlus references, FDA drug interaction text, and the target reading level (5th, 8th, or 12th grade). The LLM is instructed to return structured JSON sections.
LLM Generation
The prompt is sent to Llama 3.1 8B via the Groq API (for production) or a local Ollama instance (for development). The provider abstraction layer allows swapping models without code changes, which is useful for evaluation across model sizes.
Structured Output Parsing
The LLM's JSON response is parsed into five sections: Your Conditions, Your Medications, Important Interactions, Lab Results, and Key Takeaways. If parsing fails, the system falls back to rendering the raw text.
Readability Validation
The generated text is scored using Flesch-Kincaid Grade Level (maps to US school grade) and the Gunning Fog Index (years of education needed). These validate that the reading level instruction was followed. Both scores are displayed to the user.
Persistent Caching
The complete response (sections, readability scores, sources) is cached to disk. Subsequent requests for the same patient and reading level are served instantly without an LLM call. The cache survives container restarts.
System Architecture
Frontend
Next.js 14 + React + Tailwind CSS
Server-side rendering, client components for interactive elements, middleware-based authentication
Backend
FastAPI + Python 3.12
Async API with FHIR parsing (fhir.resources), MedlinePlus/openFDA clients, LLM provider abstraction
Infrastructure
Docker Compose + nginx + Let's Encrypt
SSL termination, reverse proxy routing, deployed to a cloud VPS with automated certificate management
Evaluation & Research
Model Comparison Framework
An evaluation script generates the same prompts across multiple LLM providers (Groq Llama 8B, Llama 70B, Claude) and compares readability scores, latency, and output quality. Results are exported as CSV/JSON for analysis.
Grounding Depth as a Research Variable
The system can be configured to include or exclude grounding sources (MedlinePlus only, MedlinePlus + openFDA, or no grounding). This enables controlled experiments measuring how grounding depth affects hallucination rates and factual accuracy.
Open Research Questions
- →Does readability scoring correlate with actual patient comprehension? (Requires user study)
- →Can a condition-comorbidity knowledge graph improve multi-condition summaries?
- →How does grounding depth affect hallucination rates across model sizes?
- →What is the minimum viable model size for health literacy applications?
- →Can the system detect when grounding is insufficient to safely explain an interaction?
Data Integrity & Safety
No Real PHI
All patient data is synthetic (Synthea-generated) or from a public test server (HAPI FHIR). No protected health information is stored or processed.
Source Attribution
Every generated explanation links back to MedlinePlus articles and openFDA drug labels. Users can verify any claim against the original source.
Medical Disclaimer
All explanations carry a disclaimer that they are for educational purposes only and do not constitute medical advice.
See it in action
Sign in to explore patient health summaries, medication explanations, and readability-scored outputs.
Sign in to MedLit