extracting-pii-entities

Extracting PII Entities

openmed.extract_pii finds PHI/PII spans and returns them without changing the text. Use it when you need to see the identifiers — to audit, route to a custom redactor, or decide a policy — rather than produce redacted output. It runs on-device.

When to use

• You want the spans and labels of identifiers, with the original text intact.
• You need a preview of what deidentify would act on before committing.
• You are feeding detected spans into a downstream redactor (your own, Presidio, or deidentify).
• You want to normalize model labels to a stable canonical taxonomy.

If you instead want redacted/masked output directly, use deidentifying-clinical-text (openmed.deidentify). If you need reversible masking, see reidentifying-text.

extract_pii vs deidentify

	extract_pii	deidentify
Changes the text?	No	Yes (mask/remove/replace/hash/shift)
Returns	PredictionResult (spans)	DeidentificationResult (redacted text)
Default threshold	0.5	0.7 (safety-biased)
Use for	detection, audit, routing	producing safe output

Install

pip install "openmed[hf]"

Quick start

import openmed

note = "Patient John Doe (MRN 00481726), DOB 1970-01-15, phone 617-555-0142."

result = openmed.extract_pii(note, confidence_threshold=0.5)

for ent in result.entities:
    print(f"{ent.label:10} {ent.text!r:18} {ent.confidence:.2f} [{ent.start}:{ent.end}]")

extract_pii(...) returns a PredictionResult. Its .entities are PIIEntity objects (synthetic example fields shown):

ent.text            # the identifier surface string, e.g. "617-555-0142"
ent.label           # detected label, e.g. "PHONE"
ent.confidence      # model score in [0, 1]   (NOTE: .confidence, not .score)
ent.start / ent.end # character offsets into the original note
ent.canonical_label # label mapped to OpenMed's canonical taxonomy (if set)
ent.entity_type     # same as label