35 days. 5 build projects.
Every concept in RAG: from “what is an embedding” to self-correcting agentic systems with hallucination guards.

Today we put everything into one system.

Not a demo. Not a tutorial exercise. A production-pattern clinical decision support agent that ingests multi-source clinical data, routes queries through a LangGraph state machine, retrieves with hybrid search and reranking logic, generates cited answers with confidence scores, self-corrects when retrieval is insufficient, logs every decision for audit, and evaluates itself with RAGAS metrics.

If you have followed this series, you already understand every component. Today you see them work together - the way a real clinical AI system operates.

This notebook is your portfolio piece. It demonstrates mastery of the most in-demand AI skill in healthcare. It’s the project you show in job interviews, present to your CMIO, or use as the foundation for your institution’s clinical AI initiative.

What Makes This Different From Every Previous Build Project

Every row shows a capability that was introduced at some point in the series. Day 35 combines all of them.

The Architecture: A Multi-Agent Clinical System

A paid subscriber recently asked a great question:

“How do multi-agent systems actually work in practice? I want to see agents with different roles communicating with each other.”

This capstone answers that question directly.

The system has five specialized agents: each with a specific role, specific tool access, and specific expertise - orchestrated by a central LangGraph state machine:

Agent 1: The Triage Agent

Role: Classify incoming queries:

• Is this clinical?

• Which domain does it belong to: heart failure, renal, pharmacology, electrolytes?

Tools: LLM classifier with clinical taxonomy.

Analogy: The ED triage nurse who assesses acuity and routes to the right department.

Agent 2: The Retrieval Agent

Role: Search the right knowledge sources based on the triage classification.

• Execute hybrid retrieval (semantic + keyword).

• Apply metadata filters.

Tools: Multiple FAISS indices, BM25 retriever, metadata filter engine.

Analogy: The medical librarian who knows exactly which shelf, which book, which chapter has the answer.

Agent 3: The Grading Agent

Role: Evaluate retrieved documents for relevance.

• Decide: proceed to generation, or rewrite the query and re-retrieve?

Tools: LLM grader with clinical relevance criteria.

Analogy: The senior resident who reviews the literature search before it reaches the attending.

“Did you actually find the renal dosing data, or just the general heart failure guideline?”

Agent 4: The Generation Agent

Role: Synthesize a cited, confidence-scored clinical answer from the retrieved evidence.

• Apply the production system prompt with citation rules, safety caveats, and “I don’t know” behavior.

Tools: LLM with clinical system prompt, confidence scorer.

Analogy: The consulting physician who reads the evidence and writes the recommendation.

Agent 5: The Evaluation Agent

Role: Verify that the generated answer is grounded in the retrieved documents. Score faithfulness. Flag hallucinations. Run RAGAS metrics on demand.

Tools: LLM fact-checker, RAGAS evaluation suite.

Analogy: The quality assurance pharmacist who double-checks every prescription against the reference before it reaches the patient.

How They Communicate

Here’s the key insight most people miss about multi-agent systems: agents don’t chat freely. They share state through a structured, typed state dictionary - the same ClinicalAgentState from Day 33, now expanded with evaluation fields.

The central orchestrator is the LangGraph state machine itself: it routes between agents based on conditional edges.

No agent decides independently what to do next. The graph decides. This is what makes the system reliable: the routing logic is explicit, testable, and auditable.

Context passing is everything. If the Evaluation Agent doesn’t receive the exact documents the Generation Agent used, it can’t verify grounding. The typed state guarantees every agent has access to the complete context: like every clinician working from the same patient chart.

The RAGAS Evaluation Pipeline

The capstone includes a complete evaluation pipeline that you can run on demand or schedule nightly:

Step 1: Define test queries with expected answers and expected source documents (the test set from Day 34).

Read more

But here’s the question nobody wants to ask: how do you know they are correct?

A RAG system that sounds right and is right are two very different things.

In healthcare, the gap between them is where patients get hurt.

Today you learn how to measure it.

The Problem with Eyeballing

Most RAG developers evaluate their systems by reading a few answers and thinking: “That looks good.” This is like a pharmaceutical company testing a drug by having the CEO take it once and saying “I feel fine.”

It’s not evaluation. It’s hope.

Real evaluation requires:

• Multiple test queries covering easy, hard, and edge cases

• Quantitative metrics that produce numbers, not feelings

• Specific diagnostics that tell you which part of the pipeline is failing

RAGAS (Retrieval Augmented Generation Assessment Suite) gives you all three.

Subscribe now

The Five Metrics That Matter

RAGAS provides a toolkit of metrics. Five are essential for healthcare RAG. Each measures a different part of the pipeline.

1. Context Precision: Is the retriever finding the right documents?

What it measures: Of the chunks your retriever returned, how many are actually relevant to the query?

The analogy: You ask the medical librarian for articles about warfarin dosing in renal impairment. They return 5 articles. Context precision asks: how many of those 5 are actually about warfarin dosing in renal impairment? If 4 of 5 are relevant, precision is 0.80. If only 2 are relevant and the other 3 are about general anticoagulation, precision is 0.40.

Interpretation:

Clinical priority: Medium. Important for efficiency, but downstream metrics matter more for patient safety.

2. Context Recall: Is the retriever finding ALL the right documents?

What it measures: Of all the documents that should have been retrieved, how many did the retriever actually find?

The analogy: There are 3 guideline sections relevant to warfarin renal dosing in your knowledge base. The retriever found 2 of them. Context recall is 0.67. It missed one — and that missing section might contain the critical dose adjustment.

Interpretation:

The precision-recall tradeoff: High precision with low recall means you’re finding good documents but missing important ones. High recall with low precision means you’re finding everything but burying it in noise. The goal is both above 0.80.

Clinical priority: High. Missing a critical guideline section is a patient safety issue.

3. Faithfulness: Is the answer grounded in the retrieved context?

What it measures: Of all the claims in the generated answer, how many are supported by the retrieved documents? This is the hallucination detector.

The analogy: The LLM generates an answer with 10 clinical claims. RAGAS checks each one against the retrieved context. 8 claims are directly supported by the documents. 2 claims were added from the LLM’s training data: fabricated or unsourced. Faithfulness score: 0.80.

Interpretation:

Clinical priority: THE HIGHEST.

Faithfulness is the single most important metric for healthcare RAG.

A system that adds clinical claims from training data (a fabricated dose, an invented trial, a hallucinated contraindication) is actively dangerous. This is the metric your CMIO should see first.

4. Factual Correctness: Is the answer actually true?

What it measures: Are the claims in the generated answer factually correct when compared against a ground truth reference?

The analogy: The answer says “target INR for mechanical mitral valve is 2.5–3.5.” The ground truth reference confirms this is correct.
Factual correctness: ✓.
If the answer said “target INR is 2.0–3.0” (wrong - that’s for AFib, not mechanical valves), factual correctness catches it.

How it differs from faithfulness: Faithfulness checks if the answer matches the retrieved documents. Factual correctness checks if the answer matches reality. An answer can be faithful to a bad document and still be factually wrong. An answer can be unfaithful (adding training data) and happen to be factually correct.

Interpretation:

Clinical priority: Very high. Paired with faithfulness, these two metrics are non-negotiable.

5. Response Relevancy: Does the answer address the question?

What it measures: How well does the generated answer address the specific question that was asked?

The analogy: You ask about warfarin dosing in renal impairment. The answer discusses warfarin drug interactions extensively but barely mentions renal dosing. The information is correct and grounded - but it doesn’t answer your question. Response relevancy catches this mismatch.

Interpretation:

Clinical priority: Medium. Important for usability, but less critical than faithfulness and factual correctness for safety.

The Healthcare Priority Stack

Not all metrics are equal in clinical settings. Here’s how to prioritize:

The rule: Faithfulness and factual correctness must be above threshold before you even look at the others. A system with 0.99 context precision but 0.60 faithfulness is dangerous - it finds the right documents but generates hallucinated answers from them.

Diagnosing Failures with RAGAS

The power of RAGAS isn’t just the scores - it’s knowing where to fix problems:

The last row is critical: If your system is faithfully quoting an outdated 2019 guideline, faithfulness will be high but factual correctness will be low.
The fix isn’t in the RAG pipeline - it’s in the knowledge base.

Remove or update the outdated source documents.

This is Day 13’s Failure Mode 4 (stale chunks) surfacing in evaluation.

Building Your Test Set

RAGAS needs test data: queries, expected retrieved documents, and reference answers. For healthcare RAG:

Start with 20–30 test queries covering:

• Simple factual questions (5–10): “What is the target dose of carvedilol for HFrEF?”

• Complex multi-factor questions (5–10): “Should I start an MRA with eGFR 28 and K+ 4.9?”

• Edge cases (5): Questions at the boundary of your knowledge base

• Out-of-scope questions (3–5): Questions your system should decline to answer

• Adversarial questions (2–3): Questions designed to trigger hallucination

Write reference answers for each query - the gold standard. For clinical RAG, have a clinician write or validate these references.

Map expected source documents for each query - which chunks should the retriever find? This is what context precision and recall measure against.

Run evaluation regularly. Not once. Every time you change the system prompt, update the knowledge base, swap the embedding model, or adjust retrieval parameters - re-evaluate. RAGAS catches regressions that eyeballing misses.

Your Takeaway for Today

RAGAS gives you five metrics that measure every part of your RAG pipeline:

• context precision (is the retriever finding the right documents?)

• context recall (is it finding ALL of them?)

• faithfulness (is the answer grounded in the evidence?)

• factual correctness (is the answer actually true?)

• and response relevancy (does it answer the question?)

For healthcare, faithfulness and factual correctness are non-negotiable - target ≥0.95 and ≥0.90 respectively. Stop guessing. Start measuring.

Coming Tomorrow: Day 35 (Premium Build Project: THE FINALE)

BUILD PROJECT: Production Clinical Decision Support Agent with Full Evaluation

Tomorrow is the capstone. Paid subscribers get the final build project: a complete, agentic clinical decision support system with LangGraph routing, multi-source retrieval, confidence scoring, audit logging, AND a full RAGAS evaluation pipeline. Everything from 35 days, in one system. This is the project that demonstrates mastery of the most in-demand AI skill in healthcare.

→ Subscribe to RAG for Healthcare to get the Day 35 Capstone Project.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Here, I will explain the architecture, the reasoning behind every design decision, and the clinical logic that makes this system work.

The code implements exactly what you read below.

What We Are Building

A clinical triage agent with five nodes and three conditional edges that mirrors how a senior clinician thinks through a complex case:

Node 1 - Classify: Is this even a clinical question? A query like “what’s the weather” gets gated immediately - no retrieval, no generation, no wasted compute. A query about Entresto dosing passes through.

Node 2 - Retrieve: Search the clinical knowledge base. For a multi-factor question like “72M with HFrEF, eGFR 25, K+ 5.2 - should I start Entresto?”, the retriever needs to surface heart failure GDMT guidelines, renal dosing adjustments, AND potassium management protocols.

Node 3 - Grade Documents: An LLM evaluates the retrieved chunks: “Do these documents actually contain enough information to answer the question?” If yes, proceed to generation. If no, rewrite the query and search again. This is the self-correction loop - the senior resident who goes back to the chart when the first search didn’t find what the attending needs.

Node 4 - Generate: Synthesize a cited clinical answer from the retrieved evidence. Same system prompt principles from Day 8 - answer only from context, cite sources, include safety caveats.

Node 5 - Check Grounding: A separate LLM call verifies: “Is every clinical claim in this answer actually supported by the retrieved documents?” If the generator added a fabricated dose or an invented trial name, this node catches it and sends the flow back to regenerate. This is the hallucination guard.

Five nodes. Each does one thing well. The intelligence is in how they connect.

The Three Decisions That Make It Agentic

Standard RAG is a straight line:

Agentic RAG has branching points where the system decides what to do next.

Decision 1: Is this clinical?

After classification, the system routes: clinical queries go to retrieval, non-clinical queries get a polite redirect and exit.

This saves the retrieval + generation cost (~$0.01–0.03) for every irrelevant query - which matters at scale.

The analogy: The triage nurse in the emergency department. Not every person who walks in needs the full workup. Some need directions to the pharmacy. The triage step prevents the expensive pipeline from running unnecessarily.

Decision 2: Are the documents relevant?

After grading, the system routes: relevant documents proceed to generation, irrelevant documents trigger a query rewrite and a second retrieval attempt.

If the second attempt also fails, the system generates from whatever it has - with appropriate caveats about insufficient evidence.

The analogy: The attending asking the resident: “Did you actually find the renal dosing data, or just the general heart failure guideline?” If the resident didn’t find it, they don’t guess - they go back and look specifically for renal dosing.

The safety cap: Maximum 2 retrieval attempts. Without this, a query that the knowledge base truly can’t answer would loop forever. After 2 attempts, the system generates honestly: “The available guidelines do not contain sufficient information...” - the same graceful failure from Day 8, Rule 3.

Decision 3: Is the answer grounded?

After the grounding check, the system routes: grounded answers are returned to the user, ungrounded answers get regenerated. Again, maximum 2 generation attempts to prevent infinite loops.

The analogy: The pharmacist who double-checks the prescription against the reference before it goes to the patient. If the dose doesn’t match the guideline, they don’t send it - they flag it for correction.

Why this matters clinically: The generation step (Node 4) uses the system prompt to request grounded answers. The grounding check (Node 5) verifies that the request was followed. These are two separate defenses against hallucination - the instruction and the verification. Belt and suspenders. In clinical AI, redundant safety is a feature, not a waste.

The State: Shared Memory Across All Nodes

Every node reads from and writes to a shared state - a typed dictionary with explicit fields: the query, whether it’s clinical, the retrieved documents, how many retrieval attempts have been made, whether docs were graded relevant, the generated answer, whether it’s grounded, and any rewritten queries.

The analogy: The patient chart. The triage nurse writes the chief complaint. The lab tech adds the results. The attending writes the assessment. The pharmacist reviews the medications. Everyone works from the same chart - no information is lost between steps, and every subsequent step has the full picture.

