Python API reference

Run lifecycle

Python API for creating, processing, revising, and exporting runs.

exception health_deid.api.PrecheckError

__init__(result)

Parameters:

result (PrecheckResult)

Return type:

None

class health_deid.api.PrecheckResult

Complete non-mutating precheck result.

__init__(issues, record_count=None, cost_estimate=None)

Parameters:

• issues (tuple[PrecheckIssue, ...])

• record_count (int | None)

• cost_estimate (CostEstimate | None)

Return type:

None

class health_deid.api.RunHandle

One durable local de-identification run.

__init__(engine, *, _dependencies=None)

Parameters:

• engine (PipelineEngine)

• _dependencies (_ApiDependencies | None)

Return type:

None

execute()

Process every pending stage.

Return type:

RunHandle

revise(config, *, reason, execute=True, rerun_detection=False, created_at=None)

Create a revised run; reuse matching detector results and rerun everything else.

Parameters:

• config (PipelineConfig | Mapping[str, Any] | str | Path)

• reason (str)

• execute (bool)

• rerun_detection (bool)

• created_at (datetime | None)

Return type:

RunHandle

health_deid.api.create_run(config, *, timestamp=None, check_precheck=True, _dependencies=None)

Create and import a run without starting paid processing.

Parameters:

• config (PipelineConfig | Mapping[str, Any] | str | Path)

• timestamp (datetime | None)

• check_precheck (bool)

• _dependencies (_ApiDependencies | EngineDependencies | None)

Return type:

RunHandle

health_deid.api.precheck(config, *, _dependencies=None)

Validate setup and estimate pre-run AWS cost.

Parameters:

• config (PipelineConfig | Mapping[str, Any] | str | Path)

• _dependencies (_ApiDependencies | EngineDependencies | None)

Return type:

PrecheckResult

health_deid.api.run(config, *, timestamp=None, _dependencies=None)

Create and execute a run.

Parameters:

• config (PipelineConfig | Mapping[str, Any] | str | Path)

• timestamp (datetime | None)

• _dependencies (_ApiDependencies | EngineDependencies | None)

Return type:

RunHandle

Configuration

Validated, versioned configuration models shared by the API, CLI, and UI.

class health_deid.models.config.RunConfig

Naming, output location, and optional parent lineage for one run.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.InputConfig

Input file format, identity columns, clinical text, and structured PHI mappings.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.ExecutionConfig

The only execution setting that materially affects a local research run.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.AwsComprehendDetectorConfig

AWS Comprehend Medical detector settings and reporting price estimate.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.BedrockLlmDetectorConfig

Amazon Bedrock detector settings for the supported Sonnet model.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.DetectionConfig

Enabled PHI detector backends and their shared request controls.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.RulesConfig

Optional deterministic rules supplied by path or embedded snapshot.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.ValidationConfig

Automated residual-PHI validation settings and adaptive token tiers.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.ReviewConfig

Human-review enablement and queue scope.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.config.PipelineConfig

Complete versioned configuration for one de-identification run.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

health_deid.models.config.load_config(config_path)

Load and validate a versioned pipeline configuration from YAML.

Parameters:

config_path (str | Path)

Return type:

PipelineConfig

Replacement policy

class health_deid.models.policy.ConsistencyScope

__new__(value)

class health_deid.models.policy.FakerSurrogate

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.policy.CustomListSurrogate

Select deterministic replacements from a user-provided list.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.policy.DateShiftSurrogate

Shift every date for one entity by the same whole-week offset.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.policy.CategoryPolicy

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class health_deid.models.policy.TransformationPolicy

Transformation selected for every supported PHI category.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Backend interfaces

Minimal extension contracts for paid detector and validator backends.

class health_deid.backends.contracts.PhiDetector

One-call detector adapter; orchestration owns persistence.

class health_deid.backends.contracts.PhiValidator

One automated audit of a de-identified record.