Choosing entity types#

What pii() finds depends on the entity types you list, and on the text around a value. Tune it on your own text before relying on it.

What each type catches#

From probing Enkrypt’s detector with sample texts, three times each:

Entity type

Caught

Missed

person

full names, lowercase names, single first names, public figures

pii

other identifiers: emails (when email is not listed), ticket and order numbers such as #1041 or 88412-AB

names: list person for those

email, phone

as named

ip_address

IPv4, including with a port

IPv6; IPv4 in some sentences

url

most URLs

some documentation URLs

secrets

key-like values

some password-like values; use secrets(), not pii()

Results were the same on every repeat of the same text and entity list. They changed with the surrounding sentence, and with which other entity types were listed: Last login 10.1.2.3, flagged by policy. was caught with ["ip_address"] and missed with ["pii", "person", "ip_address"].

Guidelines#

  1. List the entity types you mean. pii is not “all personal data”: it does not cover names (person), and it does flag ticket numbers, order numbers and similar IDs. Leave it out where those are expected, such as in a support desk.

  2. Keep each guard’s list short. Results change with what else is listed, so a long list can miss what a single type catches. A guard on a fetch tool’s arguments needs person, email and phone, not everything.

  3. Test on your own text. Detection is repeatable for the same text but depends on context. Run the probe below on samples of your data.

  4. Use local patterns for fixed formats. IPv6 addresses, passwords and other fixed formats are caught more reliably by pydantic-ai-harness’s local detectors, such as redact_secrets and personal_data, placed before the Enkrypt guard.

  5. Expect public figures to be redacted. That can stop the model from using what it knows about them. Leave person off where public names matter.

  6. Leave url off fetch tools. It flags URLs the tool legitimately needs.

Probing your own text#

This script sends texts to Enkrypt’s detector with different entity lists, several times each, and prints what was found:

import os
import requests

URL = "https://api.enkryptai.com/guardrails/detect"
HEADERS = {"apikey": os.environ["ENKRYPTAI_API_KEY"]}

def found(text: str, entities: list[str]) -> dict[str, list[str]]:
    payload = {"text": text, "detectors": {"pii": {"enabled": True, "entities": entities}}}
    response = requests.post(URL, json=payload, headers=HEADERS, timeout=30)
    response.raise_for_status()
    hits = response.json()["details"]["pii"].get("entities") or {}
    return {entity: sorted(values.values()) for entity, values in hits.items() if values}

for text in ["Maria Lopez could not log in from 192.168.4.20.", "Order 88412-AB shipped."]:
    for entities in (["person"], ["pii", "person", "ip_address"]):
        print(entities, text, found(text, entities))

Mind Enkrypt’s rate limit: the default plan allows 10 calls a minute.

Observing on real traffic#

Enkrypt(enforce=False) logs what every guard would do on real traffic without acting. Run it for a while, read the log, adjust entities, then switch to enforcing. See Observing before enforcing.