A key design choice: Retrieved documents accumulate across retrieval attempts. When the agent re-retrieves after a failed grade, the new documents get added to the existing ones. The agent builds evidence across iterations rather than throwing away its first search when it tries again.

The Query Rewriter: The Hidden Power Node

When the grader says the retrieved documents aren’t relevant, the agent doesn’t just search again with the same query - it rewrites the query first.

The original query: “72M with HFrEF, eGFR 25, K+ 5.2 - should I start Entresto?”

The rewritten query might be: “sacubitril valsartan renal dose adjustment eGFR below 30 hyperkalemia potassium monitoring”

The rewriter strips the clinical narrative and extracts the specific medical terms that will match guideline content. This dramatically improves the second retrieval’s precision - the same technique a clinician uses when their first literature search is too broad.

Human-in-the-Loop: The Clinical Safety Gate

LangGraph 2.0 supports interrupt gates - points where the workflow pauses and waits for human approval. For clinical applications, you can pause the agent after document grading and before generation, so a clinical pharmacist reviews the retrieved evidence before the system synthesizes a recommendation.

This is a one-line configuration change. The agent fetches and grades the documents, then stops. The pharmacist reviews, confirms the evidence is appropriate, and the workflow resumes. If the evidence is wrong, the pharmacist can modify the state and redirect.

AI proposes. Human approves. System executes. This is the regulatory pattern that healthcare compliance teams require for clinical decision support.

Adapting the Blueprint

The five-node structure is a template. Swap the knowledge base and node logic to build any clinical workflow:

Drug interaction checker:

Differential diagnosis agent:

Adverse event detector:

Clinical trial matcher:

Same graph. Same conditional edges. Different nodes. That’s the power of the blueprint.

What to Watch in the Notebook

When you run the seven test queries, pay attention to:

Query 1 (Entresto + eGFR 25 + K+ 5.2): Does the agent retrieve from ALL three domains - HF guidelines, renal dosing, and potassium management? Does the answer include the specific eGFR threshold for Entresto (≥20) and the potassium monitoring requirement?

Query 3 (K+ 5.8 emergency): Does the grading step recognize this as urgent? Does the answer include the immediate management steps (hold MRA, hold ARNi, consider IV calcium)?

Query 6 (weather - non-clinical): Does the classifier gate this immediately? The agent should exit after one LLM call, not run the full pipeline.

Query 7 (pneumonia - out of scope): The knowledge base covers heart failure, not pneumonia. Does the grading step recognize the retrieved docs are irrelevant? Does the rewrite help? Ultimately, does the system say “insufficient information” rather than hallucinating?

Your Takeaway for Today

An agentic clinical RAG system has five nodes: classify, retrieve, grade, generate, check. And three conditional edges (is it clinical? are docs relevant? is the answer grounded?).

LangGraph 2.0 wires them into a self-correcting state machine with safety caps on loops and optional human-in-the-loop gates.

The blueprint is reusable: swap the knowledge base and node logic for any clinical workflow.

The Notebook

Google Colab Notebook: Day 33 - Agentic RAG with LangGraph

Coming Tomorrow: Day 34

Evaluating Your RAG with RAGAS - The Only Metrics That Actually Matter

You’ve built five types of RAG systems across this series. But how do you know if any of them work?

Tomorrow: RAGAS - the evaluation framework that measures faithfulness, factual correctness, context precision, and response relevancy. The metrics that tell you whether your system is trustworthy or just confident. This is what separates hobby projects from production healthcare AI.

→ Subscribe to RAG for Healthcare so you don’t miss Day 34.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Today, the pipeline starts thinking for itself.

The Problem That Breaks Standard RAG

A clinician asks: “Should I start Entresto in this 72-year-old with HFrEF, eGFR 25, and potassium 5.2?”

Clinical context: Entresto (sacubitril/valsartan) is an ARNi - one of the four pillars of guideline-directed therapy for HFrEF (Day 7). But this isn’t a simple drug question. The eGFR of 25 means the patient has CKD stage 4 - severe kidney impairment. The potassium of 5.2 is above normal (3.5–5.0 mEq/L), and Entresto can raise potassium further through its effect on the renin-angiotensin system. Three clinical domains collide: heart failure management, renal dosing, and electrolyte safety.

Your standard RAG system does one search: “Entresto HFrEF eGFR 25 potassium 5.2.” It retrieves the 5 most similar chunks. Maybe it gets a heart failure guideline chunk. Maybe a renal dosing chunk. Probably not a potassium monitoring protocol. The retrieval is a single shot - and for a multi-factor clinical question, a single shot isn’t enough.

An agentic RAG system handles this differently:

Four separate retrievals. Each one triggered by what the agent learned from the previous retrieval. That’s what makes it agentic.

What Makes RAG “Agentic”

Three capabilities make RAG agentic:

1. Routing: Deciding WHERE to search

The agent reads the query and routes it to the right knowledge source. A drug interaction question goes to the pharmacology index. A dosing question goes to the formulary. A guideline question goes to the clinical guidelines.

The analogy: A hospital switchboard operator.
When a call comes in: “I need help with a medication question” - they don’t transfer you to every department. They listen, determine it’s a pharmacy question, and route you directly to the pharmacist. If you also mention a kidney concern, they conference in nephrology.

In our Entresto example, the agent recognizes three domains (heart failure, renal, electrolytes) and routes to each.

2. Self-correction - Deciding IF the retrieval was good enough

After retrieving chunks, the agent evaluates: “Did I get what I need to answer this question?”

If the retrieved chunks don’t address the eGFR concern, the agent doesn’t just generate a partial answer - it searches again with a refined query specifically targeting renal dosing guidelines.

The analogy: A resident presenting a case to the attending. The attending asks: “What’s the renal dosing?” The resident checks their notes. If the answer isn’t there, they don’t make something up - they go back to the chart, look it up, and return with the specific information. Self-correction is the “go back and look again” step.

3. Multi-step reasoning - Deciding WHAT to do next

Each step can trigger a different action: retrieve from a different source, re-query with a refined question, check for contradictions, or decide the answer is complete.

The analogy: A clinical reasoning chain. The attending doesn’t think about a patient in one step.
They think:

Each step follows from the previous one. The next step depends on what was learned.

LangGraph: The Framework for Agentic RAG

LangGraph 2.0 (released February 2026) is the framework that makes agentic RAG possible. It lets you build state machines: workflows where the system moves between states based on decisions. It’s MIT-licensed, free, and has become the dominant orchestration layer for production AI agents.

The Mental Model: States and Edges

A LangGraph workflow has:

• States: typed snapshots of what the system knows at each point (the query, retrieved chunks, intermediate analyses)

• Nodes: actions the system can take (retrieve, analyze, generate, decide)

• Edges: transitions between nodes, including conditional edges where the next step depends on what happened

• Checkpoints: persistent state that survives failures and enables human-in-the-loop review

• Interrupt gates: points where the workflow can pause for human approval before proceeding (critical for clinical applications)

Two conditional edges make this agentic: the document grader that re-searches if retrieval is poor, and the hallucination checker that regenerates if the answer isn’t grounded in the retrieved documents. Both are LLM calls that evaluate the system’s own output - the “self-correction” that production agentic RAG requires.

The Core Code Pattern (LangGraph 2.0)

python

from langgraph.graph import StateGraph, END
from typing import TypedDict, List, Annotated
from operator import add

class AgentState(TypedDict):
    query: str
    domains: List[str]
    retrieved_docs: Annotated[List[str], add]
    docs_relevant: bool
    answer: str
    answer_grounded: bool

def route_query(state):
    """LLM analyzes query and identifies required knowledge domains."""
    ...
    return {"domains": ["heart_failure", "renal_dosing", "electrolytes"]}

def retrieve(state):
    """Search the identified knowledge sources."""
    ...
    return {"retrieved_docs": results}

def grade_documents(state):
    """LLM evaluates: are the retrieved docs relevant to the query?"""
    ...
    return {"docs_relevant": True or False}

def generate(state):
    """Synthesize final answer from all retrieved content."""
    ...
    return {"answer": answer}

def check_hallucination(state):
    """LLM evaluates: is the answer grounded in the retrieved docs?"""
    ...
    return {"answer_grounded": True or False}

# Build the graph
workflow = StateGraph(AgentState)
workflow.add_node("route", route_query)
workflow.add_node("retrieve", retrieve)
workflow.add_node("grade", grade_documents)
workflow.add_node("generate", generate)
workflow.add_node("hallucination_check", check_hallucination)

workflow.set_entry_point("route")
workflow.add_edge("route", "retrieve")
workflow.add_edge("retrieve", "grade")

# Conditional: relevant docs? → generate. Irrelevant? → rewrite + retrieve again
workflow.add_conditional_edges(
    "grade",
    lambda state: "generate" if state["docs_relevant"] else "retrieve",
)

workflow.add_edge("generate", "hallucination_check")

# Conditional: grounded? → done. Not grounded? → regenerate
workflow.add_conditional_edges(
    "hallucination_check",
    lambda state: END if state["answer_grounded"] else "generate",
)

agent = workflow.compile()

Two conditional edges: document grading and hallucination checking - are the lines that make this agentic. In a clinical context, these loops ensure the system doesn’t return irrelevant evidence or ungrounded claims.

Standard RAG vs. Agentic RAG

The practical rule:

• Use standard RAG for single-factor questions: ”What is the dose of amoxicillin for CAP?”.

• Use agentic RAG for multi-factor clinical scenarios where the answer requires information from multiple domains: ”Should I start Entresto given this patient’s specific renal function and electrolytes?”

Most production systems use both: standard RAG for the 80% of queries that are straightforward, with agentic RAG routing for the 20% that require multi-step reasoning. An initial classifier decides which path each query takes.

Why This Matters for Healthcare

Clinical reasoning is inherently agentic. A physician doesn’t think in a single step. They gather information, identify concerns, seek additional data, reassess, and synthesize. The diagnostic process is a state machine - each finding triggers a new line of inquiry.

Standard RAG gives you a search engine. Agentic RAG gives you a clinical reasoning engine - one that mirrors how clinicians actually think through complex cases.

Human-in-the-loop is native to LangGraph 2.0. You can set interrupt gates at any node: for example, pausing before the generation step so a clinical pharmacist can review the retrieved evidence before the system synthesizes a recommendation.

In healthcare, where autonomous AI recommendations carry patient safety implications, this isn’t a nice-to-have: it’s a regulatory expectation.

LangGraph makes it a one-line configuration: workflow.compile(interrupt_before=["generate"]).

The Entresto question isn’t hypothetical. Every hospitalist, cardiologist, and nephrologist faces multi-factor prescribing decisions daily. The AI system that handles these decisions needs the same multi-step reasoning capability that the clinician uses.

Your Takeaway for Today

Agentic RAG adds three capabilities to standard RAG:

(1) routing (choosing where to search), (2) self-correction (evaluating retrieval quality and retrying), (3) and multi-step reasoning (each step informed by the previous).

LangGraph implements this as a state machine with conditional edges.

Use standard RAG for simple queries and agentic RAG for complex, multi-factor clinical scenarios that require reasoning across multiple domains.

Coming Tomorrow: Day 33

Building an Agentic RAG with LangGraph: The Step-by-Step Blueprint

Today was the concept and architecture.

Tomorrow you build it: a complete agentic clinical RAG system using LangGraph, with routing across three knowledge sources (guidelines, formulary, lab reference), self-correction when retrieval is insufficient, and multi-step synthesis. Full code.

• Subscribe to RAG for Healthcare so you don’t miss Day 33.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

CLIP eliminates both limitations. It embeds images and text into the same vector space directly - no Vision API, no text description step, no per-image cost after the initial embedding. And it works both ways: text query → find matching images, OR image query → find matching text.

What CLIP Does (One Sentence)

CLIP maps images and text into the same vector space so that an image of a chest X-ray with cardiomegaly and the text “enlarged cardiac silhouette consistent with cardiomegaly” end up as nearby vectors - even though one is pixels and the other is words.

The analogy: Imagine a bilingual translator who can read both English and Mandarin and place every document on the same bookshelf by topic - regardless of language. CLIP is that translator, except the two “languages” are images and text. Once both are on the same shelf, you can search in either language and find results in both.

How CLIP Works (3 Minutes)

CLIP (Contrastive Language-Image Pre-training, OpenAI 2021) learns by looking at millions of image-text pairs and learning to match them.

The Training Process

Given a batch of image-text pairs (e.g., a chest X-ray paired with its radiology report):

After training on hundreds of millions of pairs, the model learns that “images showing cardiomegaly” and “text describing cardiomegaly” belong in the same region of vector space - without ever being told what cardiomegaly is.

The analogy: A medical student who’s seen thousands of X-rays, each paired with the attending’s verbal description. After enough examples, they can look at a new X-ray and predict what the attending would say - or hear a description and picture what the X-ray looks like. CLIP learned the same association, at scale.

Why “Contrastive”

The training is called contrastive because the model learns by contrast - distinguishing correct pairs from incorrect ones. In a batch of 32,768 image-text pairs, each image has exactly one matching text. The model must identify the correct match out of 32,767 wrong ones. This forces it to learn precise, meaningful alignments.

General CLIP vs. Medical CLIP

Standard CLIP was trained on internet image-text pairs: photos, illustrations, memes, product images. It understands “dog,” “sunset,” and “red car” excellently. It understands “pleural effusion” poorly.

BiomedCLIP (Microsoft, 2023) was trained on 15 million biomedical figure-caption pairs from PubMed articles. It understands:

• Chest X-ray findings (consolidation, effusion, cardiomegaly)

• Histopathology patterns (ductal carcinoma, glandular architecture)

• Radiology modalities (CT, MRI, ultrasound appearances)

• Clinical photographs (dermatological lesions, wound staging)

PubMedCLIP - trained on PubMed image-text pairs, another strong option for biomedical content.

