Case study
MedLit: medical records, explained at your reading level
A grounded pipeline that turns FHIR records into cited plain-language explanations. Built solo as graduate research, in the same months the entire industry converged on the same architecture.
The problem
Patients got their records. They didn’t get understanding.
Federal information-blocking rules require providers to hand patients their electronic health information, and portals satisfy the rule with raw data: “Essential hypertension (disorder), SNOMED 59621000,” medications by clinical name, lab values with no context. About 36% of US adults have basic or below-basic health literacy. The channel that empowers patients also overwhelms them.
The obvious shortcut, pasting a chart into a general-purpose chatbot, has a measured accuracy problem: in one JMIR study, GPT-4 fully correctly answered only 46.7% of patient lab-interpretation questions. Generation is commodity. Disciplined grounding is not.
The approach
Three rules the system never breaks
Grounded in sources you can check
The patient's own SNOMED, RxNorm, and LOINC codes key retrieval from NIH MedlinePlus, FDA drug labels, and RxNav. The model personalizes and simplifies retrieved content instead of generating claims, and every response returns its citations.
Labs never touch the model
Reference ranges decide normal versus abnormal deterministically. A model cannot hallucinate a lab value into range because the model is not in that code path.
Reading levels measured, never assumed
Every output is post-scored with Flesch-Kincaid and Gunning Fog, so the interface shows the realized reading level instead of trusting that the prompt's instruction landed.
01 · The record, readable
One patient, one page, plain language
A patient’s conditions, medications, and labs arrive as coded FHIR entries and leave as a structured summary a person can act on. Medications show the name from the pill bottle (Spiriva, not just tiotropium bromide) via RxNav, interactions come from the FDA label, and each abnormal lab is flagged by its reference range, never by the model’s opinion.
02 · Receipts included
Every explanation shows its sources and its score
Each generated explanation carries a “Grounded in” panel linking to the exact MedlinePlus, openFDA, and RxNav references behind it, plus a readability badge computed on the output text. Toggle between Simple, Standard, and Detailed and the score updates, measured each time.
03 · Try it in one click
A demo that costs nothing to run
Eight synthetic patients with real clinical coding, a one-click demo session, and a pre-generated explanation cache, so the live site answers instantly and never touches an API key. The repo runs locally the same way: docker compose up, no accounts required.
Enter the demo →
By the numbers
01234567890123456789
sources
MedlinePlus, openFDA, RxNav, LOINC, and FHIR ground every claim
01234567890123456789
LLM calls
in lab interpretation; reference ranges decide
01234567890123456789
reading levels
each scored on the output, never assumed
01234567890123456789
wrong codes
caught by the validator in the synthetic data
What the build surfaced
The synthetic data was lying
During a review, a physician panelist noticed a medication card citing a topic for ticagrelor, a blood thinner, under a tiotropium label, a COPD inhaler. The pipeline was correct. The code in the synthetic record was wrong. The fix became a validator that checks every coded value against its authoritative source; it caught two more wrong medications and several deprecated codes. If a pipeline joins coded clinical data with external knowledge, it needs to validate code and display consistency at ingest.
The evaluation also replicated a published finding: even prompted for 5th grade, output floors near grade 7.7 (Flesch-Kincaid rose 7.7, 8.1, 9.4 across the three levels, monotonic and in the right direction, and still floored above the Simple target). Lifting that floor is an open research question the system is instrumented to explore.
The timing
Epic, OpenAI, Anthropic, Google, Amazon, and Microsoft all shipped patient-facing record explanation within months of this build. None of us were copying each other. The problem was ripe, and everyone landed on the same shape.