Placeholder factories¶

A placeholder is the synthetic placeholder that takes the place of a detected PII before the text is handed to the LLM. Instead of sending "Patrick lives in Paris" to the LLM, the pipeline sends "<<PERSON:1>> lives in <<LOCATION:1>>". The original values stay in the cache and the conversation memory; the LLM never sees them.

A placeholder factory decides what those placeholders look like and how much information they carry. Two questions structure the choice:

1. Are placeholders unique per entity? Patrick and Marie should not both collapse onto a generic <<PERSON>>, otherwise the LLM cannot tell them apart. A unique placeholder per entity lets the LLM reason about relations between entities: "is the manager the same person as Patrick?" becomes "is <<PERSON:1>> the same as <<PERSON:2>>?" and gets a clear answer.
2. Are placeholders reversible? Given a placeholder alone, can the original value be recovered without consulting the cache? This is the precondition for the middleware's string-replacement step on tool arguments. If two placeholders collapse onto the same <<PERSON>>, there is no way to know which original to restore.

Seven families of factories sit at different points on that spectrum, and the choice has direct consequences on which ToolCallStrategy you can use safely. See Tool-call strategies for the runtime side.

• No information (<<REDACT>>): a constant placeholder that reveals nothing to the LLM. Classic redaction. No reasoning possible on entities (the LLM cannot tell that the value was a city, so it cannot decide to call get_weather).
• Id only (<<REDACT:a1b2c3d4>>): a unique hash per entity, without revealing the type. The LLM sees that two distinct entities exist but cannot tell whether they are persons, emails, or credit cards. Keeps reversibility on the tool side without giving any semantic hint to the model.
• Type only (<<PERSON>>, <<EMAIL>>): the type is revealed but not the identity. Multiple persons in the same conversation collapse onto the same <<PERSON>> placeholder, so cross-references break.
• Type + id (opaque) (<<PERSON:1>>, <<PERSON:a1b2c3d4>>): type revealed, stable identity, clearly synthetic placeholder. The LLM can tell that <<PERSON:1>> and <<PERSON:2>> are different people. Unique, so reversible by string replacement.
• Type + partial value (p***@mail.com): the format is preserved but real content is partially visible. The LLM sees that it is an email, may guess the domain, but cannot recover the full address. Riskier on privacy (real fragments leak) and reversibility (collisions possible).
• Type + id (Faker) (john.doe@gmail.com): a fully plausible fake value. Natural-looking output, but exposes a coincidental-collision risk with a real-world value.
• Type + id (realistic hashed) (a1b2c3d4@anonymized.local): a realistic fake value with a hash guaranteeing uniqueness. Combines the realistic format with a guarantee of non-collision.

Family details¶

No information: total destruction¶

The placeholder is a fixed string (e.g. <<REDACT>>). The LLM learns that something was redacted but nothing about its type, count, or relations. The conversation loses every internal reference: an agent trying to act on "send the invoice to the client" cannot tell whether the client is the one mentioned earlier or someone new. Useful for archival redaction, useless when an agent has to reason.

Built-in: RedactPlaceholderFactory (output: <<REDACT>> by default, configurable via the value argument). Tag PreservesNothing.

Id only: identity without type¶

<<REDACT:a1b2c3d4>>. Original trade-off: the placeholder keeps the synthetic <<...>> shape but does not reveal the label; it does carry a unique hash per entity. The LLM cannot tell whether the entity is a person, an email, or a credit card, but it can see that <<REDACT:a1b2c3d4>> and <<REDACT:ef98abcd>> are two distinct entities. One of the most protective levels while remaining usable on the tool side (the hash is unique, so string replacement works).

Built-in: RedactHashPlaceholderFactory (output: <<REDACT:a1b2c3d4>>, prefix configurable). Tag PreservesIdentityOnly (under PreservesIdentity). The middleware accepts this factory like any other identity-preserving factory through covariance.

Type only: known type, identities collapsed¶

<<PERSON>>, <<EMAIL>>. The LLM knows that something is a person, an email, a credit card, and can answer questions that depend on the type alone. But two different persons in the same conversation collapse onto the same placeholder. The classic failure mode is cross-reference: "is Patrick the same person as the manager mentioned earlier?" becomes "is <<PERSON>> the same as <<PERSON>>?", which has no answer.

Built-in: LabelPlaceholderFactory (output: <<PERSON>>). Tag PreservesLabel.

Type + id (opaque)¶

<<PERSON:1>>, <<PERSON:a1b2c3d4>>. The string clearly is not a person, an email, or a card number, it's a placeholder. The LLM cannot mistake it for real data, audit logs are easy to scan, and there is zero chance of collision with a real value. Trade-off: a strict downstream prompt or tool that validates "argument must look like an email" will reject these placeholders.

