Skip to content

Recognizers

A Recognizer detects one entity type in text. spanguard ships a default set covering common PII/PHI, and you can plug in your own alongside (or instead of) the built-ins.

Built-in entity table

Entity type Detector Notes
EMAIL regex Unicode local part and domain; requires a dotted TLD of >= 2 letters.
PHONE regex NANP-style 3-3-4, optional +country, -/./space/parens separators.
SSN regex ###-##-####.
MRN regex (context-anchored) Requires an MRN prefix; only the digit run is redacted.
DOB regex mm/dd/yyyy (1- or 2-digit month/day) or ISO yyyy-mm-dd.
CREDIT_CARD regex + Luhn checksum Contiguous 13-19 digits, or standard printed groupings; Luhn-validated.
API_KEY regex Known prefixes (sk-, AKIA, ghp_) or a long high-entropy alnum run.
PERSON, LOCATION spaCy NER (optional [ner] extra) Requires the [ner] extra, a spaCy model, and passing SpacyRecognizer() (below).

Policy.entities selects which of the regex/checksum recognizers run by default. Passing your own recognizers=[...] to Redactor replaces entity-based auto-selection entirely — you get exactly the recognizers you list.

PERSON and LOCATION are never run by default, even with the [ner] extra installed. Add the spaCy recognizer next to the built-ins:

from spanguard import Policy, Redactor
from spanguard.recognizers import DEFAULT_RECOGNIZERS, SpacyRecognizer

redactor = Redactor(Policy(), recognizers=[*DEFAULT_RECOGNIZERS.values(), SpacyRecognizer()])

If Policy.entities names a type no recognizer covers, Redactor emits a UserWarning naming it, rather than silently detecting nothing.

The entity_type-is-a-label contract

Recognizer.entity_type (and the type field of every Span it returns) must be a fixed, non-sensitive entity label — e.g. "EMAIL", "ZIP" — never a value derived from the matched text. This label is what appears verbatim in placeholder mode output ([EMAIL]) and as a key in the audit record's counts. If you derived the label from the matched value, raw data would leak into redacted output and into the audit trail — exactly what spanguard exists to prevent.

Writing a custom recognizer

A recognizer is any object with an entity_type: str attribute and a recognize(text: str) -> list[Span] method — see the Recognizer protocol in spanguard.recognizers.base. Here is a complete example that detects 5-digit US ZIP codes and plugs it into a Redactor:

import re
from spanguard import Redactor, Policy, Span


class Zip5Recognizer:
    """Detects 5-digit US ZIP codes."""

    entity_type = "ZIP"

    def recognize(self, text):
        return [Span("ZIP", m.start(), m.end()) for m in re.finditer(r"\b\d{5}\b", text)]


policy = Policy(mode="placeholder", entities=("ZIP",))
redactor = Redactor(policy, recognizers=[Zip5Recognizer()])
result = redactor.redact("zip 90210 please")
print(result.text)
# zip [ZIP] please
print(result.audit.counts)
# {'ZIP': 1}

This exact snippet is executed by tests/test_docs_examples.py, so it cannot silently drift out of sync with the library's API.

Note

Passing recognizers=[...] overrides the entities-based default lookup entirely: only the recognizers you pass in are run, regardless of what Policy.entities lists. Combine your custom recognizer with the built-ins by importing them from spanguard.recognizers.regex_recognizers.DEFAULT_RECOGNIZERS if you want both.