The practical rule: For healthcare multimodal RAG, always use a biomedical CLIP variant. General CLIP will retrieve “images that look like medical images.” BiomedCLIP will retrieve “images showing the specific pathology you asked about.”

Cross-Modal Search in Code

Here’s the core pattern - embed images and text with the same model, search across both:

python

from open_clip import create_model_and_transforms, get_tokenizer
import torch
from PIL import Image

# Load BiomedCLIP
model, preprocess_train, preprocess_val = create_model_and_transforms(
    'hf-hub:microsoft/BiomedCLIP-PubMedBERT_256-vit_base_patch16_224'
)
tokenizer = get_tokenizer(
    'hf-hub:microsoft/BiomedCLIP-PubMedBERT_256-vit_base_patch16_224'
)
model.eval()

# - EMBED AN IMAGE ─-
image = preprocess_val(Image.open("chest_xray.jpg")).unsqueeze(0)
with torch.no_grad():
    image_vector = model.encode_image(image)
    image_vector /= image_vector.norm(dim=-1, keepdim=True)  # Normalize

# - EMBED TEXT -
text = tokenizer(["cardiomegaly with pulmonary edema"])
with torch.no_grad():
    text_vector = model.encode_text(text)
    text_vector /= text_vector.norm(dim=-1, keepdim=True)  # Normalize

# - COMPUTE SIMILARITY -
similarity = (image_vector @ text_vector.T).item()
print(f"Image-text similarity: {similarity:.3f}")

Both vectors live in the same space. Cosine similarity between them tells you how well the image matches the text - using the same math from Day 15.

Three Search Patterns

Pattern 1: Text → Image (Find images matching a description)

“Show me chest X-rays with bilateral pleural effusions”

Embed the query text, search against all image vectors, return the top matches.

python

query_vector = model.encode_text(tokenizer(["bilateral pleural effusions"]))
similarities = query_vector @ all_image_vectors.T
top_matches = similarities.argsort(descending=True)[:5]

Clinical use: Teaching libraries, case-based learning, clinical reference.

Pattern 2: Image → Text (Find descriptions matching an image)

Upload an unknown X-ray, find the most relevant text descriptions or guideline sections.

python

query_vector = model.encode_image(preprocess_val(unknown_xray).unsqueeze(0))
similarities = query_vector @ all_text_vectors.T
top_matches = similarities.argsort(descending=True)[:5]

Clinical use: “What does this look like?” Find similar cases and their descriptions.

Pattern 3: Image → Image (Find visually similar cases)

Upload an echo frame, find the most visually similar echo frames in your database.

python

query_vector = model.encode_image(preprocess_val(new_echo).unsqueeze(0))
similarities = query_vector @ all_image_vectors.T
top_matches = similarities.argsort(descending=True)[:5]

Clinical use: “Find cases similar to this patient’s echo.” Powerful for rare findings where a clinician wants to see how similar cases were managed.

Day 30 (GPT Vision) vs. Day 31 (CLIP): When to Use Which

The practical recommendation:

• < 1,000 images, need rich descriptions: Use GPT-5.4 Vision (Day 30). The descriptions add value for the LLM generation step.

• > 1,000 images, need fast search: Use BiomedCLIP. No per-image API cost, native cross-modal search.

• PHI-containing images: Use BiomedCLIP. Everything stays local.

• Best of both: Embed with BiomedCLIP for search, generate descriptions with GPT-5.4 Vision only for the top retrieved results. Search is cheap and fast; descriptions are rich and expensive. Combine at the right layer.

Limitations for Healthcare

Resolution matters. CLIP processes images at 224×224 pixels. A subtle finding visible on a full-resolution DICOM (3000×3000) may be lost after downscaling. For pathology whole-slide images, you’ll need to tile the slide and process each tile separately.

Rare findings are underrepresented. BiomedCLIP was trained on PubMed figures: biased toward findings that get published. Rare conditions have fewer training examples and weaker representations.

No spatial reasoning. CLIP knows “this image contains cardiomegaly” but can’t tell you “the cardiomegaly is predominantly left-sided” or “the effusion is in the right costophrenic angle.” Spatial understanding requires specialized models.

Not diagnostic. Like GPT-5.4 Vision, CLIP is a retrieval and matching tool — not an FDA-cleared diagnostic system. It finds similar images; a radiologist interprets them. This is also where specialized models like EchoJEPA (which I co-authored) push the boundary — learning visual representations from 18M echocardiography videos specifically for cardiac function assessment.

Your Takeaway for Today

CLIP embeds images and text into the same vector space, enabling three search patterns that Day 30 couldn’t do: text→image, image→text, and image→image.

Use BiomedCLIP for medical data: it understands clinical findings, not just generic objects. It runs locally (HIPAA-friendly), costs nothing per query, and scales to millions of images.

Combine it with GPT-5.4 Vision descriptions for the best of both worlds: fast search with CLIP, rich descriptions with Vision.

Coming Tomorrow: Day 32

Agentic RAG: When Your AI Decides What to Search

For 31 days, your RAG systems have followed a fixed pipeline: query → retrieve → generate.

The human decides what to search.

Tomorrow, the AI starts deciding. Agentic RAG uses LangGraph to build state machines where the AI routes queries to different knowledge sources, decides whether retrieval quality is sufficient, and self-corrects when it’s not.

This is the architecture that powers the most advanced clinical decision support systems being built today.

→ Subscribe to RAG for Healthcare so you don’t miss Day 32.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

By the end of this article (and the accompanying Google Colab notebook), you’ll have a system where a query like “findings consistent with heart failure” retrieves both a guideline text chunk about HFrEF diagnostic criteria and a chest X-ray description showing cardiomegaly with pulmonary edema: from the same FAISS index, with a single search.

The Pipeline: 5 Steps

Every medical image goes through the same production pipeline:

Steps 1–3 are image processing. Step 4 is the bridge between visual and textual modalities. Step 5 is standard RAG: your existing pipeline handles it.

Step 1-3: Load, Resize, Encode

Medical images come in various formats. The processing needs are simple but the gotchas are format-specific:

DICOM files (raw from PACS): Use pydicom to read, extract pixel data, apply windowing (for CT), then convert to PIL Image. DICOM carries metadata (patient ID, study date, modality) - extract it and attach as chunk metadata.

PNG/JPEG (exported from viewers): Direct load with PIL. Most teaching collections and public datasets use these formats.

Video frames (echo clips): Use cv2.VideoCapture to extract keyframes at specific intervals or at physiologically meaningful timepoints (end-diastole, end-systole for echo).

Why resize to ≤1024px? GPT-5.4 Vision charges based on image size. A 4000×4000 pathology tile costs ~4x more than a 1024×1024 version - with minimal quality improvement for description generation. Always resize before sending.

Why base64? The OpenAI API accepts images as base64-encoded strings embedded in the request JSON. This avoids hosting images on a URL - important for PHI, since the image never touches a public endpoint.

python

import base64, io
from PIL import Image

def encode_medical_image(filepath, max_size=1024):
    img = Image.open(filepath).convert('RGB')

    if max(img.size) > max_size:
        ratio = max_size / max(img.size)
        img = img.resize((int(img.size[0]*ratio), int(img.size[1]*ratio)))

    buffer = io.BytesIO()
    img.save(buffer, format='PNG')
    return base64.b64encode(buffer.getvalue()).decode('utf-8')

Step 4: GPT-5.4 Vision Description (The Bridge)

This is where the image becomes text: searchable, embeddable, and retrievable alongside your clinical documents.

The prompt matters enormously. A generic “describe this image” produces a generic description. A clinical prompt produces a structured radiology-style report:

