How to Integrate LlamaIndex for healthcare with Supabase for startups

Combining LlamaIndex for healthcare with Supabase gives you a practical stack for building HIPAA-aware AI workflows without standing up a heavy backend. LlamaIndex handles retrieval and structured reasoning over healthcare data, while Supabase gives you Postgres, auth, storage, and row-level security for patient-facing applications and internal tools.

Prerequisites

• •Python 3.10+
• •A Supabase project with:
  • •Project URL
  • •anon key or service_role key
  • •A table for documents or patient notes
• •A LlamaIndex setup with the healthcare package installed
• •Access to your healthcare data source:
  • •PDFs, clinical notes, discharge summaries, or FHIR exports
• •Environment variables configured:
  • •SUPABASE_URL
  • •SUPABASE_SERVICE_ROLE_KEY
  • •OPENAI_API_KEY or another LLM provider key used by LlamaIndex
• •Basic familiarity with:
  • •SQL
  • •Python async/sync client usage
  • •Retrieval-Augmented Generation patterns

Integration Steps

1. •Install the packages and initialize both clients.

pip install supabase llama-index llama-index-readers-file llama-index-llms-openai llama-index-vector-stores-postgres

import os
from supabase import create_client, Client

from llama_index.core import VectorStoreIndex, StorageContext, Settings
from llama_index.core.schema import Document
from llama_index.llms.openai import OpenAI

SUPABASE_URL = os.environ["SUPABASE_URL"]
SUPABASE_SERVICE_ROLE_KEY = os.environ["SUPABASE_SERVICE_ROLE_KEY"]

supabase: Client = create_client(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)

Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0)

2. •Pull healthcare records from Supabase and convert them into LlamaIndex documents.

This pattern works well when your startup stores normalized clinical notes in Postgres tables. Keep the raw source in Supabase and let LlamaIndex build a retrieval layer on top.

response = supabase.table("clinical_notes").select("*").eq("tenant_id", "startup_a").execute()
rows = response.data

documents = []
for row in rows:
    text = f"""
    Patient ID: {row['patient_id']}
    Encounter Date: {row['encounter_date']}
    Note Type: {row['note_type']}
    Note Text: {row['note_text']}
    """
    documents.append(
        Document(
            text=text.strip(),
            metadata={
                "patient_id": row["patient_id"],
                "encounter_date": row["encounter_date"],
                "note_type": row["note_type"],
                "source_id": row["id"],
            },
        )
    )

3. •Build a healthcare retrieval index and attach persistence to Supabase-backed storage.

If you want production persistence, store embeddings in a vector-capable Postgres setup. In startups, that usually means using Supabase Postgres plus a vector extension or an external vector store connected through the same app layer.

from llama_index.vector_stores.postgres import PGVectorStore

PG_CONNECTION = (
    "postgresql://postgres:"
    f"{os.environ['SUPABASE_DB_PASSWORD']}"
    f"@db.{os.environ['SUPABASE_PROJECT_REF']}.supabase.co:5432/postgres"
)

vector_store = PGVectorStore.from_params(
    database="postgres",
    host=f"db.{os.environ['SUPABASE_PROJECT_REF']}.supabase.co",
    password=os.environ["SUPABASE_DB_PASSWORD"],
    port=5432,
    user="postgres",
    table_name="healthcare_embeddings",
    embed_dim=1536,
)

storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
)

4. •Query the index from your agent and persist audit events back into Supabase.

For healthcare apps, every answer needs traceability. Store query metadata, retrieved document IDs, and output summaries in Supabase so you can inspect behavior later.

query_engine = index.as_query_engine(similarity_top_k=3)

question = "Summarize recent respiratory issues for patient P123."
result = query_engine.query(question)

supabase.table("audit_logs").insert({
    "tenant_id": "startup_a",
    "query_text": question,
    "response_text": str(result),
    "source": "llamaindex_healthcare",
}).execute()

print(result)

5. •Add role-based access control before exposing the agent to users.

Do not rely on the model to enforce access rules. Use Supabase auth claims and row-level security so each clinician only sees records they are allowed to query.

user_id = "clinician_42"

allowed_patients_response = supabase.table("care_team_access") \
    .select("patient_id") \
    .eq("user_id", user_id) \
    .execute()

allowed_patient_ids = [row["patient_id"] for row in allowed_patients_response.data]

secure_notes_response = supabase.table("clinical_notes") \
    .select("*") \
    .in_("patient_id", allowed_patient_ids) \
    .execute()

print(f"Loaded {len(secure_notes_response.data)} accessible notes")

Testing the Integration

Run a simple end-to-end test: fetch notes from Supabase, index them with LlamaIndex, then ask a clinical question.

test_docs = [
    Document(text="Patient P123 reported shortness of breath on 2024-03-01. Prescribed albuterol.", metadata={"patient_id": "P123"}),
    Document(text="Patient P123 follow-up on 2024-03-10 shows improved breathing and no wheezing.", metadata={"patient_id": "P123"}),
]

test_index = VectorStoreIndex.from_documents(test_docs)
test_query_engine = test_index.as_query_engine()

output = test_query_engine.query("What changed in the patient's respiratory status?")
print(output)

Expected output:

The patient’s respiratory status improved between follow-up visits.
Initial shortness of breath was reported on 2024-03-01, but by 2024-03-10 there was no wheezing and breathing had improved.

If that works, your pipeline is doing three things correctly:

• •Reading structured data from Supabase
• •Building a retrieval layer with LlamaIndex
• •Returning grounded answers from indexed healthcare text

Real-World Use Cases

• •Clinical assistant for care teams
  • •Query patient histories, recent notes, medication changes, and follow-up instructions from one interface.
• •Insurance intake automation
  • •Extract relevant evidence from medical records and store review decisions plus audit trails in Supabase.
• •Startup operations dashboard
  • •Combine auth, audit logs, document storage, and retrieval into one backend for clinician-facing AI tools.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.