Built-in: LabelCounterPlaceholderFactory (<<PERSON:1>>), LabelHashPlaceholderFactory (<<PERSON:a1b2c3d4>>). Tag PreservesLabeledIdentityOpaque.

Type + id (realistic hashed)¶

A custom factory can produce values that look like the original format but whose content is driven by a hash, e.g. a1b2c3d4@anonymized.local for an email, or Patient_a1b2c3d4 for a name. The placeholder passes basic format validation (email regex, length, allowed characters), so downstream tools and prompt templates that expect a real-looking value still work. Because the content is a hash, the placeholder is unique and impossible to coincidentally match an existing real value.

Built-in: FakerHashPlaceholderFactory (configured with a label -> strategy mapping that must cover every label your detector emits, no fallback: an unknown label raises ValueError). Tag PreservesLabeledIdentityHashed. See Writing your own below for a complete example.

Type + id (Faker)¶

FakerPlaceholderFactory returns fully plausible fake data: john.doe@example.com, Jean Dupont, +33 6 12 34 56 78. The LLM cannot tell that the value was anonymised, which is sometimes exactly what you want (clean drafts, no <<PERSON:1>> strings showing up in user-visible text). Two specific risks come with this:

1. Coincidental collision with real values. A Faker email could land on a real person's actual email address. If a tool response then contains that real address, the deanonymisation step cannot tell whether it should be replaced or left alone.
2. The agent may reason on the value as if it were real. If a downstream tool routes on the email domain, it will route on the fake domain, a feature in PASSTHROUGH-style flows but a footgun in FULL flows where real PII flows back to the LLM.

Use Faker for archival, demo, or one-shot redaction. Prefer opaque or format-preserving hash placeholders when the agent has tool calls that touch real systems. Tag PreservesLabeledIdentityFaker.

Type + partial value: partial value leak¶

j***@mail.com, ****4567, P******. The placeholder preserves part of the original value: the email domain, the last four digits of a card, the first letter of a name. The LLM can reason on more than the type: "the email is on the company domain", "the card ends in 4567", "the name starts with P". Two trade-offs come with this:

1. Real fragments of the PII reach the LLM. It cannot reconstruct the full value, but j***@mail.com already places the user inside a known mail provider.
2. Collisions are possible. Two different cards ending in 4567 collapse onto ****4567; two emails sharing the first letter and domain end up identical. The id is "mostly unique" but not guaranteed.

Built-in: MaskPlaceholderFactory. Tag PreservesShape. The middleware refuses it for the same reason as PreservesLabel: an ambiguous placeholder cannot be deanonymised through string replacement.

Preservation tags¶

Every factory carries a phantom type that summarises the preservation level of its placeholders. The type-checker reads this tag to validate a factory against its consumers.

Identity of each family.

Two angles, two tables. Confidentiality: what leaks to the LLM (attacker / privacy point of view). Exploitation: what the agent and the system can do with the placeholder (functional capabilities point of view). The same answer can be good in one and problematic in the other; this is exactly the tension we make explicit.

Shared colour code: blue = best, green = acceptable, yellow = partial, red = problematic.

Confidentiality (what leaks to the LLM)¶

Exploitation by the LLM and the agent¶

Legend: best acceptable partial problematic

Tags form an inheritance hierarchy that the type-checker exploits through the covariance of AnyPlaceholderFactory[PreservationT_co]. Two orthogonal axes structure the taxonomy: Label (the placeholder reveals the type) and Identity (the placeholder is unique per entity). PreservesLabeledIdentity combines the two via multiple inheritance, so a <<PERSON:1>> factory is both a PreservesLabel and a PreservesIdentity. A consumer typed against PreservesIdentity therefore accepts PreservesIdentityOnly and every PreservesLabeledIdentity*, while rejecting PreservesLabel / PreservesShape / PreservesNothing which lack the uniqueness guarantee.

