Interop engine

README.md

@@ -26,6 +26,7 @@ Came here from NHS RPySOC 2024 ✨?
 ## Features
 - [x] 🔥 Build FHIR-native pipelines or use [pre-built ones](https://dotimplement.github.io/HealthChain/reference/pipeline/pipeline/#prebuilt) for your healthcare NLP and ML tasks
 - [x] 🔌 Connect pipelines to any EHR system with built-in [CDA and FHIR Connectors](https://dotimplement.github.io/HealthChain/reference/pipeline/connectors/connectors/)
+- [x] 🔄 Convert between FHIR, CDA, and HL7v2 with the [InteropEngine](https://dotimplement.github.io/HealthChain/reference/interop/interop/)
 - [x] 🧪 Test your pipelines in full healthcare-context aware [sandbox](https://dotimplement.github.io/HealthChain/reference/sandbox/sandbox/) environments
 - [x] 🗃️ Generate [synthetic healthcare data](https://dotimplement.github.io/HealthChain/reference/utilities/data_generator/) for testing and development
 - [x] 🚀 Deploy sandbox servers locally with [FastAPI](https://fastapi.tiangolo.com/)
@@ -117,6 +118,24 @@ cda_data = CdaRequest(document="<CDA XML content>")
 output = pipeline(cda_data)
 ```
 
+## Interoperability
+
+The InteropEngine is a template-based system that allows you to convert between FHIR, CDA, and HL7v2.
+
+```python
+from healthchain.interop import create_engine, FormatType
+
+engine = create_engine()
+
+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
 
@@ -219,7 +238,7 @@ healthchain run mycds.py
 By default, the server runs at `http://127.0.0.1:8000`, and you can interact with the exposed endpoints at `/docs`.
 
 ## Road Map
-- [ ] 🔄 Transform and validate healthcare HL7v2, CDA to FHIR with template-based interop engine
+- [x] 🔄 Transform and validate healthcare HL7v2, CDA to FHIR with template-based interop engine
 - [ ] 🏥 Runtime connection health and EHR integration management - connect to FHIR APIs and legacy systems
 - [ ] 📊 Track configurations, data provenance, and monitor model performance with MLFlow integration
 - [ ] 🚀 Compliance monitoring, auditing at deployment as a sidecar service

configs/defaults.yaml

@@ -0,0 +1,59 @@
+# HealthChain Interoperability Engine Default Configuration
+# This file contains default values used throughout the engine
+
+defaults:
+  # Common defaults for all resources
+  common:
+    id_prefix: "hc-"
+    timestamp: "%Y%m%d"
+    reference_name: "#{uuid}name"
+    subject:
+      reference: "Patient/example"
+
+  # Mapping directory configuration
+  mappings_dir: "cda_default"
+
+  # Resource-specific defaults
+  resources:
+    Condition:
+      clinicalStatus:
+        coding:
+          - system: "http://terminology.hl7.org/CodeSystem/condition-clinical"
+            code: "unknown"
+            display: "Unknown"
+    MedicationStatement:
+      status: "unknown"
+      medication:
+        concept:
+          coding:
+            - system: "http://terminology.hl7.org/CodeSystem/v3-NullFlavor"
+              code: "UNK"
+              display: "Unknown"
+
+# TODO: More control over settings
+# # Validation settings
+# validation:
+#   strict_mode: true
+#   warn_on_missing: true
+#   ignore_unknown_fields: true
+
+# # Parser settings
+# parser:
+#   max_entries: 1000
+#   skip_empty_sections: true
+
+# # Logging settings
+# logging:
+#   level: "INFO"
+#   include_timestamps: true
+
+# # Error handling
+# errors:
+#   retry_count: 3
+#   fail_on_critical: true
+
+# # Performance settings
+# performance:
+#   cache_templates: true
+#   cache_mappings: true
+#   batch_size: 100

configs/environments/development.yaml

@@ -0,0 +1,33 @@
+# Development Environment Configuration
+# This file contains settings specific to the development environment
+# TODO: Implement
+
+# Logging settings for development
+logging:
+  level: "DEBUG"
+  include_timestamps: true
+  console_output: true
+  file_output: false
+
+# Error handling for development
+errors:
+  retry_count: 1
+  fail_on_critical: true
+  verbose_errors: true
+
+# Performance settings for development
+performance:
+  cache_templates: false  # Disable caching for easier template development
+  cache_mappings: false   # Disable caching for easier mapping development
+  batch_size: 10          # Smaller batch size for easier debugging
+
+# Default resource fields for development
+defaults:
+  common:
+    id_prefix: "dev-"     # Development-specific ID prefix
+    subject:
+      reference: "Patient/Foo"
+
+# Template settings for development
+templates:
+  reload_on_change: true  # Automatically reload templates when they change

configs/environments/production.yaml

@@ -0,0 +1,37 @@
+# Production Environment Configuration
+# This file contains settings specific to the production environment
+# TODO: Implement
+
+# Logging settings for production
+logging:
+  level: "WARNING"
+  include_timestamps: true
+  console_output: false
+  file_output: true
+  file_path: "/var/log/healthchain/interop.log"
+  rotate_logs: true
+  max_log_size_mb: 10
+  backup_count: 5
+
+# Error handling for production
+errors:
+  retry_count: 3
+  fail_on_critical: true
+  verbose_errors: false
+
+# Performance settings for production
+performance:
+  cache_templates: true   # Enable caching for better performance
+  cache_mappings: true    # Enable caching for better performance
+  batch_size: 100         # Larger batch size for better throughput
+
+# Default resource fields for production
+defaults:
+  common:
+    id_prefix: "hc-"      # Production ID prefix
+    subject:
+      reference: "Patient/example"
+
+# Template settings for production
+templates:
+  reload_on_change: false  # Don't reload templates in production

configs/environments/testing.yaml

@@ -0,0 +1,39 @@
+# Testing Environment Configuration
+# This file contains settings specific to the testing environment
+# TODO: Implement
+# Logging settings for testing
+logging:
+  level: "INFO"
+  include_timestamps: true
+  console_output: true
+  file_output: true
+  file_path: "./logs/test-interop.log"
+
+# Error handling for testing
+errors:
+  retry_count: 2
+  fail_on_critical: true
+  verbose_errors: true
+
+# Performance settings for testing
+performance:
+  cache_templates: true   # Enable caching for realistic testing
+  cache_mappings: true    # Enable caching for realistic testing
+  batch_size: 50          # Medium batch size for testing
+
+# Default resource fields for testing
+defaults:
+  common:
+    id_prefix: "test-"    # Testing-specific ID prefix
+    subject:
+      reference: "Patient/test-example"
+
+# Template settings for testing
+templates:
+  reload_on_change: false  # Don't reload templates in testing
+
+# Validation settings for testing
+validation:
+  strict_mode: true
+  warn_on_missing: true
+  ignore_unknown_fields: false  # Stricter validation for testing

configs/interop/cda/document/ccd.yaml

@@ -0,0 +1,55 @@
+# CCD Document Configuration
+# This file contains configuration for CCD documents
+
+# Document templates (required)
+templates:
+  document: "fhir_cda/document"
+  section: "fhir_cda/section"
+
+# Basic document information
+code:
+  code: "34133-9"
+  code_system: "2.16.840.1.113883.6.1"
+  code_system_name: "LOINC"
+  display: "Summarization of Episode Note"
+confidentiality_code:
+  code: "N"
+  code_system: "2.16.840.1.113883.5.25"
+language_code: "en-US"
+realm_code: "GB"
+type_id:
+  extension: "POCD_HD000040"
+  root: "2.16.840.1.113883.1.3"
+template_id:
+  root: "1.2.840.114350.1.72.1.51693"
+
+# Document structure
+structure:
+  # Header configuration
+  header:
+    include_patient: false
+    include_author: false
+    include_custodian: false
+    include_legal_authenticator: false
+
+  # Body configuration
+  body:
+    structured_body: true
+    non_xml_body: false
+    include_sections:
+      - "allergies"
+      - "medications"
+      - "problems"
+      - "notes"
+
+# Rendering configuration
+rendering:
+  # XML formatting
+  xml:
+    pretty_print: true
+    encoding: "UTF-8"
+
+  # Narrative generation
+  narrative:
+    include: true
+    generate_if_missing: true

configs/interop/cda/sections/allergies.yaml

@@ -0,0 +1,88 @@
+# Allergies Section Configuration
+# ========================
+
+# Metadata for both extraction and rendering processes
+resource: "AllergyIntolerance"
+resource_template: "cda_fhir/allergy_intolerance"
+entry_template: "fhir_cda/allergy_entry"
+
+# Section identifiers (used for extraction)
+identifiers:
+  template_id: "2.16.840.1.113883.10.20.1.2"
+  code: "48765-2"
+  code_system: "2.16.840.1.113883.6.1"
+  code_system_name: "LOINC"
+  display: "Allergies"
+  reaction:
+    template_id: "1.3.6.1.4.1.19376.1.5.3.1.4.5"
+  severity:
+    template_id: "1.3.6.1.4.1.19376.1.5.3.1.4.1"
+
+# Template configuration (used for rendering/generation)
+template:
+  # Act element configuration
+  act:
+    template_id:
+      - "1.3.6.1.4.1.19376.1.5.3.1.4.5.1"
+      - "1.3.6.1.4.1.19376.1.5.3.1.4.5.3"
+      - "2.16.840.1.113883.3.88.11.32.6"
+      - "2.16.840.1.113883.3.88.11.83.6"
+    status_code: "active"
+
+  # Allergy observation configuration
+  allergy_obs:
+    type_code: "SUBJ"
+    inversion_ind: false
+    template_id:
+      - "1.3.6.1.4.1.19376.1.5.3.1.4.5"
+      - "1.3.6.1.4.1.19376.1.5.3.1.4.6"
+      - "2.16.840.1.113883.10.20.1.18"
+      - "1.3.6.1.4.1.19376.1.5.3.1"
+      - "2.16.840.1.113883.10.20.1.28"
+    code: "420134006"
+    code_system: "2.16.840.1.113883.6.96"
+    code_system_name: "SNOMED CT"
+    display_name: "Propensity to adverse reactions"
+    status_code: "completed"
+
+  # Reaction observation configuration
+  reaction_obs:
+    template_id:
+      - "2.16.840.1.113883.10.20.1.54"
+      - "1.3.6.1.4.1.19376.1.5.3.1.4.5"
+    code: "RXNASSESS"
+    status_code: "completed"
+
+  # Severity observation configuration
+  severity_obs:
+    template_id:
+      - "2.16.840.1.113883.10.20.1.55"
+      - "1.3.6.1.4.1.19376.1.5.3.1.4.1"
+    code: "SEV"
+    code_system: "2.16.840.1.113883.5.4"
+    code_system_name: "ActCode"
+    display_name: "Severity"
+    status_code: "completed"
+    value:
+      code_system: "2.16.840.1.113883.5.1063"
+      code_system_name: "SeverityObservation"
+
+  # Clinical status observation configuration
+  clinical_status_obs:
+    template_id: "2.16.840.1.113883.10.20.1.39"
+    code: "33999-4"
+    code_system: "2.16.840.1.113883.6.1"
+    code_system_name: "LOINC"
+    display_name: "Status"
+    status_code: "completed"
+
+# Rendering configuration (not used)
+rendering:
+  narrative:
+    include: true
+    template: "narratives/allergy_narrative"
+  entry:
+    include_status: true
+    include_reaction: true
+    include_severity: true
+    include_dates: true