fhircraft 0.8.0

Fhircraft transforms FHIR (Fast Healthcare Interoperability Resources) specifications into type-safe Python models using Pydantic. Build healthcare applications with automatic validation, intelligent code completion, and seamless integration with Python's ecosystem.

---

Pythonic healthcare interoperability
A comprehensive Python toolkit for working with FHIR healthcare data standards using Pydantic models from core and profiled FHIR specifications, all without external dependencies or complex server infrastructure.

Explore the Documentation »

Report Bug · Request Feature

---

[!WARNING]
This package is under active development. Major and/or breaking changes are to be expected in future updates.

Key Features

• Automatic validation of FHIR resources using Pydantic models generated directly from FHIR structure definitions. Catch schema violations and constraint failures without any dedicated servers.

• Work with FHIR data as standard Python objects. No XML parsing, no external FHIR servers required. Access and modify healthcare data using familiar Python syntax and patterns.

• Supports FHIR R4, R4B, and R5 out of the box. Load implementation guides and custom profiles directly from the FHIR package registry to work with specialized healthcare data models.

• Execute FHIRPath expressions directly on Python objects. Query complex nested healthcare data structures using the standard FHIR query language without additional tooling.

• Implement healthcare data transformations using the official FHIR Mapping Language. Convert between different data formats while maintaining semantic integrity and validation.

(back to top)

Quick Start

Prerequisites

• Python 3.10 or higher

Installation

Install Fhircraft using your package manager of choice. To download the latest release using the pip manager:

pip install fhircraft

or install the latest development version:

pip install git+https://github.com/luisfabib/fhircraft.git

To verify your installation:

from fhircraft.fhir.resources import get_fhir_type

# This should work without errors
Patient = get_fhir_type("Patient","R4B")
print("✓ Fhircraft installed successfully!")

(back to top)

Demo

Built-in FHIR Resources

Work with pre-generated Pydantic models for all standard FHIR resources. Each model includes full validation rules from the FHIR specification:

from fhircraft.fhir.resources import get_fhir_type

# Get built-in Patient model for FHIR R5
Patient = get_fhir_type("Patient", "R5")

# Create and validate a patient
patient = Patient(
    name=[{"given": ["Alice"], "family": "Johnson"}],
    gender="female",
    birthDate="1985-03-15"
)

print(f"Created patient: {patient.name[0].given[0]} {patient.name[0].family}")

FHIR Package Integration

Extend base FHIR models with implementation guide profiles loaded directly from the official FHIR package registry:

from fhircraft.fhir.resources import FHIRModelFactory

# Create a FHIR (R5 release) factory
factory = FHIRModelFactory(fhir_release="R4")

# Load US Core Implementation Guide
factory.register_package("hl7.fhir.us.core", "5.0.1")

# Create US Core Patient model with enhanced validation
USCorePatient = factory.build(
    canonical_url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
)

# Use with US Core constraints
patient = USCorePatient(
    identifier=[{"system": "http://example.org/mrn", "value": "12345"}],
    name=[{"family": "Doe", "given": ["John"]}],
    gender="male"
)

FHIRPath Querying

Execute FHIRPath expressions directly on FHIR resource instances to extract, filter, and validate healthcare data:

# Query patient data with FHIRPath
family_names = patient.fhirpath_values("Patient.name.family")
has_phone = patient.fhirpath_exists("Patient.telecom.where(system='phone')")

# Update data using FHIRPath expressions
patient.fhirpath_update_single("Patient.gender", "female")
patient.fhirpath_update_values("Patient.name.given", ["Jane", "Marie"])

print(f"Updated patient: {family_names[0]}, Phone: {has_phone}")

Data Transformation

Convert external data sources into valid FHIR resources using declarative mapping scripts:

from fhircraft.fhir.mapper import FHIRStructureMapper

# Legacy system data
legacy_patient = {
    "firstName": "Bob",
    "lastName": "Smith", 
    "dob": "1975-06-20",
    "sex": "M"
}

# FHIR Mapping script
mapping_script = """
/// url = "http://example.org/legacy-to-fhir"
/// name = "LegacyPatientToFHIR"

uses "http://hl7.org/fhir/StructureDefinition/Patient" as target

group main(source legacy, target patient: Patient) {
    legacy -> patient.name as name then {
        legacy.firstName -> name.given;
        legacy.lastName -> name.family;
    };
    legacy.dob -> patient.birthDate;
    legacy.sex where($this = 'F') -> patient.gender = "female";
    legacy.sex where($this = 'M') -> patient.gender = "male";
}
"""

# Execute transformation
mapper = FHIRStructureMapper(fhir_release="R5")
targets = mapper.map(mapping_script, legacy_patient)
fhir_patient = targets[0]

print(fhir_patient.model_dump(exclude={'meta','resourceType'}))
#> {'name': [{'family': 'Smith', 'given': ['Bob']}], 'birthDate': '1975-06-20'}

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. Checkout the Contributing Guide for more details. Thanks to all our contributors!

(back to top)

License

This project is distributed under the MIT License. See LICENSE for more information.

(back to top)