Most PII redactors stop at plain text. This one also handles document images — both the text in them (names, addresses, IDs, dates, phones, …) and visual entities (signatures, stamps, QR codes, face photos, fingerprints). The models are trained on Indian names, documents, and contexts, and the text model works across Indian languages. Image OCR defaults to lightweight Tesseract; any OCR (Textract, Google Vision, …) plugs straight in for even better accuracy.

What it does

detect() is the core primitive — it finds every PII entity with its location, category, and confidence. The three transforms consume its output:

Anonymization is best-effort removal/generalization of detected identifiers — not a k-anonymity guarantee or a compliance determination.

Install

pip install document-pii-redactor            # core: text + OCR pipelines (permissive licenses)
pip install "document-pii-redactor[visual]"  # + visual-entity detection (AGPL-3.0 — see License)
pip install "document-pii-redactor[server]"  # + FastAPI service

Tesseract (apt-get install tesseract-ocr / brew install tesseract) is needed only for the built-in image OCR — not for text-only use or bring-your-own-OCR.

Quickstart

Load once, detect once — every transform consumes the detect() result:

from document_pii_redactor import ImagePIIRedactor, TextPIIRedactor

image_redactor = ImagePIIRedactor("ekacare/document-pii-redactor")
entities = image_redactor.detect("report.png")              # built-in Tesseract OCR

# …or bring your own OCR — pass words + pixel boxes, Tesseract is skipped
# and your exact boxes come back on the detected entities:
entities = image_redactor.detect("report.png", words=["John", "Doe"],
                                 boxes=[[100, 20, 140, 40], [145, 20, 180, 40]])

text_redactor = TextPIIRedactor("ekacare/document-pii-redactor")
text  = "Mr. John Doe, 45 yrs, DOB 12-03-1979, Indiranagar, Bangalore. Contact: +91 98765 43210."
spans = text_redactor.detect(text)

Redact — destroy:

image_redactor.redact("report.png", entities, mode="blur").save("redacted.png")  # or "solid" / "pixelate"

text_redactor.redact(text, spans)
# '[REDACTED], [REDACTED] yrs, DOB [REDACTED], [REDACTED], [REDACTED]. Contact: [REDACTED].'

Anonymize — generalize, one-way, no mapping kept. Ages become 10-year buckets, dates keep only the year, fine geography collapses to [LOCATION] (state and country survive), everything else becomes an unnumbered token:

image_redactor.anonymize("report.png", entities).save("anonymized.png")

text_redactor.anonymize(text, spans)
# '[PERSON], 40–49 yrs, DOB 1979, [LOCATION], [LOCATION]. Contact: [PHONE].'

De-identify — pseudonymize. Same value → same pseudonym throughout the document, and the entity→pseudonym mapping comes back for authorized re-linking. strategy="hash" gives tokens that stay stable across documents with no mapping to thread (secret= salts the hash):

deid = image_redactor.deidentify("report.png", entities)    # .image + .mapping
deid.image.save("deidentified.png")

text_redactor.deidentify(text, spans).text
# 'Person_1, Age_1 yrs, DOB Date_1, City_1, City_2. Contact: Phone_1.'

text_redactor.deidentify(text, spans, strategy="hash").text
# 'Person_539681, Age_6c8349 yrs, DOB Date_7f19c4, City_d12704, City_60c7d5. Contact: Phone_d57003.'

Good to know:

• Transforms require the detect() result as their second argument — detection is always the explicit first step, and runs the models exactly once.
• categories=[...] on detect() limits which of the 53 PII categories are found (default: all).
• Sequential pseudonyms are scoped to the returned mapping — pass mapping=result.mapping on the next page of the same record to keep numbering consistent. Hash tokens need no threading.

For a runnable end-to-end walkthrough, see examples/quickstart.ipynb.

ImagePIIRedactor(hf_repo, *, detect_visual=True, device=None,
                  categories=None, visual_score_threshold=0.25,
                  ocr_lang=None, cache_dir=None)

detect(image, *, categories=None, ocr_lang=None,
       words=None, boxes=None) -> list[PIIEntity]

redact(image, entities, *, mode="solid", color=(0,0,0), pad=2) -> PIL.Image

deidentify(image_or_text, entities_or_spans, *,
           mapping=None, strategy="counter", secret=None)

ImagePIIRedactor.list_entities() -> {"text": [...], "visual": [...]}
TextPIIRedactor.list_entities()  -> [...]

docker build -t document-pii-redactor .

# GPU
docker run --gpus all -p 7860:7860 \
  -e EKA_PII_HF_REPO=ekacare/document-pii-redactor \
  -v $HOME/.cache/huggingface:/root/.cache/huggingface \
  document-pii-redactor

# CPU
docker run -e EKA_PII_DEVICE=cpu -p 7860:7860 document-pii-redactor

curl -F file=@page.jpg http://localhost:7860/detect
curl -F file=@page.jpg -F mode=blur http://localhost:7860/redact -o redacted.png

document_pii_redactor/
  taxonomy.py, entities.py          # shared
  image/                            # IMAGE modality
    redactor.py  -> ImagePIIRedactor
    layoutlmv3.py -> text-PII-in-image detector
    yolo11m.py    -> visual-entity detector
  text/                             # TEXT modality
    redactor.py  -> TextPIIRedactor  (PII inside plain-text strings, no image)
    minilm.py    -> text-PII token classifier (char-span detector)

License & citation

Code: Apache-2.0 (keep the NOTICE attribution when redistributing). The optional [visual] extra installs ultralytics (AGPL-3.0). Model weights are licensed per model, following each base's license — the text pipeline is fully permissive; the image models inherit restrictions:

If you use this library or the models, please cite us:

@software{document_pii_redactor,
  author = {{Eka Care}},
  title  = {document-pii-redactor: detect, redact, de-identify, or anonymize
            PII in document images and plain text},
  year   = {2026},
  url    = {https://github.com/eka-care/document-pii-redactor},
  note   = {Model weights: https://huggingface.co/ekacare/document-pii-redactor}
}