Usage

Install

Health-DeID supports Python 3.12 through 3.14.

pip install health-deid

The package includes Flask and botocore CRT support. AWS backends use the normal boto3 credential and region chain; the UI never asks for credentials.

UI

Launch the primary interface with one fixed runs directory:

health-deid ui --reviewer "Reviewer Name" --runs-dir runs

The server accepts loopback hosts only and is intended for one person on a laptop or desktop. Supply a run directory or run.sqlite path as the optional positional argument to open that run immediately.

CLI

health-deid check config.yaml
health-deid run config.yaml
health-deid status runs/RUN_ID
health-deid resume runs/RUN_ID
health-deid retry runs/RUN_ID --stage validation --failed

Create a revised run while leaving the parent unchanged:

health-deid revise runs/RUN_ID revised.yaml \
  --reason "change replacement policy"

Add --rerun-detection only when authorizing a new paid detector pass.

Python API

from health_deid import create_run, open_run

run = create_run("config.yaml").execute()
print(run.status())

reopened = open_run(run.run_dir).resume()
revised = reopened.revise(
    "revised.yaml",
    reason="change replacement policy",
)

Export

ready_only exports records with current final output. all_records keeps the imported records and adds operational status fields.

health-deid export runs/RUN_ID final.parquet \
  --mode ready_only \
  --column record_id \
  --column final_text

Select source text, identifiers, or original structured PHI only when they are required. The run database always contains source clinical data and must remain protected as PHI.