Glossary

Terms used across the piighost documentation. Each entry defines the concept by what it does. Class names stay in English.

Anonymization: Removing PII with no way to restore it. Irreversible by definition. A redacting placeholder factory anonymizes, since it keeps no mapping back to the value.
Cipher: A component that reversibly encrypts and decrypts bytes, so a store keeps ciphertext instead of plaintext. A leak of the store yields nothing without the key, held outside it. RedisConversationMemory and SqlAlchemyConversationMemory can use one to encrypt persisted values. AesGcmCipher is the built-in AES-GCM backend.
Confidential data: Everything piighost protects, that is personal data (PII) and secrets such as API keys. Each detected item is a value, replaced by a placeholder in the de-identified text.
Conversation memory: The store that accumulates a thread's entities across messages, so a value seen in one message keeps its placeholder in the next. InMemoryConversationMemory holds it in the process. RedisConversationMemory persists it in Redis, and SqlAlchemyConversationMemory in a SQL table. Both backends can encrypt the values with a cipher and hash the keys.
De-identification: Replacing confidential data with placeholders while keeping the mapping between each value and its placeholder, so the original can be restored later. The default piighost pipeline de-identifies. Under the GDPR this is pseudonymization, not anonymization.
Detection: One occurrence of a value spotted by a detector, that is a Span, the matched text, a label, and a confidence in the range 0 to 1. Detecting Patrick as PERSON at (0, 7) with confidence 0.95 is one Detection.
Detector: The component that finds confidential data in a text and returns detections. Detectors implement the AnyDetector protocol and are interchangeable. The three families are regex, NER, and LLM, listed under their own entries.
Entity: A group of detections that refer to the same value. Every occurrence of the value is one detection. The group shares one placeholder and restores to one value. Different from a detection, which is a single occurrence. Entity.
Entity resolver: The component that reconciles conflicting entities, that is entities that share a detection or whose values are close. MergeEntityResolver merges entities that share a detection, FuzzyEntityResolver merges near-duplicate values. SeparateEntityResolver keeps the entities apart. It gives each shared detection to the largest entity holding it and drops it from the others.
Guard rail: A component that re-checks the de-identified text for confidential data the pipeline missed. It runs after replacement and raises if a residual value remains. A guard rail can re-run a detector (DetectorGuardRail), classify the output with a local GLiNER2 model (Gliner2GuardRail), query an LLM (LLMGuardRail) or the Mistral moderation API (ModerationGuardRail).
Linker: The component that groups detections into entities. It finds the occurrences that refer to the same value, so they share a placeholder. Linking Patrick at (0, 7) and patrick at (34, 41) yields one entity. ExactEntityLinker.
LLM detector: A detector that prompts a large language model to return the values it finds as structured output. Slower and less deterministic than regex or NER, but able to reason about context. LLMDetector.
NER detector: Named Entity Recognition. An AI model that classifies the words of a text into categories decided in advance, such as person, location, or organization. Works on free text where a pattern cannot. Gliner2Detector, Gliner2PiiDetector, SpacyDetector, TransformersDetector, PresidioDetector, and BridgeDetector, which awaits a model run elsewhere, for example in JavaScript in the browser.
Pepper: A secret that keys a hasher, read from the PIIGHOST_HASH_PEPPER environment variable. The pepper is mandatory, because a low-entropy value hashed without a secret stays brute-forceable. Used by Sha256Hasher and Argon2Hasher.
PII: Personally Identifiable Information, the personal-data part of confidential data. Any value that can identify a person, that is name, address, phone number, email, location, organization, account number. piighost finds and replaces PII so a downstream LLM never sees the raw value.
Placeholder: The token that replaces a value in the de-identified text, for example <<PERSON:1>> or <<EMAIL:1>>. What a placeholder looks like is decided by a placeholder factory.
Placeholder factory: The component that produces placeholders. It decides the token shape and what the token preserves, that is a label, a stable identity, both, or nothing. Built-in factories include RedactPlaceholderFactory, LabelPlaceholderFactory, LabelCounterPlaceholderFactory, LabelHashPlaceholderFactory, and MaskPlaceholderFactory.
Placeholder preservation tag: A phantom type (a type that exists only for the type checker) on a placeholder factory, stating what its tokens preserve. The concrete tags are PreservesNothing, PreservesLabel, PreservesShape, PreservesIdentityOnly, PreservesLabeledIdentityOpaque, and PreservesLabeledIdentityHashed. PreservesIdentity, PreservesRecognizableIdentity, and PreservesLabeledIdentity are abstract tags that group them. The middleware requires PreservesRecognizableIdentity so it can restore values. It rejects a factory without this tag at type-check time.
Recognizer: The token grammar the middleware uses to find a pipeline's placeholders in an LLM response, without reaching into the anonymizer. A pipeline exposes it in its recognizer attribute, which holds a BaseDelimitedPlaceholderFactory or None.
Regex detector: A detector that recognizes fixed patterns, character strings that follow a known structure such as an IBAN or a phone number. Effective on structured formats, useless on free text like a first name or a written date. RegexDetector.
Secret: A credential that must never reach a model, such as an API key, an access token, a private key, or a connection string. Secrets are the other part of confidential data. They are detected through the catalog groups piighost/secrets and piighost/secrets-extended, pulled for example with catalogs = ["catalog:piighost/secrets"]. The other catalog groups, piighost/generic and the regional ones, hold no secret pattern. Gliner2PiiDetector also asks its model for API keys and passwords.
Span: A half-open character range [start, end) inside a text, mirroring Python slice semantics. Every detection carries a Span to mark where the value sits. Span.
Thread: A conversation scope identified by a thread_id. Memory is isolated per thread, so two parallel conversations never share confidential data. A placeholder stays stable across all the messages of one thread.
thread_id: The string that identifies a thread. The thread pipeline and the middleware use it to scope memory and to route each message to the right conversation.