python

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": """You are a radiologist. Generate a structured report:
1. MODALITY AND VIEW
2. KEY FINDINGS
3. MEASUREMENTS (if applicable)
4. IMPRESSION
Clinical info: 65F with new-onset dyspnea"""},
            {"type": "image_url", "image_url": {
                "url": f"data:image/png;base64,{base64_data}",
                "detail": "high"
            }}
        ]
    }],
    max_completion_tokens=500,
)

Cost: ~$0.01–0.03 per image at high detail. For a 500-image teaching library, that’s $5–15 one-time indexing cost. Queries after indexing are text-only (no Vision API needed).

Clinical context: GPT-5.4 Vision is not FDA-cleared for diagnostic interpretation. The descriptions it generates are for search indexing, not clinical diagnosis. A radiologist interprets; the model makes the image searchable. This distinction matters for compliance.

Step 5: Unified Index - Images and Text Together

The description from Step 4 becomes a standard LangChain Document with image metadata attached:

python

from langchain_core.documents import Document

doc = Document(
    page_content=vision_description,  # The GPT-5.4 Vision output
    metadata={
        "source_type": "medical_image",
        "modality": "Chest X-Ray",
        "study": "PA Chest Radiograph",
        "filename": "cxr_001.png",
        "clinical_info": "65F with new-onset dyspnea",
    }
)

This document goes into the same FAISS index as your clinical text chunks. The embedding model maps the radiological description into the same vector space as your guideline text - so a query about “heart failure imaging” retrieves both the guideline definition and the X-ray description.

What the Notebook Demonstrates

The accompanying Google Colab notebook walks through the complete pipeline with six medical images across four modalities:

Plus five clinical text documents on related topics. All indexed together.

Five cross-modal search tests demonstrate that text queries retrieve relevant images:

• “chest X-ray showing cardiomegaly” → finds the cardiomegaly X-ray description

• “dilated left ventricle with reduced ejection fraction” → finds BOTH the echo image AND the HFrEF guideline text

• “acute ischemic stroke on brain MRI” → finds both the MRI description and the stroke management text

Full multimodal RAG generates answers with image attribution: the response cites which images were used, by modality and study type.

Processing Medical Images at Scale

For production deployment, here’s the practical workflow:

Teaching libraries (100–1,000 images): Process all at once. ~$10–30 in Vision API costs. Run overnight. Done.

Active PACS integration (continuous): Set up a listener that processes new studies as they arrive. Each new image gets described and indexed within minutes of acquisition. This is the architecture for real-time image-searchable clinical systems.

Large retrospective datasets: Batch process with rate limiting.

• NIH Chest X-ray dataset (100K images) at $0.01/image = $1,000.

• CheXpert (224K images) = $2,240. Significant but one-time. Alternatively, use BiomedCLIP for native image embedding (Day 31 preview) - no Vision API needed, dramatically cheaper at scale.

EchoNet-Dynamic (10K echo videos): Extract keyframes (end-diastole, end-systole - 2 frames per video = 20K images), describe with Vision API = ~$200. For my co-authored work on EchoJEPA - a self-supervised model trained on 18M echo videos - we process echocardiography at a scale where native visual encoders become essential.

Your Takeaway for Today

Processing medical images for RAG follows a five-step pipeline:

1. Load

2. Resize

3. Encode to base64

4. Describe with GPT-5.4 Vision

5. Embed the description alongside clinical text.

   The description is the bridge between visual and textual modalities - once an image has a text description, your existing RAG pipeline handles everything else. Cost is ~$0.01–0.03 per image for indexing; queries are free.

The Notebook

Google Colab Notebook: Day 30 - Medical Image Processing for RAG

Six medical images across four modalities, five cross-modal search tests, full multimodal RAG with image attribution. Run in ~60 seconds.

Coming Tomorrow: Day 31

The CLIP Model - Aligning Medical Images and Text Without Fine-Tuning

Today you used GPT-5.4 Vision as the bridge between images and text (Approach 1: text-mediated).

Tomorrow you learn CLIP and BiomedCLIP - models that embed images and text directly into the same vector space (Approach 2: native multimodal embedding).

No Vision API needed. No per-image description cost. True image-to-text and image-to-image search.

• Subscribe to RAG for Healthcare so you don’t miss Day 31.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Your text-based RAG, the one you have spent four weeks building, finds guideline chunks describing severe MR criteria: vena contracta ≥7mm, regurgitant volume ≥60mL, EROA ≥0.40 cm². Accurate. Cited. Grounded.

But the fellow doesn’t need a text definition. They need to SEE it. They need the echo clip showing the color Doppler jet filling the left atrium. They need the side-by-side comparison of moderate vs. severe. They need the annotated still frame pointing to the vena contracta measurement.

Text alone can’t answer this question. The answer is an image.

Clinical context: Mitral regurgitation (MR) is backward leakage of blood through the mitral valve during each heartbeat.

Severity is graded by echocardiography using multiple parameters (the size of the regurgitant jet on color Doppler, the width of the vena contracta (the narrowest point of the jet), and quantitative measures of regurgitant volume). Interpreting MR severity is a visual skill: echocardiographers learn it by seeing hundreds of examples, not by reading criteria.

Healthcare is inherently multimodal. Clinicians don’t make decisions from text alone: they read notes, scan lab values, examine imaging, listen to heart sounds, and review ECG tracings. A RAG system that only processes text is working with one hand tied behind its back.

Today we untie it.

What Multimodal RAG Means

The modalities that matter in healthcare:

A truly multimodal clinical RAG system can answer: “Find echo clips similar to this patient’s parasternal long-axis view” or “Show me chest X-rays with findings consistent with the pulmonary edema described in this note.”

The Architecture: Three Approaches

Approach 1: Describe, then retrieve (Text-Mediated)

Convert non-text modalities to text descriptions, then use standard text RAG.

Example: Feed each echo frame to GPT-5.4 with a prompt: “Describe the echocardiographic findings in this image.” The model produces: “Apical 4-chamber view showing severe mitral regurgitation with a large color Doppler jet occupying >50% of the left atrium. Vena contracta appears wide.” This description gets embedded and stored alongside a pointer to the original image.

The analogy: A radiologist dictating a report. The image is converted to text (the radiology report), and the text is what gets searched. When you find the right report, you pull up the corresponding image.

Pros: Uses your existing text RAG pipeline (Days 1–21). No new infrastructure. Cons: The description loses visual details. You can’t search for “images that look like this” - only for “images described like this.”

Best for: Quick prototyping, lecture slide libraries, annotated teaching collections.

Approach 2: Native multimodal embedding (Vision Embeddings)

Embed images directly into the same vector space as text, using a multimodal embedding model.

How it works: Multimodal embedding models (like OpenAI’s multimodal embeddings, CLIP, or BiomedCLIP) map both text and images into the same vector space. An echo image of severe MR and the text “severe mitral regurgitation” end up near each other - because the model has learned to align visual and textual representations of the same concept.

The analogy: A bilingual librarian who organizes English and Spanish books on the same shelves by topic. You can search in English and find a Spanish book, because the librarian understands both languages and filed them together by subject.

Pros: True cross-modal search. Query with text, retrieve images. Query with an image, retrieve similar images or related text.

Cons: Requires multimodal embedding models. Medical-specific models (BiomedCLIP, PubMedCLIP) perform significantly better than general-purpose ones on clinical images.

Best for: Production multimodal systems, image similarity search, cross-modal retrieval.

Approach 3: Parallel retrieval with fusion (Multi-Index)

Maintain separate indices for each modality and merge results at query time - the same architecture you built on Day 21, extended to images.

The analogy: The consulting physician who checks the chart (text index), pulls up the imaging (image index), and reviews the labs (structured data) - then synthesizes across all three. Each source is searched independently, and the results are merged into a unified clinical picture.

Pros: Each modality uses its best-fit embedding model. You can weight modalities differently per query. Modular - add new modalities without rebuilding.

Cons: More complex merging logic. Need to maintain multiple indices.

Best for: Enterprise clinical decision support, multi-modal teaching systems, comprehensive patient review tools.

The Current State of Medical Multimodal Models

The field is moving fast. Here’s where things stand:

BiomedCLIP: Trained on PubMed figure-caption pairs. Best open-source option for medical image-text alignment. Understands X-rays, pathology, and clinical photographs significantly better than general CLIP.

EchoJEPA (echojepa.com) - A self-supervised foundation model trained on 18 million echocardiography videos from 300,000+ patients, which I co-authored. EchoJEPA learns visual representations of cardiac function without labeled data - the kind of pretrained visual encoder that powers the image embedding side of multimodal RAG for cardiology.

GPT-5.4 Vision: Processes images natively in the chat completion API. Can describe clinical images with reasonable accuracy but is not FDA-cleared for diagnostic use. Excellent for generating text descriptions (Approach 1).

Med-PaLM M (Google): Multimodal medical AI handling text, imaging, and genomics. Research-stage but demonstrates the direction the field is heading.

RAG-Anything (HKUDS, 2025): An extension of LightRAG (Day 24–26) that processes text, images, tables, and equations in a unified RAG pipeline. Integrates with LightRAG’s knowledge graph for multimodal graph-based retrieval.

Clinical context: No multimodal AI system is currently FDA-cleared for autonomous diagnostic interpretation of medical images in a RAG context. These systems are decision support tools - they surface relevant images and descriptions, but a qualified clinician must interpret and act on the findings.

Your Takeaway for Today

Healthcare is multimodal: notes, images, labs, waveforms, audio.

Text-only RAG answers text questions well but can’t handle “show me what severe MR looks like on echo.”

Three multimodal RAG architectures exist:

• text-mediated (convert images to descriptions)

• native multimodal embedding (align images and text in the same vector space)

• parallel multi-index retrieval (separate indices, merged results).
  
  Start with text-mediated for quick wins. Move to native multimodal embedding for production image search.

Coming Tomorrow: Day 30

Processing Medical Images for RAG: X-Rays, Ultrasound, and Pathology Slides

Today was the architecture. Tomorrow is the implementation - how to actually process medical images (DICOM X-rays, ultrasound frames, pathology whole-slide images), generate embeddings, and build a searchable medical image index.

You’ll learn which preprocessing matters, which models to use, and the gotchas specific to clinical imaging data.

→ Subscribe to RAG for Healthcare so you don’t miss Day 30.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

The final week starts tomorrow. Agentic RAG. Self-correcting systems. The capstone.

→ Subscribe free for every daily article.

→ Subscribe paid for the build projects and notebooks.

Subscribe now

- Teodora

Drug interactions kill more Americans annually than car accidents. And the tragic part: most of these interactions are known. They are documented in FDA labeling, in pharmacology textbooks, in drug databases. The information exists.

The problem is detection at the point of prescribing.

Most EHR alert systems use pair-wise lookup tables:

Drug A + Drug B = alert.

They catch the obvious ones.

But they miss interaction cascades: the multi-drug pile-ups that happen when three or four medications collide through shared metabolic pathways.

Here is a real scenario: A cardiologist prescribes amiodarone for a patient already on warfarin. The EHR fires an alert: amiodarone inhibits CYP2C9, warfarin levels will rise, reduce the dose. Good. The pharmacist adjusts.

But the patient also has a fungal infection, and the ID team adds fluconazole. Fluconazole is also a potent CYP2C9 inhibitor. Now warfarin has two inhibitors blocking its metabolism simultaneously. The additive effect isn’t 30-50% increase: it’s potentially catastrophic. The EHR fires two separate pair-wise alerts (warfarin-amiodarone, warfarin-fluconazole), but it doesn’t flag the additive cascade: that dual CYP2C9 inhibition creates a compounding risk far greater than either interaction alone.

Read more

Today you make it visible. This is how the graph that we are building today looks like (Python code included):

You will extract subgraphs around clinical concepts, render them as interactive HTML visualizations, and produce the artifact that makes a non-technical stakeholder say: “Now I understand what this system knows.”

Why Visualization Matters in Healthcare AI

Knowledge graph visualization serves three purposes in a clinical setting:

1. Validation. When you visualize the subgraph around “Warfarin,” you can immediately see whether the extraction captured the CYP2C9 metabolism, the amiodarone interaction, the INR monitoring requirement, and the pregnancy contraindication. Missing edges are visible at a glance. No need to write test queries for every relationship.

2. Communication. Your CMIO doesn’t read Python dictionaries. But show them an interactive network where “Warfarin” connects to “CYP2C9” via “metabolized_by” and to “Amiodarone” via “interacts_with”. And they immediately grasp what the system knows and where the gaps are.

3. Discovery. Graphs reveal patterns that queries miss. You might notice that three drugs all connect to CYP2C9, suggesting a shared interaction risk you hadn’t explicitly queried. Visualization turns passive data into active insight.

The analogy: A medical knowledge graph without visualization is like an MRI without the radiologist’s report. The data is all there, but no one can interpret it. Visualization is the report: it turns raw structure into clinical meaning.

Tool: PyVis

PyVis is a Python library that generates interactive HTML network graphs. You create nodes and edges in Python, and PyVis renders them as a draggable, zoomable visualization you can open in any browser. No JavaScript required.

python

pip install pyvis

The output is a standalone .html file. No server, no dependencies. Email it to a colleague, embed it in a presentation, or open it on your phone. This portability is why PyVis beats heavier tools for clinical communication.

Extracting Subgraphs from LightRAG

LightRAG stores its knowledge graph internally. To visualize it, we extract the entities and relationships into a format PyVis can render.

If you want full control over the visualization (recommended for clinical presentations), build the graph from your known entities:

python

import networkx as nx

G = nx.DiGraph()

# Define entities with types (for color-coding)
drugs = ["Warfarin", "Amiodarone", "Metoprolol", "Diltiazem", "Dapagliflozin"]
conditions = ["Atrial Fibrillation", "HFrEF", "HFpEF", "VTE", "Hypertension"]
enzymes = ["CYP2C9", "CYP3A4", "CYP2D6"]
labs = ["INR", "TSH", "LFTs", "PFTs", "BNP"]
effects = ["Bleeding", "Thyroid Dysfunction", "Pulmonary Toxicity",
           "Bradycardia", "Genital Mycotic Infection"]

for d in drugs:      G.add_node(d, type="drug")
for c in conditions: G.add_node(c, type="condition")
for e in enzymes:    G.add_node(e, type="enzyme")
for l in labs:       G.add_node(l, type="lab")
for ef in effects:   G.add_node(ef, type="adverse_effect")

# Add relationships
edges = [
    ("Warfarin", "Atrial Fibrillation", "treats"),
    ("Warfarin", "VTE", "treats"),
    ("Warfarin", "CYP2C9", "metabolized_by"),
    ("Warfarin", "INR", "monitored_by"),
    ("Warfarin", "Bleeding", "causes"),
    ("Amiodarone", "Atrial Fibrillation", "treats"),
    ("Amiodarone", "CYP2C9", "inhibits"),
    ("Amiodarone", "CYP3A4", "inhibits"),
    ("Amiodarone", "Thyroid Dysfunction", "causes"),
    ("Amiodarone", "Pulmonary Toxicity", "causes"),
    ("Amiodarone", "TSH", "monitored_by"),
    ("Amiodarone", "LFTs", "monitored_by"),
    ("Amiodarone", "PFTs", "monitored_by"),
    ("Amiodarone", "Warfarin", "interacts_with"),
    ("Metoprolol", "HFrEF", "treats"),
    ("Metoprolol", "Atrial Fibrillation", "treats"),
    ("Metoprolol", "Hypertension", "treats"),
    ("Metoprolol", "CYP2D6", "metabolized_by"),
    ("Metoprolol", "Bradycardia", "causes"),
    ("Diltiazem", "Atrial Fibrillation", "treats"),
    ("Diltiazem", "Hypertension", "treats"),
    ("Diltiazem", "CYP3A4", "inhibits"),
    ("Diltiazem", "HFrEF", "contraindicated_in"),
    ("Dapagliflozin", "HFrEF", "treats"),
    ("Dapagliflozin", "HFpEF", "treats"),
    ("Dapagliflozin", "BNP", "monitored_by"),
    ("Dapagliflozin", "Genital Mycotic Infection", "causes"),
    ("Atrial Fibrillation", "VTE", "increases_risk_of"),
]

for src, tgt, rel in edges:
    G.add_edge(src, tgt, relationship=rel)

print(f"Graph: {G.number_of_nodes()} nodes, {G.number_of_edges()} edges")

Rendering with PyVis

Now turn the NetworkX graph into an interactive visualization:

python

from pyvis.network import Network

def visualize_graph(G, filename="medical_knowledge_graph.html", height="700px"):
    """Render a NetworkX graph as an interactive HTML visualization."""

    net = Network(height=height, width="100%", directed=True, notebook=True)

    # Color scheme by entity type
    colors = {
        "drug": "#4A90D9",         # Blue
        "condition": "#E74C3C",     # Red
        "enzyme": "#F39C12",        # Orange
        "lab": "#2ECC71",           # Green
        "adverse_effect": "#9B59B6" # Purple
    }

    # Add nodes with styling
    for node in G.nodes():
        node_type = G.nodes[node].get("type", "unknown")
        color = colors.get(node_type, "#95A5A6")
        size = 30 if node_type == "drug" else 20

        net.add_node(
            node,
            label=node,
            color=color,
            size=size,
            title=f"{node} ({node_type})",  # Hover tooltip
        )

    # Add edges with relationship labels
    for src, tgt, data in G.edges(data=True):
        rel = data.get("relationship", "")
        color = "#E74C3C" if rel == "contraindicated_in" else "#CCCCCC"
        width = 3 if rel in ["contraindicated_in", "interacts_with"] else 1

        net.add_edge(src, tgt, title=rel, label=rel, color=color, width=width)

    # Physics settings for readable layout
    net.set_options("""
    {
      "physics": {
        "forceAtlas2Based": {
          "gravitationalConstant": -50,
          "centralGravity": 0.01,
          "springLength": 200
        },
        "solver": "forceAtlas2Based"
      }
    }
    """)

    net.save_graph(filename)
    print(f" Saved to {filename} - open in any browser")

visualize_graph(G)

Open medical_knowledge_graph.html in your browser. You’ll see an interactive network where:

• Blue nodes are drugs (largest - they’re the primary entities)

• Red nodes are conditions

• Orange nodes are metabolizing enzymes

• Green nodes are lab tests

• Purple nodes are adverse effects

• Red edges highlight contraindications and interactions (the dangerous relationships)

• Hover over any node to see its type

• Hover over any edge to see the relationship

• Drag nodes to rearrange the layout

• Zoom in/out to explore clusters

Extracting Clinical Subgraphs

The full graph is useful for overview. Subgraphs are useful for focused clinical questions.

Subgraph: Everything connected to Warfarin

python

def extract_subgraph(G, center_node, depth=2):
    """Extract all nodes within 'depth' hops of center_node."""
    nodes = set()
    current_layer = {center_node}

    for _ in range(depth):
        next_layer = set()
        for node in current_layer:
            next_layer.update(G.successors(node))
            next_layer.update(G.predecessors(node))
        nodes.update(current_layer)
        current_layer = next_layer - nodes
    nodes.update(current_layer)

    return G.subgraph(nodes).copy()

warfarin_subgraph = extract_subgraph(G, "Warfarin", depth=2)
visualize_graph(warfarin_subgraph, "warfarin_network.html")

Open warfarin_network.html and you see Warfarin’s complete clinical profile at a glance: CYP2C9 metabolism, INR monitoring, amiodarone interaction (and amiodarone’s own side effects branching out), bleeding risk, AFib and VTE indications. A pharmacist reviewing this graph can immediately verify that the knowledge base captures the key warfarin considerations.

Subgraph: The heart failure treatment landscape

python

hf_nodes = {"HFrEF", "HFpEF"}
hf_subgraph = nx.DiGraph()

for node in hf_nodes:
    for pred in G.predecessors(node):
        rel = G[pred][node]["relationship"]
        hf_subgraph.add_node(pred, **G.nodes[pred])
        hf_subgraph.add_node(node, **G.nodes[node])
        hf_subgraph.add_edge(pred, node, relationship=rel)

visualize_graph(hf_subgraph, "heart_failure_landscape.html")

This produces a visualization showing every drug that treats or is contraindicated in HFrEF and HFpEF - the complete treatment landscape from a single image. Metoprolol and dapagliflozin treating HFrEF. Dapagliflozin treating HFpEF. Diltiazem contraindicated in HFrEF. The red contraindication edge jumps out visually - exactly the kind of safety signal you want to be immediately obvious.

What to Look for in Your Visualization

When you visualize a medical knowledge graph, inspect it like a clinician reviewing a chart:

Disconnected nodes. An entity with no edges means the extraction missed its relationships. If “Metoprolol” exists but has no “treats” edge to any condition, the extraction failed for that drug. Re-examine the source text.

Missing contraindications. If you know a drug has a major contraindication but the red edge isn’t there, your extraction prompt needs improvement. Contraindications are the highest-value relationships in a clinical knowledge graph - they should all be captured.

Hub nodes. Entities with many connections (like CYP2C9, which connects to multiple drugs) are clinically important hubs. They represent shared risk factors. A hub node in an enzyme like CYP3A4 means that any inhibitor of CYP3A4 could affect all connected drugs. A multi-drug interaction risk that’s immediately visible in the graph but hard to spot in flat text.

Missing edges between entities you know should be connected. If “Warfarin” and “Amiodarone” both exist but have no “interacts_with” edge, that’s a critical gap. The visualization makes this gap obvious in a way that querying alone doesn’t.

Your Takeaway for Today

• Visualization transforms a knowledge graph from a data structure into a communication tool.

• Use PyVis to create interactive HTML visualizations that clinicians and stakeholders can explore in a browser.

• Extract subgraphs around specific drugs or conditions for focused clinical review.

• Inspect for disconnected nodes, missing contraindications, and hub entities.

  The graph you can see is the graph you can trust.

Coming Tomorrow: Day 28 (Premium Build Project)

BUILD PROJECT: Drug Interaction Detection System with LightRAG

Tomorrow, paid subscribers get Build Project #4: a complete drug interaction detection system built on LightRAG.

Feed it a patient’s medication list, and it automatically identifies interactions, rates their severity, explains the mechanisms, and suggests monitoring or alternatives.

Full Google Colab notebook with the complete code. This is the knowledge graph in production.

→ Subscribe to RAG for Healthcare to get the Day 28 Build Project.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Query A: “What is the half-life of amiodarone?”

One entity, one fact, one number. The answer is 40–55 days. You need LightRAG to find the specific node, pull the specific property, and return it. Fast, precise, no synthesis required.

Query B: “What are the major challenges in managing antiarrhythmic therapy?”

No single entity answers this. The answer spans multiple drugs (amiodarone, metoprolol, diltiazem), multiple side effects (thyroid dysfunction, pulmonary toxicity, bradycardia), multiple interactions (CYP inhibition, warfarin dose adjustments), and multiple contraindications (HFrEF, heart block). You need LightRAG to traverse the graph broadly, identify patterns, and synthesize.

Same knowledge graph. Same LightRAG instance. Two fundamentally different retrieval strategies.

The Four Query Modes

LightRAG offers four modes. Each activates a different retrieval strategy.

naive: Plain vector search (no graph)

python

result = await rag.aquery("amiodarone half-life", param=QueryParam(mode="naive"))

What it does: Standard embedding-based retrieval: finds the most semantically similar text chunks. Ignores the knowledge graph entirely.

The analogy: Reading the textbook page by page until you find the relevant paragraph. No index, no table of contents, just brute-force similarity.

When to use it: Rarely. This is your baseline for comparison - it’s traditional RAG without graph enhancement. Use it to measure how much the graph improves your answers.

Clinical example: “Patient presents with progressive dyspnea and bilateral edema.” A narrative clinical scenario where semantic similarity is sufficient and entity-level precision isn’t needed.

local: Entity-focused retrieval

python

result = await rag.aquery("amiodarone half-life", param=QueryParam(mode="local"))

What it does: Identifies specific entities in the query (”amiodarone”), retrieves their direct properties and relationships from the graph, and pulls the original text chunks linked to those entities.

The analogy: Looking up “amiodarone” in the drug handbook index, flipping to that page, and reading the pharmacokinetics section. Direct, precise, no wandering.

When to use it: Specific factual questions about named entities.

Clinical examples:

• “What CYP enzyme metabolizes warfarin?” → Finds Warfarin node → follows metabolized_by edge → CYP2C9

• “What is the target INR for mechanical mitral valves?” → Finds Warfarin node → follows monitored_by edge → INR → reads target range

• “Is diltiazem contraindicated in HFrEF?” → Finds Diltiazem node → follows contraindicated_in edge → HFrEF → Yes

• “What monitoring does amiodarone require?” → Finds Amiodarone node → follows all monitoring-related edges

global: Theme-focused retrieval

python

result = await rag.aquery(
    "What are the major challenges in managing antiarrhythmic therapy?",
    param=QueryParam(mode="global"),
)

What it does: Generates high-level search keys from the query, retrieves across broad thematic patterns in the graph, and synthesizes information that spans multiple entities and relationships.

The analogy: Asking a senior cardiologist to give a 5-minute overview of antiarrhythmic challenges. They draw from their knowledge of multiple drugs, multiple patients, multiple trials - synthesizing a narrative that no single page in the textbook contains.

When to use it: Broad conceptual questions, comparative analyses, thematic summaries.

Clinical examples:

• “How do genetic factors influence cardiovascular drug dosing?” → Traverses CYP2C9 polymorphisms → VKORC1 → CYP2D6 → synthesizes the pharmacogenomics theme

• “What are the common side effect patterns across antiarrhythmics?” → Traverses amiodarone toxicities + metoprolol bradycardia + diltiazem negative inotropy → identifies patterns

• “How has heart failure treatment evolved with SGLT2 inhibitors?” → Traverses dapagliflozin → DAPA-HF → DELIVER → HFrEF + HFpEF → synthesizes the clinical shift

hybrid: Both levels combined (the default)

python

result = await rag.aquery(
    "My patient is on warfarin and needs amiodarone - what should I know?",
    param=QueryParam(mode="hybrid"),
)

What it does: Runs both local and global retrieval, merges the results, and generates from the combined context. Gets the specific interaction facts AND the broader anticoagulation management principles.

The analogy: The consulting cardiologist who both looks up the specific interaction in the drug database (local) AND draws on their clinical experience with anticoagulation management (global) to give you a complete, nuanced answer.

When to use it: Most clinical queries. Real clinical questions almost always need both specific facts and broader context. This should be your default mode.

Clinical examples:

• “Should I start dapagliflozin in a patient with HFrEF and eGFR 22?” → Local: dapagliflozin eGFR threshold (≥20) → Global: SGLT2i evidence in CKD + HF

• “How should I manage anticoagulation when adding amiodarone?” → Local: warfarin-amiodarone interaction details → Global: anticoagulation monitoring principles

• “What rate control options are safe in heart failure?” → Local: metoprolol (safe in HFrEF) and diltiazem (contraindicated in HFrEF) → Global: rate control strategy in HF

How Dual-Level Retrieval Works Under the Hood

When you query in hybrid mode, LightRAG runs two parallel retrieval pipelines:

The merge step deduplicates overlapping content (both pipelines might retrieve the same amiodarone chunk) and orders results by relevance.

The LLM then generates from this combined context: getting both the “reduce warfarin by 30–50%” fact AND the “monitor INR within 1 week and reassess at steady state” management principle.

The Decision Cheat Sheet

The practical rule: When in doubt, use hybrid. It’s slightly slower than local or global alone (two retrieval passes instead of one), but the latency difference is typically under 200ms, negligible for clinical use. The accuracy gain from combining both levels consistently outweighs the minor speed cost.

Your Takeaway for Today

LightRAG’s four query modes give you precision when you need it (local), synthesis when you need it (global), and both when you need both (hybrid).

• Local mode traverses specific entities and relationships for factual answers.

• Global mode searches across thematic patterns for broad synthesis.

• Hybrid mode, your default, combines both for the complete clinical picture. Match the mode to the question type, and your knowledge graph answers at exactly the right level of granularity.

Coming Tomorrow: Day 27

Visualizing Your Medical Knowledge Graph

You have built a knowledge graph and queried it at multiple levels. Tomorrow you see it. You will visualize the entity-relationship network, identify clusters, trace multi-hop paths, and produce visuals that make the knowledge structure tangible to clinicians and stakeholders who’ve never heard of a “knowledge graph.” The picture that makes your CMIO say “I get it.”

→ Subscribe to RAG for Healthcare so you don’t miss Day 27.

Teodora Szasz, PhD | Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

You will feed cardiovascular pharmacology content into LightRAG and watch it automatically extract entities (drug names, conditions, enzymes, lab tests), identify relationships (treats, metabolized_by, contraindicated_in), and build a queryable knowledge graph: in about 30 lines of code.

Subscribe now

Setup: One Install, One API Key

LightRAG is distributed as lightrag-hku on PyPI (currently v1.4.12, March 2026). Install it with:

python

pip install lightrag-hku

Set your OpenAI API key (LightRAG uses it for both entity extraction and embeddings):

python

import os
os.environ["OPENAI_API_KEY"] = "your-key-here"

That’s the entire setup.

The Clinical Data

We will use a curated cardiovascular pharmacology reference - the same kind of content you’d find in a hospital formulary or a WHO Model Formulary chapter:

python

cardio_pharmacology = """
Warfarin is an oral anticoagulant that inhibits vitamin K epoxide reductase,
preventing the synthesis of vitamin K-dependent clotting factors (II, VII, IX, X).
Warfarin is primarily metabolized by CYP2C9, with minor contribution from CYP3A4.
Genetic polymorphisms in CYP2C9 (particularly *2 and *3 variants) and VKORC1
result in altered warfarin sensitivity, requiring dose adjustments. Warfarin is
monitored by INR, with a therapeutic target of 2.0-3.0 for most indications and
2.5-3.5 for mechanical mitral valves. Warfarin is indicated for atrial fibrillation,
venous thromboembolism, and mechanical heart valves. Warfarin interacts with numerous
medications including amiodarone (increases INR via CYP2C9 inhibition, reduce warfarin
dose by 30-50%), fluconazole (potent CYP2C9 inhibitor, significant INR elevation),
and rifampin (potent CYP inducer, dramatically reduces warfarin effect). Warfarin
is contraindicated in pregnancy (teratogenic, causes warfarin embryopathy).

