diff --git a/README.md b/README.md
index 643ea397..815f434e 100644
--- a/README.md
+++ b/README.md
@@ -4,274 +4,201 @@
-
- 
-
+
+[![PyPI Version][pypi-version-badge]][pypi]
+[![Stars][stars-badge]][stars]
+[![Downloads][downloads-badge]][pypistats]
-
+[![License][license-badge]][license]
+[![Python Versions][python-versions-badge]][pypi]
+[![Build Status][build-badge]][build]
-Connect your AI models to any healthcare system with a few lines of Python ๐ซ ๐ฅ.
+[![Substack][substack-badge]][substack]
+[![Discord][discord-badge]][discord]
-Integrating AI with electronic health records (EHRs) is complex, manual, and time-consuming. Let's try to change that.
+
-```bash
-pip install healthchain
-```
-First time here? Check out our [Docs](https://dotimplement.github.io/HealthChain/) page!
+Open-Source Framework for Productionizing Healthcare AI
-## Features
-- [x] ๐ **Gateway**: Connect to multiple EHR systems with [unified API](https://dotimplement.github.io/HealthChain/reference/gateway/gateway/) supporting FHIR, CDS Hooks, and SOAP/CDA protocols (sync / async support)
-- [x] ๐ฅ **Pipelines**: Build FHIR-native ML workflows or use [pre-built ones](https://dotimplement.github.io/HealthChain/reference/pipeline/pipeline/#prebuilt) for your healthcare NLP and AI tasks
-- [x] ๐ **InteropEngine**: Convert between FHIR, CDA, and HL7v2 with a [template-based engine](https://dotimplement.github.io/HealthChain/reference/interop/interop/)
-- [x] ๐ Type-safe healthcare data with full type hints and Pydantic validation for [FHIR resources](https://dotimplement.github.io/HealthChain/reference/utilities/fhir_helpers/)
-- [x] โก Built-in event-driven logging and operation tracking for [audit trails](https://dotimplement.github.io/HealthChain/reference/gateway/events/)
-- [x] ๐ Deploy production-ready applications with [HealthChainAPI](https://dotimplement.github.io/HealthChain/reference/gateway/api/) and FastAPI integration
-- [x] ๐งช Generate [synthetic healthcare data](https://dotimplement.github.io/HealthChain/reference/utilities/data_generator/) and [sandbox testing](https://dotimplement.github.io/HealthChain/reference/sandbox/sandbox/) utilities
-- [x] ๐ฅ๏ธ Bootstrap configurations with CLI tools
+
-## Why use HealthChain?
-- **EHR integrations are manual and time-consuming** - **HealthChainAPI** abstracts away complexities so you can focus on AI development, not learning FHIR APIs, CDS Hooks, and authentication schemes.
-- **Healthcare data is fragmented and complex** - **InteropEngine** handles the conversion between FHIR, CDA, and HL7v2 so you don't have to become an expert in healthcare data standards.
-- [**Most healthcare data is unstructured**](https://pmc.ncbi.nlm.nih.gov/articles/PMC10566734/) - HealthChain **Pipelines** are optimized for real-time AI and NLP applications that deal with realistic healthcare data.
-- **Built by health tech developers, for health tech developers** - HealthChain is tech stack agnostic, modular, and easily extensible with built-in compliance and audit features.
+HealthChain is an open-source developer framework to build healthcare AI applications with native protocol understanding. Skip months of custom integration with **built-in FHIR support**, **real-time EHR connectivity**, and **production-ready deployment** - all in Python.
-## HealthChainAPI
+
-The HealthChainAPI provides a secure integration layer that coordinates multiple healthcare systems in a single application.
+## Installation
-### Multi-Protocol Support
+```bash
+pip install healthchain
+```
-Connect to multiple healthcare data sources and protocols:
+## Core Features
+
+HealthChain is the **quickest way for AI/ML engineers to integrate their models with real healthcare systems**.
+
+
+### ๐ก For HealthTech Engineers
+
+
+
+
+ 
+
+ |
+
+ 
+
+ |
+
+
+
+
+
+### ๐ค For LLM / GenAI Developers
+
+
+
+
+ 
+
+ |
+
+ 
+
+ |
+
+
+
+### ๐ For ML Researchers
+
+
+
+
+
+
+ 
+ |
+
+
+
+## Why HealthChain?
+
+**Electronic health record (EHR) data is specific, complex, and fragmented.** Most healthcare AI projects require months of manual integration and custom validation on top of model development. This leads to fragile pipelines that break easily and consume valuable developer time.
+
+HealthChain understands healthcare protocols and data formats natively, so you don't have to build that knowledge from scratch. Skip months of custom integration work and productionize your healthcare AI faster.
+
+- **Optimized for real-time** - Connect to live FHIR APIs and integration points instead of stale data exports
+- **Automatic validation** - Type-safe FHIR models prevent broken healthcare data
+- **Built-in NLP support** - Extract structured data from clinical notes, output as FHIR
+- **Developer experience** - Modular and extensible architecture works across any EHR system
+
+## Usage Examples
+
+### Building a Pipeline [[Docs](https://dotimplement.github.io/HealthChain/reference/pipeline/pipeline)]
```python
-from healthchain.gateway import (
- HealthChainAPI, FHIRGateway,
- CDSHooksService, NoteReaderService
-)
-
-# Create your healthcare application
-app = HealthChainAPI(
- title="My Healthcare AI App",
- description="AI-powered patient care platform"
-)
-
-# FHIR for patient data from multiple EHRs
-fhir = FHIRGateway()
-fhir.add_source("epic", "fhir://fhir.epic.com/r4?client_id=...")
-fhir.add_source("medplum", "fhir://api.medplum.com/fhir/R4/?client_id=...")
-
-# CDS Hooks for real-time clinical decision support
-cds = CDSHooksService()
-
-@cds.hook("patient-view", id="allergy-alerts")
-def check_allergies(request):
- # Your AI logic here
- return {"cards": [...]}
-
-# SOAP for clinical document processing
-notes = NoteReaderService()
-
-@notes.method("ProcessDocument")
-def process_note(request):
- # Your NLP pipeline here
- return processed_document
+from healthchain.pipeline import Pipeline
+from healthchain.pipeline.components.integrations import SpacyNLP
+from healthchain.io import Document
-# Register everything
-app.register_gateway(fhir)
-app.register_service(cds)
-app.register_service(notes)
+# Create medical NLP pipeline
+nlp_pipeline = Pipeline[Document]()
+nlp_pipeline.add_node(SpacyNLP.from_model_id("en_core_web_sm"))
-# Your API now handles:
-# /fhir/* - Patient data, observations, etc.
-# /cds/* - Real-time clinical alerts
-# /soap/* - Clinical document processing
+nlp = nlp_pipeline.build()
+doc = Document("Patient presents with hypertension and diabetes.")
+result = nlp(doc)
-# Deploy with uvicorn
-if __name__ == "__main__":
- import uvicorn
- uvicorn.run(app, port=8888)
+spacy_doc = result.nlp.get_spacy_doc()
+print(f"Entities: {[(ent.text, ent.label_) for ent in spacy_doc.ents]}")
+print(f"FHIR conditions: {result.fhir.problem_list}") # Auto-converted to FHIR Bundle
```
-### FHIR Operations with AI Enhancement
+### Creating a Gateway [[Docs](https://dotimplement.github.io/HealthChain/reference/gateway/gateway)]
```python
-from healthchain.gateway import FHIRGateway
+from healthchain.gateway import HealthChainAPI, FHIRGateway
from fhir.resources.patient import Patient
-gateway = FHIRGateway()
-gateway.add_source("epic", "fhir://fhir.epic.com/r4?...")
+# Create healthcare application
+app = HealthChainAPI(title="Multi-EHR Patient Data")
-# Add AI transformations to FHIR data
-@gateway.transform(Patient)
-def enhance_patient(id: str, source: str = None) -> Patient:
- patient = gateway.read(Patient, id, source)
+# Connect to multiple FHIR sources
+fhir = FHIRGateway()
+fhir.add_source("epic", "fhir://fhir.epic.com/r4?client_id=epic_client_id")
+fhir.add_source("cerner", "fhir://fhir.cerner.com/r4?client_id=cerner_client_id")
- # Get lab results and process with AI
- lab_results = gateway.search(
- Observation,
- {"patient": id, "category": "laboratory"},
- source
- )
- insights = nlp_pipeline.process(patient, lab_results)
+@fhir.aggregate(Patient)
+def enrich_patient_data(id: str, source: str = None) -> Patient:
+ """Get patient data from any connected EHR and add AI enhancements"""
+ patient = fhir.read(Patient, id, source)
- # Add AI summary to patient record
+ # Add AI processing metadata
patient.extension = patient.extension or []
patient.extension.append({
- "url": "http://healthchain.org/fhir/summary",
- "valueString": insights.summary
+ "url": "http://healthchain.org/fhir/ai-processed",
+ "valueString": f"Enhanced by HealthChain from {source}"
})
- # Update the patient record
- gateway.update(patient, source)
return patient
-# Automatically available at: GET /fhir/transform/Patient/123?source=epic
-```
-
-## Pipeline
-Pipelines provide a flexible way to build and manage processing pipelines for NLP and ML tasks that can easily integrate with complex healthcare systems.
-
-### Building a pipeline
-
-```python
-from healthchain.io.containers import Document
-from healthchain.pipeline import Pipeline
-from healthchain.pipeline.components import (
- TextPreProcessor,
- SpacyNLP,
- TextPostProcessor,
-)
-
-# Initialize the pipeline
-nlp_pipeline = Pipeline[Document]()
-
-# Add TextPreProcessor component
-preprocessor = TextPreProcessor()
-nlp_pipeline.add_node(preprocessor)
-
-# Add Model component (assuming we have a pre-trained model)
-spacy_nlp = SpacyNLP.from_model_id("en_core_sci_sm")
-nlp_pipeline.add_node(spacy_nlp)
-
-# Add TextPostProcessor component
-postprocessor = TextPostProcessor(
- postcoordination_lookup={
- "heart attack": "myocardial infarction",
- "high blood pressure": "hypertension",
- }
-)
-nlp_pipeline.add_node(postprocessor)
-
-# Build the pipeline
-nlp = nlp_pipeline.build()
-
-# Use the pipeline
-result = nlp(Document("Patient has a history of heart attack and high blood pressure."))
-
-print(f"Entities: {result.nlp.get_entities()}")
-```
-
-#### Working with healthcare data formats
-Adapters handle conversion between healthcare formats (CDA, FHIR) and internal Document objects for seamless EHR integration.
-
-```python
-from healthchain.io import CdaAdapter, Document
-from healthchain.models import CdaRequest
-
-adapter = CdaAdapter()
-
-# Parse healthcare data into Document
-cda_request = CdaRequest(document="")
-doc = adapter.parse(cda_request)
-
-# Process with your pipeline
-processed_doc = nlp_pipeline(doc)
-
-# Access extracted clinical data
-print(f"Problems: {processed_doc.fhir.problem_list}")
-print(f"Medications: {processed_doc.fhir.medication_list}")
-
-# Convert back to healthcare format
-response = adapter.format(processed_doc)
-```
-
-### Using pre-built pipelines
-Pre-built pipelines are use case specific end-to-end workflows optimized for common healthcare AI tasks.
-
-```python
-from healthchain.pipeline import MedicalCodingPipeline
-from healthchain.models import CdaRequest
-
-# Load from model ID
-pipeline = MedicalCodingPipeline.from_model_id(
- model="blaze999/Medical-NER", task="token-classification", source="huggingface"
-)
-
-# Simple end-to-end processing
-cda_request = CdaRequest(document="")
-response = pipeline.process_request(cda_request)
-
-# Or manual control for document access
-from healthchain.io import CdaAdapter
-adapter = CdaAdapter()
-doc = adapter.parse(cda_request)
-doc = pipeline(doc)
-# Access: doc.fhir.problem_list, doc.fhir.medication_list
-response = adapter.format(doc)
-```
-
-## Interoperability
-
-The InteropEngine is a template-based system that allows you to convert between FHIR, CDA, and HL7v2.
-
-```python
-from healthchain.interop import create_interop, FormatType
-
-engine = create_interop()
-
-with open("tests/data/test_cda.xml", "r") as f:
- cda_data = f.read()
-
-# Convert CDA to FHIR
-fhir_resources = engine.to_fhir(cda_data, src_format=FormatType.CDA)
-
-# Convert FHIR to CDA
-cda_data = engine.from_fhir(fhir_resources, dest_format=FormatType.CDA)
-```
-
-## Sandbox
-
-Test your AI applications in realistic healthcare contexts with [CDS Hooks](https://cds-hooks.org/) sandbox environments.
-
-```python
-import healthchain as hc
-from healthchain.sandbox.use_cases import ClinicalDecisionSupport
-
-@hc.sandbox
-class MyCDS(ClinicalDecisionSupport):
- def __init__(self):
- self.pipeline = SummarizationPipeline.from_model_id("facebook/bart-large-cnn")
-
- @hc.ehr(workflow="encounter-discharge")
- def ehr_database_client(self):
- return self.data_generator.generate_prefetch()
+app.register_gateway(fhir)
-cds = MyCDS()
-cds.start_sandbox()
+# Available at: GET /fhir/transform/Patient/123?source=epic
+# Available at: GET /fhir/transform/Patient/123?source=cerner
-# Run with: healthchain run mycds.py
+if __name__ == "__main__":
+ import uvicorn
+ uvicorn.run(app, port=8000)
```
## Road Map
-- [ ] ๐ Configurations, data provenance, and audit trails in FHIR
-- [ ] ๐ HL7v2 parsing and FHIR profile conversion support
-- [ ] ๐ HIPAA compliance validation and PHI detection
+- [ ] ๐ Data provenance and audit trails tracking
+- [ ] ๐ HIPAA compliance and security
+- [ ] ๐ HL7v2 parsing, FHIR profile conversion and OMOP mapping support
+- [ ] ๐ Enhanced deployment support with observability and telemetry (Docker, Kubernetes, etc.)
- [ ] ๐ Model performance monitoring with MLFlow integration
-- [ ] ๐ Deployment as a sidecar service with telemetry and improved CLI
-- [ ] ๐ง Multi-modal pipelines
+- [ ] ๐ค MCP server integration
## Contribute
@@ -282,3 +209,22 @@ We are always eager to hear feedback and suggestions, especially if you are a de
## Acknowledgements ๐ค
This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.resources) and [CDS Hooks](https://cds-hooks.org/) standards developed by [HL7](https://www.hl7.org/) and [Boston Children's Hospital](https://www.childrenshospital.org/).
+
+
+
+[pypi-version-badge]: https://img.shields.io/pypi/v/healthchain?logo=python&logoColor=white&style=flat-square&color=%23e59875
+[downloads-badge]: https://img.shields.io/pepy/dt/healthchain?style=flat-square&color=%2379a8a9
+[stars-badge]: https://img.shields.io/github/stars/dotimplement/HealthChain?style=flat-square&logo=github&color=BD932F&logoColor=white
+[license-badge]: https://img.shields.io/github/license/dotimplement/HealthChain?style=flat-square&color=%23e59875
+[python-versions-badge]: https://img.shields.io/pypi/pyversions/healthchain?style=flat-square&color=%23eeeeee
+[build-badge]: https://img.shields.io/github/actions/workflow/status/dotimplement/healthchain/ci.yml?branch=main&style=flat-square&color=%2379a8a9
+[discord-badge]: https://img.shields.io/badge/chat-%235965f2?style=flat-square&logo=discord&logoColor=white
+[substack-badge]: https://img.shields.io/badge/Cool_Things_In_HealthTech-%23c094ff?style=flat-square&logo=substack&logoColor=white
+
+[pypi]: https://pypi.org/project/healthchain/
+[pypistats]: https://pepy.tech/project/healthchain
+[stars]: https://github.com/dotimplement/HealthChain/stargazers
+[license]: https://github.com/dotimplement/HealthChain/blob/main/LICENSE
+[build]: https://github.com/dotimplement/HealthChain/actions?query=branch%3Amain
+[discord]: https://discord.gg/UQC6uAepUz
+[substack]: https://jenniferjiangkells.substack.com/
diff --git a/docs/assets/images/hc-use-cases-clinical-integration.png b/docs/assets/images/hc-use-cases-clinical-integration.png
new file mode 100644
index 00000000..e1e3e76d
Binary files /dev/null and b/docs/assets/images/hc-use-cases-clinical-integration.png differ
diff --git a/docs/assets/images/hc-use-cases-genai-aggregate.png b/docs/assets/images/hc-use-cases-genai-aggregate.png
new file mode 100644
index 00000000..80aca6e7
Binary files /dev/null and b/docs/assets/images/hc-use-cases-genai-aggregate.png differ
diff --git a/docs/assets/images/hc-use-cases-ml-deployment.png b/docs/assets/images/hc-use-cases-ml-deployment.png
new file mode 100644
index 00000000..692c5156
Binary files /dev/null and b/docs/assets/images/hc-use-cases-ml-deployment.png differ
diff --git a/docs/assets/images/interopengine.png b/docs/assets/images/interopengine.png
new file mode 100644
index 00000000..2f3d7706
Binary files /dev/null and b/docs/assets/images/interopengine.png differ
diff --git a/docs/assets/images/openapi_docs.png b/docs/assets/images/openapi_docs.png
index 76afa7cd..59c1868f 100644
Binary files a/docs/assets/images/openapi_docs.png and b/docs/assets/images/openapi_docs.png differ
diff --git a/docs/cookbook/ml_model_deployment.md b/docs/cookbook/ml_model_deployment.md
new file mode 100644
index 00000000..74fa87c1
--- /dev/null
+++ b/docs/cookbook/ml_model_deployment.md
@@ -0,0 +1,64 @@
+# Deploy ML Models as Healthcare APIs
+
+*This example is coming soon! ๐ง*
+
+
+
+
+
+
-
-- :material-tools:{ .lg .middle } __Build a pipeline__
+- :material-tools:{ .lg .middle } __FHIR-native ML Pipelines__
---
- Create custom pipelines or use pre-built ones for your healthcare NLP and ML tasks
+ Create custom pipelines or use pre-built ones for healthcare NLP and ML tasks with automatic FHIR output
[:octicons-arrow-right-24: Pipeline](reference/pipeline/pipeline.md)
-- :material-connection:{ .lg .middle } __Connect to multiple data sources__
+- :material-connection:{ .lg .middle } __Multi-EHR Gateway__
---
- Connect to multiple healthcare data sources and protocols with **HealthChainAPI**.
+ Connect to multiple healthcare systems with unified API supporting FHIR, CDS Hooks, and SOAP/CDA protocols
[:octicons-arrow-right-24: Gateway](reference/gateway/gateway.md)
-- :material-database:{ .lg .middle } __Interoperability__
+- :material-database:{ .lg .middle } __Healthcare Data Conversion__
---
- Configuration-driven **InteropEngine** to convert between FHIR, CDA, and HL7v2
+ Convert between FHIR, CDA, and HL7v2 formats using configuration-driven InteropEngine
[:octicons-arrow-right-24: Interoperability](reference/interop/interop.md)
-- :material-fire:{ .lg .middle } __Utilities__
+- :material-fire:{ .lg .middle } __Developer Utilities__
---
- FHIR data model utilities and helpers to make development easier
+ Type-safe FHIR resources, validation helpers, and sandbox environments for rapid development
[:octicons-arrow-right-24: Utilities](reference/utilities/fhir_helpers.md)
+
+## Getting Started with Healthcare AI
-
+HealthChain provides the missing middleware layer between healthcare systems and modern AI/ML development. Whether you're building clinical decision support tools, processing medical documents, or creating multi-system integrations, these docs will guide you through:
+
+- **๐ง Core concepts** - Understand FHIR resources, pipelines, and gateway patterns
+- **๐ Real examples** - Step-by-step tutorials for common healthcare AI use cases
+- **๐๏ธ Advanced patterns** - Production deployment, authentication, and multi-EHR workflows
+- **๐งช Testing tools** - Sandbox environments and utilities for development
+
+## What You Can Build with HealthChain
-## Why HealthChain?
+| | Use Case | Description |
+|---|---------------------------------------|-----------------------------------------------------------------------------|
+| ๐จ | **CDS alerts for discharge summaries** | Generate clinical recommendations directly in Epic workflows |
+| ๐ | **Automatic medical coding** | Extract ICD-10 or SNOMED-CT codes from physician notes with confidence scores|
+| ๐ | **Multi-EHR patient aggregation** | Combine patient records from Epic, Cerner, and specialty systems |
+| ๐ค | **ML model deployment** | Serve your trained healthcare models as FHIR-compliant APIs |
+| ๐ | **Legacy document conversion** | Transform CDA documents to modern FHIR resources |
-Healthcare AI development has a **missing middleware layer**. Traditional enterprise integration engines move data around, EHR platforms serve end users, but there's nothing in between for developers building AI applications that need to talk to multiple healthcare systems. Few solutions are open-source, and even fewer are built in modern Python where most ML/AI libraries thrive.
+**New to healthcare AI?** Start with our [Quickstart Guide](quickstart.md) to build your first medical NLP pipeline in under 10 minutes.
-HealthChain fills that gap with:
+**Ready to integrate with EHRs?** Jump to our [Cookbook](cookbook/index.md) for complete examples including CDS Hooks and FHIR integration.
-- **๐ฅ FHIR-native ML pipelines** - Pre-built NLP/ML pipelines optimized for structured / unstructured healthcare data, or build your own with familiar Python libraries such as ๐ค Hugging Face, ๐ค LangChain, and ๐ spaCy
-- **๐ Type-safe healthcare data** - Full type hints and Pydantic validation for FHIR resources with automatic data validation and error handling
-- **๐ Multi-protocol connectivity** - Handle FHIR, CDS Hooks, and SOAP/CDA in the same codebase with OAuth2 authentication and connection pooling
-- **โก Event-driven architecture** - Real-time event handling with audit trails and workflow automation built-in
-- **๐ Built-in interoperability** - Convert between FHIR, CDA, and HL7v2 using a template-based engine
-- **๐ Production-ready deployment** - FastAPI integration for scalable, real-time applications
+---
HealthChain is made by a small team with experience in software engineering, machine learning, and healthcare NLP. We understand that good data science is about more than just building models, and that good engineering is about more than just building systems. This rings especially true in healthcare, where people, processes, and technology all play a role in making an impact.
diff --git a/pyproject.toml b/pyproject.toml
index ce33499b..6f417439 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,12 +1,12 @@
[tool.poetry]
name = "healthchain"
version = "0.0.0"
-description = "Python toolkit that makes it easier to connect your AI/ML pipelines to healthcare systems"
+description = "Open source framework for productionizing healthcare AI"
authors = ["Jennifer Jiang-Kells ", "Adam Kells "]
license = "Apache-2.0"
readme = "README.md"
documentation = "https://dotimplement.github.io/HealthChain/"
-keywords = ["nlp", "ai", "llm", "healthcare", "ehr", "mlops"]
+keywords = ["nlp", "ai", "llm", "healthcare", "ehr", "mlops", "fhir"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",