# Reidentifying Text

Reversibly de-identify clinical text with OpenMed and later restore the original PHI...

- 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 reidentifying-text -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill reidentifying-text -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill reidentifying-text -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill reidentifying-text -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Reversibly de-identify clinical text with OpenMed and later restore the original PHI from a saved mapping. Use when the user needs pseudonymization rather than permanent anonymization, wants to mask PHI now and re-link it later under authorization (e.g. recontact, adjudication, GDPR pseudonymization), asks about deidentify keep_mapping, reidentify, or how to store and protect the re-identification mapping. Covers when reversibility is and is not appropriate (pseudonymization vs HIPAA Safe Harbor anonymization). Pairs after extracting-pii-entities and deidentifying-clinical-text.

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

# Reidentifying Text

Some workflows need to remove PHI **for processing** but keep the ability to
restore it later under authorization, adjudication, patient recontact, linking
results back to a record. That is **pseudonymization** (reversible), not
**anonymization** (irreversible). OpenMed supports it with
`deidentify(..., keep_mapping=True)` to capture a mapping, and `reidentify` to
restore. Everything runs on-device.

## When to use

- You need to **re-link** redacted output to the original record later.
- You are doing **GDPR pseudonymization** (Art. 4(5)): identifiers held separately,
  reversible under controlled conditions.
- A reviewer must **spot-check** redactions against originals.

**Do NOT use reversibility when:**

- The goal is **HIPAA Safe Harbor anonymization** or a true **anonymous** release, a re-identification mapping defeats anonymization. Use `method="remove"` and keep
  **no** mapping.
- The redacted text leaves your trust boundary and the mapping might travel with
  it. The mapping is the secret; never co-locate it with the de-identified output.

## Install

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

## Quick start: reversible round-trip

```python
import openmed

note = "Patient John Doe (MRN 00481726) seen on 2024-03-02 by Dr. Alice Smith."

# 1) De-identify AND capture the reversal mapping
deid = openmed.deidentify(
    note,
    method="mask",          # or "replace" for realistic surrogates
    keep_mapping=True,       # <-- required to enable reidentify()
    policy="gdpr_pseudonymization",
)

safe_text = deid.deidentified_text       # ship/process this
mapping   = deid.mapping                  # SECRET: store separately, encrypted

# 2) Later, under authorization, restore the original
restored = openmed.reidentify(safe_text, mapping)
assert restored == note
```

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/reidentifying-text/SKILL.md