classDiagram
    class PlaceholderPreservation {
        root
    }
    class PreservesNothing {
        <<REDACT>>
    }
    class PreservesLabel {
        &lt;&lt;PERSON&gt;&gt;
    }
    class PreservesShape {
        j***@mail.com
    }
    class PreservesIdentity {
        abstraction
    }
    class PreservesIdentityOnly {
        <<REDACT:a1b2c3d4>>
    }
    class PreservesLabeledIdentity {
        abstraction
    }
    class PreservesLabeledIdentityOpaque {
        &lt;&lt;PERSON_1&gt;&gt;
        &lt;&lt;PERSON:a1b2c3d4&gt;&gt;
    }
    class PreservesLabeledIdentityRealistic {
        abstraction
    }
    class PreservesLabeledIdentityHashed {
        a1b2c3d4@anonymized.local
        Patient_a1b2c3d4
    }
    class PreservesLabeledIdentityFaker {
        john.doe@example.com
        Jean Dupont
    }

    PlaceholderPreservation <|-- PreservesNothing
    PreservesNothing <|-- PreservesLabel
    PreservesNothing <|-- PreservesIdentity
    PreservesLabel <|-- PreservesShape
    PreservesIdentity <|-- PreservesIdentityOnly
    PreservesLabel <|-- PreservesLabeledIdentity
    PreservesIdentity <|-- PreservesLabeledIdentity
    PreservesLabeledIdentity <|-- PreservesLabeledIdentityOpaque
    PreservesLabeledIdentity <|-- PreservesLabeledIdentityRealistic
    PreservesLabeledIdentityRealistic <|-- PreservesLabeledIdentityHashed
    PreservesLabeledIdentityRealistic <|-- PreservesLabeledIdentityFaker

PreservesLabeledIdentity inherits from both PreservesLabel and PreservesIdentity (multiple inheritance). This expresses the "A is a B but not every B is an A" relation: every PreservesLabeledIdentity is also a PreservesLabel and a PreservesIdentity, but the reverse is false. A consumer typed against Pipeline[PreservesIdentity] therefore accepts factories with or without labels, as long as they produce unique placeholders per entity.

A factory declares the most specific tag that matches its guarantees:

class LabelCounterPlaceholderFactory(AnyPlaceholderFactory[PreservesLabeledIdentityOpaque]): ...
class LabelHashPlaceholderFactory(AnyPlaceholderFactory[PreservesLabeledIdentityOpaque]): ...
class FakerPlaceholderFactory(AnyPlaceholderFactory[PreservesLabeledIdentityFaker]): ...
class LabelPlaceholderFactory(AnyPlaceholderFactory[PreservesLabel]): ...
class MaskPlaceholderFactory(AnyPlaceholderFactory[PreservesShape]): ...
# No built-in for the id-only branch: implement your own with
# PreservesIdentityOnly for a hashed redact like <<REDACT:a1b2c3d4>>.

Built-in factories¶

The naming follows a <Style><Mechanism>PlaceholderFactory schema:

• Style = what the placeholder preserves (Redact = nothing, Label = type, Faker = PII shape, Mask = partial value)
• Mechanism = how uniqueness is achieved (Counter = sequential, Hash = SHA-256; absent when not relevant)

LabelCounterPlaceholderFactory and LabelHashPlaceholderFactory are the safe defaults. RedactCounter / RedactHash add uniqueness without leaking the label (useful for bias reduction). FakerCounter / FakerHash produce a realistic format: you must explicitly provide a strategy per label (3 modes: base, template with {counter} or {hash}, callable like fake_ip() or fake_phone()). FakerPlaceholderFactory is reversible but its placeholders can collide with real values. RedactPlaceholderFactory, LabelPlaceholderFactory and MaskPlaceholderFactory are non-reversible redaction tools (rejected by the middleware).

Which placeholder to pick?¶

The placeholder factory is the place where the privacy / agent-capability trade-off is made explicit. The right choice depends on the use case. Two scenarios cover most needs.

Case 1: simple anonymisation (one-shot, archival, compliance)¶

The goal is to produce a sanitised version of a document: redacting a court ruling, scrubbing an HR record before archival, exporting a dataset. No agent, no tools, sometimes not even reversibility.

Case 2: anonymisation for an LLM / agent with tools¶

The LLM reasons about the conversation, and tools (CRM, DB, mail) need real values at call time. The middleware does string replacement on tool arguments, so it requires a unique placeholder per entity.

Direct consequence: only families with preserved identity (Id only, every Type + id variant) are compatible. No information, Type only and Type + partial value are rejected at type-check (and at runtime via get_preservation_tag).

To avoid in an agent:

• LabelPlaceholderFactory and MaskPlaceholderFactory are rejected by the middleware (no uniqueness guarantee). Usable outside the middleware, or in ToolCallStrategy.PASSTHROUGH mode (the agent never receives the real values).
• FakerPlaceholderFactory when the pipeline runs FULL or INBOUND_ONLY and tools may return real emails or names: undetectable external collision risk.

The preservation tag exists so this choice is visible to the type-checker, not buried in placeholder-format trivia. A factory tagged PreservesShape cannot be plugged into the middleware by accident: it will fail at type-check time, not on the first tool call in production.

