Cookbook

Hands-on, production-ready examples for building healthcare AI applications with HealthChain.

Getting started

Cookbooks are runnable scripts in the HealthChain repository. Clone the repo to get started:

git clone https://github.com/healthchainai/HealthChain.git
cd HealthChain
uv sync   # or: pip install healthchain

Run any cookbook from the repo root — e.g. python cookbook/sepsis_cds_hooks.py. Filter by Zero Setup below to find examples that run immediately with no external accounts.

Filter: Beginner Intermediate Advanced GenAI ML Research CDS Hooks FHIR Gateway Interop Zero Setup Clear

🚦

Working with FHIR Sandboxes

Spin up and access free Epic, Medplum, and other FHIR sandboxes for safe experimentation. Recommended first step before the other tutorials.

Beginner FHIR Gateway

🔬

Deploy ML Models: Real-Time Alerts & Batch Screening

Deploy the same ML model two ways: CDS Hooks for point-of-care sepsis alerts, and FHIR Gateway for population-level batch screening with RiskAssessment resources.

Intermediate ML Research CDS Hooks FHIR Gateway Zero Setup

💬

FHIR-Grounded Patient Q&A

Build a patient Q&A service that fetches live FHIR data, formats it as LLM context via a pipeline, and returns grounded answers. Foundation pattern for patient portal chatbots and care navigation assistants.

Beginner GenAI FHIR Gateway

🔗

Multi-Source Patient Data Aggregation

Merge patient data from multiple FHIR sources (Epic, Cerner, etc.), deduplicate conditions, prove provenance, and handle cross-vendor errors. Foundation for RAG and analytics workflows.

Intermediate GenAI FHIR Gateway

🧾

Automate Clinical Coding & FHIR Integration

Extract medical conditions from clinical documentation using AI, map to SNOMED CT codes, and sync as FHIR Condition resources for billing, analytics, and interoperability.

Advanced Interop

📝

Summarize Discharge Notes with CDS Hooks

Deploy a CDS Hooks-compliant service that listens for discharge events, auto-generates concise plain-language summaries, and delivers actionable clinical cards directly into the EHR workflow.

Beginner CDS Hooks Zero Setup

🔄

Convert Between Healthcare Data Formats

Convert between CDA, HL7v2, and FHIR formats using the interoperability engine. Handle bidirectional conversion for integrating legacy systems with modern FHIR applications.

Intermediate Interop Zero Setup

No cookbooks match the selected filters. Clear filters

---

From cookbook to service

Cookbooks are standalone scripts — run them directly to explore and experiment. When you're ready to build a proper service, scaffold a project and move your logic in:

# 1. Run a cookbook locally
python cookbook/sepsis_cds_hooks.py

# 2. Scaffold a project
healthchain new my-sepsis-service -t cds-hooks
cd my-sepsis-service

# 3. Move your hook logic into app.py, then run with config
healthchain serve

app.run() (used in cookbooks) is a convenience wrapper — equivalent to running uvicorn directly. healthchain serve reads healthchain.yaml for port, TLS, and deployment settings, and prints a startup banner so you can see what's active at a glance.

What moves from your script into healthchain.yaml:

# cookbook — everything hardcoded in Python
gateway = FHIRGateway()
gateway.add_source("medplum", FHIRAuthConfig.from_env("MEDPLUM").to_connection_string())

llm = ChatAnthropic(model="claude-opus-4-6", max_tokens=512)

app = HealthChainAPI(title="My App", service_type="fhir-gateway")
app.run(port=8000)

# healthchain.yaml — port, sources, and LLM provider declared here
service:
  type: fhir-gateway
  port: 8000

sources:
  medplum:
    env_prefix: MEDPLUM   # credentials stay in .env

llm:
  provider: anthropic
  model: claude-opus-4-6
  max_tokens: 512

# app.py — load from config instead
from healthchain.config.appconfig import AppConfig
from healthchain.gateway import FHIRGateway, HealthChainAPI

config = AppConfig.load()
gateway = FHIRGateway.from_config(config)
llm = config.llm.to_langchain()

app = HealthChainAPI(title="My App")

Credentials (API keys, client secrets) always stay in .env — never in healthchain.yaml.

Configuration reference

See the configuration reference for all available settings — security, compliance, eval, and more.