Amiodarone is a class III antiarrhythmic used for atrial fibrillation and ventricular
tachycardia. Amiodarone has an extremely long half-life of 40-55 days. Amiodarone
causes thyroid dysfunction (both hypothyroidism and hyperthyroidism) due to its
high iodine content and direct thyroid effects. Amiodarone causes pulmonary toxicity
in 1-5% of patients, requiring baseline and annual pulmonary function tests and
chest X-rays. Amiodarone causes hepatotoxicity, requiring liver function monitoring
every 6 months. Amiodarone inhibits CYP2C9, CYP2D6, and CYP3A4, causing interactions
with warfarin, digoxin, and many other medications. When initiating amiodarone in a
patient on warfarin, reduce warfarin dose by 30-50% and check INR within 1 week.

Metoprolol succinate is a selective beta-1 blocker used for heart failure with reduced
ejection fraction, hypertension, and atrial fibrillation rate control. Target dose
for HFrEF is 200mg daily. Metoprolol is metabolized by CYP2D6. Metoprolol should be
started at low doses (12.5-25mg daily) in heart failure and titrated up every 2 weeks.
Metoprolol is contraindicated in decompensated heart failure, severe bradycardia,
and second or third-degree heart block without a pacemaker.

Diltiazem is a non-dihydropyridine calcium channel blocker used for atrial fibrillation
rate control, hypertension, and angina. Diltiazem is contraindicated in heart failure
with reduced ejection fraction due to negative inotropic effects. Diltiazem inhibits
CYP3A4 and can increase levels of drugs metabolized by this enzyme. Diltiazem should
not be combined with beta-blockers in patients with impaired cardiac function due to
risk of severe bradycardia and heart block.