Why PIIAnonymizationMiddleware requires PreservesIdentity¶

The middleware operates on three boundaries: input messages (LLM in), output messages (LLM out), and tool calls. The first two go through the cache; the tool calls cannot.

Input/output messages. When abefore_model anonymises a message, it stores hash(anonymized_text) → original in the cache. The reply from the LLM is looked up by exact hash, so deanonymisation is a clean key lookup. This works for any factory, regardless of whether placeholders are unique.

Tool calls. The LLM produces tool arguments by combining and paraphrasing the placeholders it received. The exact text was never anonymised by the pipeline, so it is not in the cache. The only way to deanonymise is string replacement: scan the args for known placeholders and substitute the original value of each. The same is true in reverse for the tool response, which is re-anonymised by replacing known PII values with their placeholders.

That string-replacement step is unambiguous only if every entity maps to a unique placeholder. If two entities collapse onto <<PERSON>>, there is no way to know which original to restore. The middleware therefore narrows its accepted type to ThreadAnonymizationPipeline[PreservesIdentity], which through covariance encompasses both PreservesIdentityOnly (hashed redact, no label) and every PreservesLabeledIdentity* (with label). Wiring a PreservesLabel / PreservesShape / PreservesNothing factory into the middleware is caught by pyrefly / mypy before the program runs.

ThreadAnonymizationPipeline mirrors that constraint at runtime via get_preservation_tag(), so untyped or dynamically-built factories that bypass the type-checker are still rejected at construction time.

See Tool-call strategies for the only escape hatch (ToolCallStrategy.PASSTHROUGH, where the tool boundary is never crossed in clear text).

Writing your own¶

Subclass AnyPlaceholderFactory[<tag>] with the right preservation tag for your guarantees, then implement create().

import uuid
from piighost.models import Entity
from piighost.placeholder import AnyPlaceholderFactory
from piighost.placeholder_tags import PreservesIdentityOnly

class UUIDPlaceholderFactory(AnyPlaceholderFactory[PreservesIdentityOnly]):
    """Generates opaque UUID tags, e.g. <<a3f2-1b4c>>."""

    def create(self, entities: list[Entity]) -> dict[Entity, str]:
        result: dict[Entity, str] = {}
        seen: dict[str, str] = {}  # canonical → placeholder

        for entity in entities:
            canonical = entity.detections[0].text.lower()
            if canonical not in seen:
                seen[canonical] = f"<<{uuid.uuid4().hex[:8]}>>"
            result[entity] = seen[canonical]

        return result

from collections import defaultdict
from piighost.models import Entity
from piighost.placeholder import AnyPlaceholderFactory
from piighost.placeholder_tags import PreservesLabeledIdentityOpaque

class BracketPlaceholderFactory(AnyPlaceholderFactory[PreservesLabeledIdentityOpaque]):
    """Generates tags in the format [PERSON:1], [LOCATION:2], etc."""

    def create(self, entities: list[Entity]) -> dict[Entity, str]:
        result: dict[Entity, str] = {}
        counters: dict[str, int] = defaultdict(int)

        for entity in entities:
            label = entity.label
            counters[label] += 1
            result[entity] = f"[{label}:{counters[label]}]"

        return result

from piighost.ph_factory.faker_hash import (
    FakerHashPlaceholderFactory,
    fake_ip,
    fake_phone,
    fake_iban,
)

factory = FakerHashPlaceholderFactory(
    strategies={
        "person":     "John Doe",                  # base → "John Doe:a1b2c3d4"
        "location":   "Paris",                      # base → "Paris:a1b2c3d4"
        "email":      "{hash}@example.com",         # template → "a1b2c3d4@example.com"
        "url":        "https://example.com/{hash}", # template
        "ip_address": fake_ip(),                    # callable → "192.168.42.7"
        "phone":      fake_phone(),                 # callable → "+33 6 12 34 56 78"
        "iban":       fake_iban(),                  # callable → "FR76..."
    },
    hash_length=8,
)

from piighost.ph_factory.faker_hash import FakerCounterPlaceholderFactory

factory = FakerCounterPlaceholderFactory(
    strategies={
        "person":   "John Doe",                  # → "John Doe:1", "John Doe:2"…
        "email":    "{counter}@example.com",     # → "1@example.com", "2@example.com"…
    },
)

See also¶

• Tool-call strategies: how the middleware uses these placeholders, and why PASSTHROUGH is the only mode that tolerates weaker tags.
• Extending PIIGhost: the full protocol reference and the rest of the pipeline injection points.
• Limitations: operational consequences of the factory choice (cache, scaling, hallucinated PII).