kestrel-feature-healthcare 0.3.0

Patient-owned sovereign health records (FHIR/CCDA) as a Kestrel Sovereign feature package

kestrel-feature-healthcare

Patient-owned sovereign health records (FHIR/CCDA) for Kestrel Sovereign.

An agent holds the owner's clinical records as part of its sovereign memory. This is a reusable framework capability — a sibling package alongside kestrel-feature-visual / -reflection / -observability — not a host-product feature. Any healthcare host on Kestrel consumes it.

Status

Multi-phase epic tracked in KestrelSovereignAI/kestrel-sovereign:

• Phase A — implemented — typed FHIR R4B resource store, owner-DID-scoped, PHI encrypted at rest, audited reads
• Phase B — implemented — CCDA document storage + header extraction (lxml), owner-DID-scoped, encrypted at rest, sharing one append-only PHI access log with Phase A
• Phase C — implemented — pure-Python CCDA → FHIR R4B mapper (no third-party converter): Patient + Allergies / Medications / Problems / Results / Vital Signs / Immunizations / Procedures. Normalized resources land in the Phase A FHIR store, owner-scoped and audited, exactly like any other write.
• Phase D — owner-controlled access/consent surface + export hooks

Phases C/D depend on the sovereign-import receiver and the data_access_grant consent-verification primitives shipping in kestrel-sovereign first.

Phase A — PHI handling (required)

Health records are PHI. The store is fail-closed: resource bodies are encrypted at rest with AES-256-GCM under a per-owner key HKDF-derived from the host master key, and no operation will store or return PHI in the clear. The host master key must be configured (KESTREL_DATA_KEY); without it the FHIR tools fail with a clear error rather than degrading to plaintext. Every owner read/write/query is recorded in an append-only access log. Only the resource body is encrypted — resource_type and fhir_id remain queryable metadata.

Installation

uv pip install kestrel-feature-healthcare

The package registers HealthcareFeature through the kestrel_sovereign.features entry point group.

Development

uv sync --extra test
uv run --extra test pytest