# Extracting Pii Entities

Detect PHI/PII spans in clinical text with OpenMed's extract_pii without altering the...

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill extracting-pii-entities -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill extracting-pii-entities -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill extracting-pii-entities -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill extracting-pii-entities -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Detect PHI/PII spans in clinical text with OpenMed's extract_pii without altering the text. Use when the user wants to find names, dates, MRNs, phone numbers, addresses, SSNs, or other identifiers and get their offsets and labels (not redact them), inspect what would be removed before de-identifying, route spans to a custom redactor, normalize labels to a canonical taxonomy, or filter by confidence and language. Covers extract_pii, the PIIEntity fields, CANONICAL_LABELS / normalize_label, and how it differs from deidentify. Pairs before reidentifying-text and deidentifying-clinical-text.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

```bash
pip install "openmed[hf]"
```

## Quick start

```python
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):

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/extracting-pii-entities/SKILL.md