Dapagliflozin is an SGLT2 inhibitor approved for heart failure (both HFrEF and HFpEF),
type 2 diabetes, and chronic kidney disease. Dapagliflozin reduces heart failure
hospitalizations and cardiovascular death based on DAPA-HF and DELIVER trials. Dose
is 10mg daily regardless of diabetes status. Dapagliflozin can be initiated with eGFR
as low as 20 mL/min. Monitor for genital mycotic infections and euglycemic DKA
(rare but serious). Dapagliflozin does not require dose adjustment for renal impairment.
"""

Five drugs. Multiple mechanisms, interactions, contraindications, monitoring requirements, and clinical trial references. Rich relationship territory.

Build the Knowledge Graph: 30 Lines

python

import asyncio
from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed
from lightrag.kg.shared_storage import initialize_pipeline_status
from lightrag.utils import setup_logger

setup_logger("lightrag", level="INFO")

async def build_and_query():
    # ── INITIALIZE ──
    rag = LightRAG(
        working_dir="./cardio_kg",
        llm_model_func=gpt_4o_mini_complete,
        embedding_func=openai_embed,
    )
    await rag.initialize_storages()
    await initialize_pipeline_status()

    # ── INGEST (this builds the knowledge graph automatically) ──
    await rag.ainsert(cardio_pharmacology)
    print(" Knowledge graph built!")

    # ── QUERY: Low-level (specific facts) ──
    result = await rag.aquery(
        "What enzyme metabolizes warfarin?",
        param=QueryParam(mode="local"),  # Low-level retrieval
    )
    print(f"\n Low-level: {result}")

    # ── QUERY: High-level (themes and synthesis) ──
    result = await rag.aquery(
        "How do drug interactions affect anticoagulation management?",
        param=QueryParam(mode="global"),  # High-level retrieval
    )
    print(f"\n High-level: {result}")

    # ── QUERY: Hybrid (both levels) ──
    result = await rag.aquery(
        "What drugs treat atrial fibrillation and what are their major risks?",
        param=QueryParam(mode="hybrid"),  # Both levels combined
    )
    print(f"\n Hybrid: {result}")

asyncio.run(build_and_query())

That’s it. LightRAG reads the text, extracts entities and relationships using the LLM, builds the knowledge graph, and answers queries with three retrieval modes.

What Just Happened Under the Hood

When you called rag.ainsert(), LightRAG:

1. Chunked the pharmacology text into segments

2. Sent each chunk to GPT-5.4 with an extraction prompt

3. Extracted entities: Warfarin, CYP2C9, Vitamin K, INR, Amiodarone, Metoprolol, Diltiazem, Dapagliflozin, HFrEF, HFpEF, Atrial Fibrillation, CYP2D6, CYP3A4...

4. Extracted relationships: Warfarin→metabolized_by→CYP2C9, Amiodarone→inhibits→CYP2C9, Diltiazem→contraindicated_in→HFrEF, Dapagliflozin→treats→HFpEF...

5. Deduplicated entities (merging “warfarin” and “Warfarin”)

6. Profiled each entity with a summary description

7. Embedded entity and relationship descriptions as vectors

8. Stored everything — graph structure + original text chunks + vector indices

All of this from a single ainsert() call.

The Three Query Modes

Five Queries to Try

Once your graph is built, these queries showcase what LightRAG can do that flat RAG can’t:

python

# Multi-hop: Drug → Enzyme → Other drugs sharing that enzyme
"What other drugs are affected by CYP2C9 inhibition?"

# Contraindication check
"Can I give diltiazem to a patient with HFrEF?"

# Interaction chain
"If I start amiodarone, what other medications need dose adjustments?"

# Comparative
"Compare metoprolol and diltiazem for atrial fibrillation rate control"

# Synthesis across mechanisms
"Which cardiovascular drugs require genetic testing before prescribing?"

Each of these requires traversing multiple entities and relationships. The kind of multi-hop reasoning that makes knowledge graphs powerful (Day 22).

Incremental Updates: Add Without Rebuild

When new drug information arrives, just insert it:

python

new_drug_info = """
Rivaroxaban is a direct oral anticoagulant (DOAC) that inhibits Factor Xa.
Unlike warfarin, rivaroxaban does not require INR monitoring...
"""

await rag.ainsert(new_drug_info)
# The knowledge graph updates incrementally — no rebuild needed

LightRAG extracts new entities, links them to existing ones where they overlap (e.g., “Rivaroxaban” gets connected to “Atrial Fibrillation” via a treats relationship), and the graph grows organically. This is critical for healthcare, where formularies update monthly and new drug approvals arrive regularly.

Your Takeaway for Today

LightRAG turns clinical text into a queryable knowledge graph automatically: extract entities, build relationships, and answer multi-hop clinical questions in ~30 lines of code.

Three query modes (local, global, hybrid) handle everything from specific drug facts to thematic synthesis. Incremental updates mean your graph grows with your knowledge base.

Tomorrow, we go deeper into dual-level retrieval and when each mode shines.

Coming Tomorrow: Day 26

Dual-Level Retrieval - Getting Both the Facts and the Big Picture

Today you built the graph and ran basic queries. Tomorrow we explore the dual-level retrieval system in depth - when to use local vs. global vs. hybrid mode, how to tune retrieval parameters for clinical accuracy, and the performance characteristics that matter at scale.

→ Subscribe to RAG for Healthcare so you don’t miss Day 26.

Subscribe now

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Yesterday you learned that the best healthcare RAG systems combine embeddings (find what’s relevant) with knowledge graphs (trace how things connect). The three-phase architecture: retrieve, augment, generate.

The question left hanging: Who builds the knowledge graph?

Manually constructing a knowledge graph from clinical documents (extracting every entity, labeling every relationship, resolving synonyms) is brutally labor-intensive. A 200-page pharmacology textbook might contain 5,000 entities and 15,000 relationships. No one is tagging those by hand.

LightRAG does it automatically. You feed it documents. It chunks the text, uses an LLM to extract entities and relationships, builds the knowledge graph, and then combines graph traversal with vector retrieval. All in one framework. Published in 2024, accepted at EMNLP 2025, and under active development with multimodal support and RAGAS evaluation as of March 2026.

Subscribe now

In benchmarks, it outperforms naive RAG, HyDE, and Microsoft’s GraphRAG across retrieval accuracy, response quality, and efficiency. Here’s why.

How LightRAG Works (5 Steps)

Step 1: Chunk the documents

Same as traditional RAG. The text gets split into manageable chunks.

Step 2: Extract entities and relationships with an LLM

This is the breakthrough. LightRAG sends each chunk to an LLM (GPT-5.4, Qwen, or any capable model) with an extraction prompt: “Identify all entities and their relationships in this text.”

From a pharmacology chunk about warfarin, the LLM extracts:

Clinical context: This extraction captures the mechanistic knowledge that flat text retrieval misses. CYP2C9 is the cytochrome P450 enzyme responsible for metabolizing warfarin. Genetic polymorphisms in CYP2C9 (particularly *2 and *3 variants) cause slow warfarin metabolism, requiring lower doses - a pharmacogenomic relationship that LightRAG can extract and traverse.

Step 3: Build the knowledge graph

Extracted entities become nodes. Extracted relationships become edges. LightRAG deduplicates entities (merging “warfarin” and “Warfarin” and “Coumadin”), profiles each entity with a summary description, and connects everything into a navigable graph.

The key design choice: LightRAG is chunk-centric, not triple-centric. Each entity and relationship stays linked to the original text chunk it was extracted from. When you retrieve an entity, you also get the original passage, preserving context that pure triple stores lose.

Step 4: Index everything for dual-level retrieval

LightRAG creates two types of search keys:

• Low-level keys: Linked to specific entities and relationships. Answer precise factual questions: “What enzyme metabolizes warfarin?”

• High-level keys: Linked to broader themes and concepts. Answer abstract questions: “How do genetic polymorphisms affect anticoagulation therapy?”

Both key types get embedded and stored as vectors - so retrieval uses the same fast similarity search you already know (Days 3–6).

Step 5: Retrieve and generate

When a query arrives, LightRAG:

1. Generates low-level and high-level search keys from the query

2. Retrieves matching entities, relationships, and original text chunks

3. Feeds everything - graph structure + source text - to the LLM for generation

The result: Answers that combine the precision of graph traversal with the contextual richness of the original documents.

Dual-Level Retrieval: Why It Matters for Healthcare

This is LightRAG’s most powerful feature for clinical use.

Low-level: Facts and specifics

“What is the renal dose adjustment for meropenem?”

Precise. Deterministic. Exactly what a pharmacist needs.

High-level: Themes and synthesis

“How has the approach to antibiotic stewardship evolved in the past decade?”

High-level retrieval aggregates across multiple entities and relationships, connecting stewardship principles, de-escalation evidence, shorter duration trials, and resistance patterns into a thematic summary that no single chunk contains.

The analogy: Low-level retrieval is asking the hospital pharmacist a specific drug question - they give you an exact answer. High-level retrieval is asking the infectious disease attending to explain the philosophy behind the stewardship program - they synthesize across their experience.

Most clinical queries need both. “Should I de-escalate this patient’s piperacillin-tazobactam?” requires specific culture data (low-level) AND understanding of de-escalation principles (high-level).

LightRAG’s dual retrieval handles both simultaneously.

LightRAG vs. Naive RAG vs. GraphRAG

The critical advantage for healthcare:

LightRAG’s incremental update capability means you can add new guidelines, new drug approvals, or updated protocols without rebuilding the entire graph.

In a clinical setting where formularies update monthly and guidelines update annually, this is essential.

What Makes It “Light”

Three things that make LightRAG faster and cheaper than Microsoft’s GraphRAG:

1. No community detection step. GraphRAG runs the Leiden algorithm to cluster entities into communities, then generates summaries for each community. This is expensive and slow. LightRAG skips it. Entities and relationships are indexed directly.

2. Vector-indexed graph. Instead of traversing the full graph at query time, LightRAG embeds entity and relationship descriptions as vectors. Retrieval is a fast similarity search (Day 16), not a full graph traversal.

3. Incremental updates. New documents get chunked, entities extracted, and added to the existing graph - no rebuild required. GraphRAG needs to re-cluster the entire graph when new data arrives.

Practical Considerations for Healthcare

LLM requirements: LightRAG uses an LLM for entity extraction (Step 2), which means extraction quality depends on model capability. The project recommends models with at least 32B parameters and 32K+ context. For clinical documents with dense medical terminology, use the strongest model available for extraction - GPT-5.4 or equivalent.

Cost: The extraction step (running every chunk through an LLM) is a one-time indexing cost. For a 200-page clinical guideline, expect a few dollars in API costs. Queries after indexing are fast and cheap.

HIPAA: If your documents contain PHI, run extraction with a local LLM (Qwen, Llama, etc.) to keep data on-premises. LightRAG supports open-source models for all steps.

Storage backends: As of March 2026, LightRAG supports Neo4j, MongoDB, PostgreSQL, and OpenSearch as storage backends - all options that healthcare IT teams are familiar with.

Your Takeaway for Today

LightRAG automatically builds knowledge graphs from your documents using LLM-based entity extraction, then combines graph traversal with vector retrieval in a dual-level system - low-level for specific facts, high-level for thematic synthesis.

It’s faster and cheaper than GraphRAG, supports incremental updates, and preserves links to original source text.

For healthcare, this means you can feed it clinical guidelines and get a system that answers both “What is the dose of X?” and “How has the approach to Y evolved?” - without manually building a knowledge graph.

Coming Tomorrow: Day 25

Building a Medical Knowledge Graph with LightRAG

Today was how LightRAG works. Tomorrow you build one. You will feed clinical pharmacology content into LightRAG, watch it extract entities and relationships, and query it with both low-level and high-level clinical questions. Hands-on, with code.

→ Subscribe to RAG for Healthcare so you don’t miss Day 25.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Question 1: “Patient presents with crushing substernal chest pain, diaphoresis, and nausea. What should I consider?”

Your embedding-based RAG nails this. “Crushing chest pain” and “myocardial infarction” are semantically close (Day 3). The retriever finds ACS management guidelines instantly. Score: 0.93.

Question 2: “This patient is on warfarin, amiodarone, and omeprazole. Are there interactions I should know about?”

Your embedding-based RAG struggles. It finds chunks mentioning these drugs, but it can’t trace the specific interaction pathways: warfarin + amiodarone → potentiated anticoagulation via CYP inhibition → bleeding risk. It doesn’t know that omeprazole reduces clopidogrel efficacy but has minimal interaction with warfarin. The answer is vague where it should be precise.

Clinical context: The warfarin-amiodarone interaction is one of the most dangerous in cardiology. Amiodarone inhibits CYP2C9, the enzyme that metabolizes warfarin. When both are co-prescribed, warfarin levels can increase 30–50%, pushing INR into dangerous territory and dramatically increasing bleeding risk. This isn’t a “maybe” - it requires mandatory dose reduction and increased INR monitoring. An imprecise answer here could lead to a hemorrhagic stroke.

Same RAG system. Same embedding model. Same FAISS index. One question answered brilliantly. One answered dangerously.

The problem isn’t your RAG. The problem is using only one tool for two fundamentally different types of questions.

The Two Types of Clinical Questions

Every clinical question falls into one of two categories:

Type 1: “What is relevant to this situation?”

Find me information that’s semantically related to what I’m describing.

• “Management of new-onset HFrEF in a 65-year-old”

• “Antibiotic options for hospital-acquired pneumonia”

• “Patient with dyspnea, orthopnea, and bilateral edema”

Best tool: Embeddings + vector search. These are open-ended, context-rich questions where semantic similarity excels. You don’t know exactly which document contains the answer - you need the retriever to find it based on meaning.

Type 2: “What connects X to Y?”

Trace specific relationships between named entities.

• “What are the drug interactions for warfarin?”

• “Which beta-blockers are contraindicated in asthma?”

• “What labs should I monitor on daptomycin?”

Best tool: Knowledge graphs. These are structured, relationship-specific questions where you need deterministic, complete answers. You know the entities - you need the connections between them.

The insight that changes everything: Most real clinical questions contain both types. “My patient has new-onset AFib and is on warfarin for a mechanical valve — what rate control options are safe?” This needs semantic retrieval (AFib management guidelines) and relationship traversal (drug interactions with warfarin, contraindications with mechanical valves).

Neither tool alone gives a complete answer. Together, they do.

The Three-Phase Architecture

Here’s how production healthcare AI systems combine both:

The analogy: A consulting physician gets a consult request (the query).
Phase 1: they pull the relevant guidelines from the shelf (embeddings).
Phase 2: they check the drug interaction database and the patient’s allergy list (knowledge graph).
Phase 3: they synthesize both into a recommendation (LLM).

No good consultant skips either step.

What Phase 2 Adds

Without the knowledge graph augmentation, the LLM receives guideline chunks that mention warfarin but may not explicitly list every interaction. The LLM might fill the gap from training data - which is hallucination (Day 2).

With the knowledge graph, the context now includes:

This structured fact gets injected alongside the retrieved chunks. The LLM doesn’t need to infer the interaction - it’s explicitly in the context. Grounded. Deterministic. Auditable.

When to Use What

The practical rule:

• If the question contains named clinical entities (drug names, specific conditions, lab values) AND requires understanding relationships between them: use both.

• If it’s purely a “find me something relevant” question - embeddings are sufficient.

• If it’s purely a “what connects A to B” question - the knowledge graph alone is faster and more precise.

The Cost of Getting This Wrong

Using only embeddings when you need a knowledge graph → imprecise or incomplete answers on relationship questions. The warfarin interaction example: a vague answer where a precise one is life-or-death.

Using only a knowledge graph when you need embeddings → brittle, narrow answers on open-ended questions. A graph can tell you “metoprolol treats AFib” but can’t find a guideline paragraph that discusses rate control strategy in the context of heart failure with preserved ejection fraction and renal impairment.

Using both when you only need one → unnecessary complexity and latency. A simple “what is the dose of amoxicillin for CAP?” doesn’t need a graph lookup. Don’t over-engineer.

The judgment of when to use which tool is the architectural skill that separates RAG practitioners who build systems that work from those who build systems that impress in demos but fail in production.

Where This Is Heading

Tomorrow (Day 24) you will learn LightRAG: a graph-based RAG framework that automates the three-phase architecture. It extracts entities and relationships from your documents automatically, builds the knowledge graph for you, and combines graph traversal with vector retrieval in a single query.

On Day 25, you will learn GraphRAG (Microsoft’s approach) - a different architecture that uses community detection to organize your knowledge graph into hierarchical summaries.

Both build directly on today’s conceptual framework. If you understand the three-phase architecture - retrieve, augment, generate - everything that follows will click immediately.

Your Takeaway for Today

Embeddings and knowledge graphs are not competitors: they solve different types of questions.

Embeddings find what’s relevant (semantic similarity).
Knowledge graphs find what’s connected (explicit relationships).

The best healthcare RAG systems use both in a three-phase architecture: retrieve with embeddings, augment with knowledge graph facts, generate with the LLM.
This framework guides every architecture decision you’ll make from here forward.

Coming Tomorrow: Day 24

LightRAG - The Graph-Based RAG That Outperforms Everything

Today was the theory. Tomorrow is the tool. LightRAG automatically extracts entities and relationships from your clinical documents, builds a knowledge graph, and combines it with vector retrieval - in one framework. You’ll see how it handles the queries that stumped pure embedding-based RAG.

→ Subscribe to RAG for Healthcare so you don’t miss Day 24.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Your retriever: hybrid search, reranked, metadata-filtered, the full Week 3 stack - finds chunks about AFib treatment and chunks about heart failure contraindications. But the answer requires connecting information across those chunks: metoprolol treats AFib, metoprolol is a beta-blocker, beta-blockers should be initiated only in compensated (not decompensated) heart failure, diltiazem treats AFib, diltiazem is contraindicated in HFrEF entirely.

The retriever found the right documents. But the reasoning (connecting drug to indication to contraindication across multiple relationships) is something flat document retrieval was never designed to do.

This is where knowledge graphs enter the picture.

Subscribe now

What Is a Knowledge Graph

A knowledge graph is a structured network of entities (things) connected by relationships (how things relate to each other).

Every piece of information is stored as a triple:
Entity → Relationship → Entity

The analogy:
A vector database is a library - you search by topic similarity and get back relevant pages.

A knowledge graph is a map - you navigate by following connections between specific places.

The library helps you find information about a topic. The map helps you trace paths between topics.

When the cardiologist asks “What drugs treat AFib but are contraindicated in decompensated HF?”, the knowledge graph traces two paths simultaneously:

That’s a multi-hop query - and it’s what knowledge graphs do best.

The Three Building Blocks

Triples are simple, composable, and machine-readable.

A graph of 10,000 triples can answer questions that would require reading hundreds of pages of unstructured text.

What Knowledge Graphs Can Do That Vector Search Can’t

Multi-hop reasoning

“What are the side effects of drugs used to treat conditions that increase stroke risk?”

A vector search would need to find a single document that connects all three concepts. A knowledge graph walks the path step by step.

Explicit contraindication checking

“Can I give this patient diltiazem?” (Patient has HFrEF)

Drug interaction networks

“What interactions exist for a patient on warfarin, amiodarone, and metformin?”

Temporal patient journeys

“What happened to this patient between admission and discharge?”

The graph encodes the clinical reasoning chain as a navigable path.

Healthcare Knowledge Graphs That Already Exist

You don’t need to build a knowledge graph from scratch.

Several large-scale medical knowledge graphs are publicly available:

SNOMED CT: the most comprehensive clinical terminology system. Over 350,000 concepts with relationships (is-a, finding-site, causative-agent, etc.). Used by EHR systems worldwide.

RxNorm: maps between drug names, ingredients, dose forms, and strengths. Essential for medication-related graphs. Links brand names, generics, and clinical drug concepts.

UMLS (Unified Medical Language System): integrates over 200 biomedical vocabularies including SNOMED CT, RxNorm, ICD-10, MeSH, and others into a single metathesaurus with semantic relationships.

Drug interaction databases: DrugBank, the FDA Adverse Event Reporting System (FAERS), and commercial databases like Lexicomp encode drug-drug and drug-condition interactions as structured relationships.

Clinical context: SNOMED CT is the backbone of clinical documentation in many EHR systems. When a physician enters “Type 2 Diabetes Mellitus” in the chart, SNOMED CT provides the concept code (44054006), its hierarchical relationships (is-a Diabetes Mellitus, is-a Metabolic Disease), and its associated findings and procedures. This structure is already a knowledge graph - most institutions just don’t use it as one.

Knowledge Graphs vs. Vector Databases

These are not competitors. They solve different problems:

The punchline:

Vector databases are great at finding what’s relevant.

Knowledge graphs are great at understanding how things connect.

Tomorrow (Day 23) we combine both - and the result is more powerful than either alone.

A Minimal Knowledge Graph in Python

You don’t need a specialized graph database to start.
NetworkX gives you a working knowledge graph in 10 lines:

python

import networkx as nx

G = nx.DiGraph()

# Add triples
G.add_edge("Metoprolol", "Atrial Fibrillation", relationship="treats")
G.add_edge("Metoprolol", "Decompensated HF", relationship="contraindicated_in")
G.add_edge("Diltiazem", "Atrial Fibrillation", relationship="treats")
G.add_edge("Diltiazem", "HFrEF", relationship="contraindicated_in")
G.add_edge("Atrial Fibrillation", "Stroke", relationship="increases_risk_of")

# Query: What treats AFib?
afib_drugs = [n for n in G.predecessors("Atrial Fibrillation")
              if G[n]["Atrial Fibrillation"]["relationship"] == "treats"]
print(f"Drugs that treat AFib: {afib_drugs}")
# → ['Metoprolol', 'Diltiazem']

# Multi-hop: Treats AFib AND contraindicated in something?
for drug in afib_drugs:
    contras = [(drug, target) for target in G.successors(drug)
               if G[drug][target]["relationship"] == "contraindicated_in"]
    for d, c in contras:
        print(f"  {d} treats AFib but is contraindicated in {c}")
# → Metoprolol treats AFib but is contraindicated in Decompensated HF
# → Diltiazem treats AFib but is contraindicated in HFrEF

That’s the cardiologist’s original question: answered in milliseconds with deterministic accuracy. No embedding model, no similarity threshold, no hallucination risk.

Your Takeaway for Today

Knowledge graphs store medical knowledge as entities connected by relationships, triples of the form (Subject, Predicate, Object).

They excel at multi-hop reasoning, contraindication checking, and drug interaction queries - the relationship-rich questions that vector search handles poorly.

They complement, not replace, your RAG pipeline.

Tomorrow we combine both into something more powerful than either alone.

Coming Tomorrow: Day 23

Embeddings vs. Knowledge Graphs - Competitors or Best Friends?

Today you learned what knowledge graphs are.

Tomorrow you learn how to combine them with the vector-based RAG system you’ve been building: Graph RAG, where semantic retrieval meets structured reasoning.

This is where the series crosses from standard RAG into the architecture that the most advanced healthcare AI systems are using right now.

→ Subscribe to RAG for Healthcare so you don’t miss Day 23.

Subscribe now

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

Week 4 starts tomorrow: Knowledge Graphs, Graph RAG, Evaluation, and Multimodal RAG.

→ Subscribe free for every daily article. → Subscribe paid for the build projects and notebooks.

Teodora

We are at an inflection point. Every hospital, every health system, every clinical research team is about to face the same question:

Can your team build AI that works on real data (clinical or not) - or do you need to hire someone who can?

The people who can answer “yes, we can build it” will lead the next decade of technology (especially in healthcare).

The people who can’t will watch from the sidelines while their institutions pay consultants $300/hour to build what you’re about to build in a notebook.

This is not about learning a fun new skill. AI literacy in 2026 is career survival. It’s institutional survival. The hospital that can build a clinical RAG system over its own data - internally, securely, auditably - has a competitive advantage that no vendor can match. The hospital that can’t is dependent on every vendor’s pricing, every vendor’s timeline, every vendor’s data privacy policies.

This series: 35 days, 5 build projects, every concept explained so clearly you can teach it - is the fastest path from “I’ve heard of RAG” to “I built it, I deployed it, I own it.”

Today’s build project is the one that changes how people see you.

Why Day 21 Is the Most Important Build Project So Far

Day 7 built a RAG over one document type (guidelines). Day 14 added production features (logging, confidence). Both are single-source systems.

Real clinical decisions are never single-source.

When a consulting physician evaluates a patient, they don’t read just the progress notes. They check the labs. They pull up the imaging. They cross-reference the medication list against the renal function. They synthesize a unified clinical picture from multiple data types - each with different structure, vocabulary, and clinical meaning.

Today you build an AI that does the same thing.

Three separate FAISS indices:

• One for clinical progress notes.

• One for laboratory results.

• One for radiology reports.

When a clinician asks “What is the trend in this patient’s renal function and has imaging shown any changes?” - the system queries all three, merges the results with source attribution, and generates a unified answer that synthesizes across data types.

This is the architecture used in real clinical decision support systems. And you’ll have it running in 90 seconds.

What You’re Getting Today

The Clinical Data

Two complete patient stories, spanning multiple days, with realistic clinical detail:

Read more

A clinician asks a complex pharmacology question.

Your pipeline:

Hybrid search (Day 17) → reranking (Day 18) → metadata filtering (Day 19) retrieves 15 excellent chunks. Concatenated, they total 12,000 tokens. GPT-5.4 has a 1 Million token context window. Plenty of room, right?

Here is the problem: more context does not mean better answers.

Research consistently shows that LLMs pay the most attention to the beginning and end of the context, and tend to ignore information in the middle. This is the “Lost in the Middle” phenomenon. And it means that your 15 carefully retrieved chunks might perform worse than a well-ordered 5.

Lost in the Middle: The Problem

Subscribe now

A landmark study by Liu et al. (Stanford, 2023) tested LLMs on a task where the answer was placed at different positions within the context. The finding: accuracy dropped 20–30% when the relevant information was in the middle of a long context, compared to when it was at the beginning or end.

The analogy: A physician reading a 50-page patient chart during a busy shift. They read the first few pages carefully (chief complaint, recent labs). They read the last page carefully (the assessment and plan). The 30 pages in the middle? Skimmed at best. If the critical drug interaction is buried on page 27, it might get missed - not because it wasn’t in the chart, but because attention is finite.

LLMs exhibit the same pattern. The context window is technically huge. Effective attention is not.

Clinical impact: If the chunk about warfarin contraindication in pregnancy lands in position 8 of 15, surrounded by general anticoagulation content, the LLM might generate an answer that overlooks it entirely. The information was retrieved. It was in the context. It was ignored.

The Three Rules

Rule 1: Fewer, Better Chunks Beat More, Okay Chunks

The sweet spot for clinical RAG is 4–7 chunks.
This isn’t arbitrary - it balances three factors:

• Enough context to answer complex multi-faceted questions

• Little enough that every chunk gets the model’s full attention

• Room for the response within a reasonable token budget

The practical approach:

1. Retrieve broadly (20 chunks), rerank (Day 18), then take the top 5.

2. If the question is clearly simple (”What is first-line for uncomplicated UTI?”), take the top 3.

3. If the question is complex and multi-faceted (”Management of HFrEF with CKD stage 4, hyperkalemia, and atrial fibrillation”), consider the top 7.

Rule 2: Put the Best Evidence First and Last

If you must send more than 5 chunks, order them strategically to exploit the attention pattern:

python

def order_for_attention(chunks_with_scores):
    """Order chunks to exploit beginning/end attention bias."""
    sorted_chunks = sorted(chunks_with_scores, key=lambda x: x[1])  # Best first
    if len(sorted_chunks) <= 3:
        return sorted_chunks

    best = sorted_chunks[:2]          # Top 2 → beginning
    worst = sorted_chunks[2:-1]       # Middle → middle (least attention)
    second_best = [sorted_chunks[-1]] # Last strong chunk → end

    return best + worst + second_best

This is a simple reordering: zero cost, zero latency, measurable improvement on longer contexts.

Rule 3: Budget Your Tokens

Every API call has a cost. Here’s the math:

For GPT-5.4 at current pricing, a typical RAG call with 5 chunks, compared with 15 chunks:

At 1,000 queries/day: $14/day or $420/month. Nearly double the cost, with potentially worse answer quality due to lost-in-the-middle.

This is the rare case where doing less is better on both dimensions.

Dynamic Chunk Selection

Not every query needs the same number of chunks. A simple heuristic:

python

def select_top_k(reranked_chunks, scores):
    """Dynamically choose how many chunks to send."""
    top_score = scores[0]

    # If the best chunk is very strong, fewer chunks suffice
    if top_score > 0.85:
        return reranked_chunks[:4]

    # If scores are moderate, include more context
    if top_score > 0.70:
        return reranked_chunks[:6]

    # If scores are weak, cast a wider net (but cap at 8)
    return reranked_chunks[:8]

The analogy: When a cardiologist is very confident in a diagnosis (high score), they order 2–3 targeted tests. When uncertain (moderate score), they order a broader workup. When truly unsure (low score), they cast a wide net - but they don’t order every test in the hospital.

Counting Tokens Before You Send

Always verify your token budget before the API call. Surprises are expensive:

python

import tiktoken

def count_tokens(text, model="gpt-5.4"):
    encoding = tiktoken.encoding_for_model("gpt-4o")  # Use gpt-4o encoding
    return len(encoding.encode(text))

# Check before sending
total = count_tokens(system_prompt + context + query)
print(f"Input tokens: {total}")

if total > 15000:
    print("⚠️ Context may be too large — consider fewer chunks")

This takes milliseconds and prevents unexpected bills.

Your Takeaway for Today

More context is not better context.

The “Lost in the Middle” phenomenon means LLMs ignore information buried in long contexts.

The sweet spot for clinical RAG is 4–7 chunks, ordered with the best evidence at the beginning and end.

Fewer chunks = better answers + lower cost.

Budget your tokens, order your chunks strategically, and dynamically adjust K based on retrieval confidence.

Coming Tomorrow: Day 21 (Premium Build Project)

BUILD PROJECT: Multi-Source RAG Combining Clinical Notes + Lab Results + Imaging Reports

Tomorrow, paid subscribers get Build Project #3 - a RAG system that ingests multiple data types (clinical notes, lab CSVs, radiology text reports) into a single searchable knowledge base with source-type metadata.

You will use hybrid search, reranking, metadata filtering, and context window management - everything from Week 3, running in one pipeline.

This is the project that proves RAG can handle the messy reality of multi-source clinical data.

→ Subscribe to RAG for Healthcare to get the Day 21 Build Project.

Subscribe now

Teodora Szasz, PhD — Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

The retriever returns five chunks:

• Three are about adult coronary artery disease.

• One is about pediatric fever workup.

• One is the actual Kawasaki disease guideline from pediatric cardiology.

The adult coronary artery chunks have high semantic similarity: Kawasaki disease causes coronary artery aneurysms. So the vocabulary overlaps heavily with adult coronary disease. Cosine similarity can’t tell the difference. Reranking helps but doesn’t fully solve it because both topics genuinely involve coronary artery management.

Clinical context: Kawasaki disease is a childhood vasculitis (inflammation of blood vessels) that primarily affects children under 5. Without treatment, 25% develop coronary artery aneurysms - ballooning of the coronary arteries that can cause heart attacks in children. Treatment is IV immunoglobulin (IVIG) plus high-dose aspirin, which is completely different from adult coronary disease management. Returning adult guidelines for a Kawasaki query isn’t just irrelevant - it’s the wrong treatment paradigm entirely.

The fix is simple: before the retriever searches, tell it where to look.

department=Pediatrics, age_group=0-18, document_type=clinical_guideline

Now the search only considers pediatric guideline chunks. The adult coronary disease content never enters the results. Problem solved before retrieval even begins.

What Metadata Filtering Is

Every chunk in your vector store can carry metadata = structured key-value tags attached during ingestion.

Metadata filtering restricts the search to chunks that match specific criteria before computing similarity scores.

The analogy: A hospital has one medical records system, but a pediatric cardiologist doesn’t search through adult orthopedic surgery records when looking for a patient’s echo report. The system filters by department, age, and record type first - then searches within that subset.

Without metadata: searching the entire library for a book, hoping the right one floats to the top. With metadata: walking to the pediatrics section, the cardiology shelf, the guidelines row - then searching.

Designing Your Metadata Schema

The metadata you tag during ingestion determines what you can filter on later. You can’t filter on fields you didn’t create. Design this upfront.

Here’s the schema I recommend for clinical RAG:

The practical rule: Tag the fields your clinicians would use to narrow a search if they were searching manually. If a cardiologist would say “I only want the 2024 guidelines, not the 2019 version,” then year needs to be a metadata field.

Tagging Chunks During Ingestion

Metadata is attached when you create your LangChain Document objects before they enter the vector store:

python

from langchain_core.documents import Document

chunk = Document(
    page_content="Kawasaki disease: administer IVIG 2g/kg as single infusion...",
    metadata={
        "department": "Pediatrics",
        "document_type": "clinical_guideline",
        "year": 2024,
        "age_group": "pediatric",
        "section": "treatment",
        "source": "AHA Kawasaki Disease Guideline 2024",
    }
)

This is what we did in the Day 14 build project: every chunk carried section, category, and year. Today’s article extends that pattern to a full clinical metadata schema.

Filtering at Query Time

With FAISS (Manual Filtering)

FAISS doesn’t support native metadata filtering. You filter after retrieval:

python

results = vector_store.similarity_search_with_score(query, k=20)

# Filter: only pediatric guidelines from 2023+
filtered = [
    (doc, score) for doc, score in results
    if doc.metadata.get("department") == "Pediatrics"
    and doc.metadata.get("year", 0) >= 2023
][:5]  # Take top 5 after filtering

Important: Retrieve more than you need (k=20), then filter down to your target (top 5). If you retrieve k=5 and then filter, you might end up with 1–2 results after filtering.

With Chroma, Pinecone, or Weaviate (Native Filtering)

Managed vector databases support native metadata filtering - the filter is applied during the search, not after:

python

# Chroma example
results = vector_store.similarity_search(
    query,
    k=5,
    filter={"department": "Pediatrics", "year": {"$gte": 2023}},
)

Native filtering is more efficient than post-retrieval filtering because it never computes similarity scores for irrelevant chunks. At scale (500K+ chunks), this matters.

Three Filtering Patterns for Healthcare

Pattern 1: Department Scoping

Clinician is a nephrologist. Automatically scope all queries to nephrology content:

python

filter = {"department": "Nephrology"}

This prevents the cross-specialty pollution from the Kawasaki example. A nephrology query about “AKI management” won’t return the hepatology AKI-in-cirrhosis guidelines unless the clinician explicitly requests it.

Pattern 2: Freshness Gating

Only return guidelines from the past 2 years:

python

filter = {"year": {"$gte": 2024}}

This is the direct fix for Day 13’s Failure Mode 4 (stale chunks). When you ingest the 2024 AHA heart failure guideline, the 2019 version no longer contaminates results.

Pattern 3: Multi-Field Precision

Combine filters for highly targeted retrieval:

python

filter = {
    "department": "Pediatrics",
    "age_group": "pediatric",
    "document_type": "clinical_guideline",
    "year": {"$gte": 2024},
}

Kawasaki query now searches only recent pediatric clinical guidelines. The search space might drop from 100,000 chunks to 2,000, making retrieval faster and dramatically more precise.

Metadata Filtering vs. Reranking vs. Hybrid Search

These three techniques aren’t competitors - they are layers:

The production pipeline uses all three:

Metadata filtering is the first step: it reduces the search space before anything else runs.

Think of it as the bouncer at the door: irrelevant chunks never get inside.

Your Takeaway for Today

Metadata filtering adds structure to vector search.

Tag chunks during ingestion with department, year, document type, and age group.

Filter at query time to search only the relevant subset.

This prevents cross-specialty contamination, eliminates stale guidelines, and makes retrieval faster and more precise.

Design your metadata schema upfront: you can’t filter on fields you didn’t create.

Coming Tomorrow: Day 20

Context Window Management: Feeding the Right Amount of Information to GPT

You can now retrieve with precision (metadata filtering), diversity (hybrid search), and relevance (reranking). But how much retrieved content should you actually send to the LLM? Too little and you miss information. Too much and the model gets confused: the “lost in the middle” problem.

Tomorrow: the science and practice of context window management.

→ Subscribe to RAG for Healthcare so you don’t miss Day 20.

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA

I sometimes get asked: “Why should I follow this series when I can just ask ChatGPT or Claude how to build RAG?”

Try it. Ask an LLM: “How do I add reranking to my healthcare RAG system?”

You wll get a technically correct, generic answer.

It will mention cross-encoders and maybe show you a code snippet. What it won’t tell you is why reranking matters specifically for clinical text, which failure mode from Day 13 it fixes, how it interacts with the hybrid search you built yesterday, where to place it relative to your confidence scoring from Day 14, or that a pharmacist querying “vancomycin AUC dosing” needs different reranking behavior than a physician querying “management of resistant hypertension.”

That is the difference between information and curriculum.

I spent months designing this series so that every concept builds on the last, every example is healthcare-specific, and every technique connects to the system you are actually building.

An LLM gives you ingredients. This series gives you the recipe, the cooking technique, and the experience to know when to adjust the seasoning.

Today’s seasoning adjustment is the highest-ROI improvement in all of RAG.

Subscribe now

The Problem Reranking Solves

Your retriever returns 20 chunks for the query “atrial fibrillation management in heart failure.”

Clinical context: Atrial fibrillation (AF) occurs in 30–50% of heart failure patients. Managing AF in HF is complex because the treatment priorities can conflict - rate control drugs like diltiazem are effective for AF but contraindicated in HFrEF because they worsen heart failure. Rhythm control with catheter ablation (CASTLE-AF trial) shows improved outcomes in HF patients. Anticoagulation is required but DOACs are preferred over warfarin in most cases. A clinician asking this question needs the intersection of AF and HF management - not either one separately.

Here’s what the retriever found:

The two best chunks are ranked #4 and #7. The top 3 are related but not precisely what the clinician needs. If your system sends only the top 5 chunks to the LLM (Day 6: K=5), chunk #7 - the CASTLE-AF trial data - doesn’t even make the cut.

This is Day 13’s Failure Mode 1 in action: high similarity, low relevance. The chunks are about the right topics but don’t answer the specific question.

Reranking fixes this. After reranking, the chunk about AF management in HF moves to #1, the CASTLE-AF trial moves to #2, and the tangentially related chunks drop to the bottom. The top 5 after reranking are dramatically more relevant than the original top 5.

Ten lines of code. Measurably better answers.

Why Initial Retrieval Gets the Order Wrong

Understanding why requires understanding the difference between two types of models:

Bi-encoders (Your Current Retriever)

Your embedding model (text-embedding-3-large) is a bi-encoder. It encodes the query and each chunk separately, then compares the resulting vectors with cosine similarity.

The analogy: Two doctors write independent assessments of the same case without talking to each other. Doctor A writes a summary of the question. Doctor B writes a summary of each chunk. Then you compare their summaries for overlap. They might both mention “atrial fibrillation” and “management” (so the similarity is high), but neither summary captures whether the chunk specifically answers the question.

Bi-encoders are fast (you embed the query once, compare against pre-embedded chunks) but shallow. They measure topical overlap, not answer relevance.

Cross-encoders (The Reranker)

A cross-encoder takes the query and a chunk together as a single input and outputs a relevance score. It reads both simultaneously, attending to the interaction between them.

The analogy: A single attending physician reads the clinical question and the reference document side by side, then judges: “Does this document actually answer this specific question?” That joint reading - seeing the query and chunk in context together - is fundamentally more accurate than comparing independent summaries.

Cross-encoders are slow (each query-chunk pair requires a separate model inference) but deep. They measure answer relevance, not just topical similarity.

Why Not Just Use Cross-Encoders for Everything?

Speed. A cross-encoder needs to evaluate every query-chunk pair individually. If you have 500,000 chunks, that’s 500,000 model inferences per query - minutes, not milliseconds.

The solution: Use bi-encoders (fast, approximate) to retrieve a broad initial set (20–50 chunks), then use a cross-encoder (slow, precise) to rerank just those 20–50. The best of both worlds.

Total added latency: ~200ms. Total accuracy improvement: often 20–40% better retrieval precision. That’s the ROI.

Implementation: Two Options

Option A: Cohere Rerank API (Easiest)

Cohere offers a reranking API: send your query and chunks, get back reranked results. No model hosting, no GPU.

python

# pip install cohere
import cohere

co = cohere.Client("your-cohere-api-key")

results = co.rerank(
    model="rerank-v3.5",
    query="atrial fibrillation management in heart failure",
    documents=[chunk.page_content for chunk in retrieved_chunks],
    top_n=5,
    return_documents=True,
)

for r in results.results:
    print(f"Score: {r.relevance_score:.3f} | {r.document.text[:100]}...")

Pros: No infrastructure, no GPU, excellent quality, supports 100+ languages. Cons: Data sent to Cohere’s API (same HIPAA considerations as OpenAI - check BAA status), per-query cost ($2 per 1,000 searches).

Option B: Open-Source Cross-Encoder (Local, HIPAA-friendly)

Run a cross-encoder model locally. No data leaves your infrastructure.

python

# pip install sentence-transformers
from sentence_transformers import CrossEncoder

reranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-12-v2")

query = "atrial fibrillation management in heart failure"
pairs = [(query, chunk.page_content) for chunk in retrieved_chunks]
scores = reranker.predict(pairs)

# Sort by reranking score (highest first)
reranked = sorted(
    zip(retrieved_chunks, scores),
    key=lambda x: x[1],
    reverse=True,
)

for chunk, score in reranked[:5]:
    print(f"Score: {score:.3f} | {chunk.page_content[:100]}...")

Pros: Free, runs locally, no data leaves your network, HIPAA-compatible by default. Cons: Requires more compute (a GPU helps but isn’t required for small batch sizes), slightly lower quality than Cohere for some use cases.

For healthcare production systems handling PHI: Option B is the safe default. For prototyping with non-PHI guideline text, Option A is fastest to implement.

Where Reranking Fits in Your Pipeline

Here’s the updated RAG pipeline with every technique from this series:

Notice the order: Retrieve broadly (20 chunks), rerank precisely (reorder those 20), then take the top 5.
Reranking sits between retrieval and generation.
It doesn’t replace your retriever - it refines its output.

The Numbers: Before and After

On clinical guideline retrieval tasks, adding reranking typically produces:

The improvement is largest when the initial retrieval returns chunks that are topically related but don’t precisely answer the question - which is the most common failure mode in clinical RAG (Day 13, Failure Mode 1).

Your Takeaway for Today

Reranking is the single highest-ROI improvement you can make to any existing RAG system.

Retrieve broadly with bi-encoders (fast, approximate), then rerank with a cross-encoder (slow, precise).
The cross-encoder reads query and chunk together, judging answer relevance. Not just topical similarity.

Ten lines of code, ~200ms of latency, 20–40% better retrieval precision. If you do one thing after reading this series, add reranking.

Coming Tomorrow: Day 19

Metadata Filtering: Searching by Age, Diagnosis, Department, and Date

Reranking improves ordering. Metadata filtering improves scoping - “only search cardiology guidelines from 2024” or “only retrieve chunks tagged as renal dosing.”

Tomorrow you will learn how to tag chunks with structured metadata and filter at retrieval time. This is the fix for Day 13’s Failure Mode 4 (stale chunks) and the key to multi-department clinical RAG.

→ Subscribe to RAG for Healthcare so you don’t miss Day 19.

Subscribe now

Teodora Szasz, PhD - Senior Clinical Data Scientist | FDA 510(k) AI | Co-author, EchoJEPA