Metadata-Version: 2.4
Name: kestrel-feature-healthcare
Version: 0.7.0
Summary: Patient-owned sovereign health records (FHIR/CCDA) as a Kestrel Sovereign feature package
Project-URL: Homepage, https://kestrelsovereign.com
Project-URL: Source, https://github.com/KestrelSovereignAI/kestrel-feature-healthcare
Project-URL: Issues, https://github.com/KestrelSovereignAI/kestrel-feature-healthcare/issues
Author: UncleSaurus
Maintainer: UncleSaurus
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,ccda,fhir,healthcare,kestrel,sovereign-records
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: <3.15,>=3.11
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: cryptography>=43
Requires-Dist: fhir-resources<9,>=8.0.0
Requires-Dist: kestrel-sovereign-sdk<1,>=0.14.1
Requires-Dist: kestrel-sovereign<1,>=0.14.1
Requires-Dist: lxml>=5
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
uv pip install kestrel-feature-healthcare
```

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

## Development

```bash
uv sync --extra test
uv run --extra test pytest
```
