Core Concepts

The protection flow

The canonical flow separates finding personal information from producing an answer:

user content
  ─▶ Detection adapter (Rampart Q4 or caller model)
  ─▶ anonymizer and placeholder engine
  ─▶ one privacy session for one private conversation
  ─▶ protected content to a Generation adapter/model
  ◀─ restored response; private mapping stays with the caller

Deterministic detectors run first for email, phone, card, IBAN, SSN, IP, and URL. Dictionary values and the private mapping provide stable matches. Rampart Q4 is a Detection model for names, addresses, and IDs; Gemini Nano, Gemma, and provider models are Generation models. ner: is a supported compatibility alias for detection:.

Private mapping and privacy session

• Private mapping assigns a stable placeholder to each distinct value and relates placeholders to original user content. It is the secret: keep it in memory and never serialize it outside the caller's trust boundary.
• Privacy session keeps one private mapping across turns and belongs to one private conversation. A new conversation gets a new session.

const conversation = privacy.createSession()
await conversation.anonymize("First, about João…")
await conversation.anonymize("Tell João I said hi") // same placeholder
conversation.rehydrate(assistantReply)

Explicit sessions are recommended for multi-turn use. Supplied sessions are borrowed; adapters never clear them. OpenAI and AI SDK adapters may own an implicit wrapper-scoped session reused across calls, while TanStack requires a caller-owned session. Create a fresh wrapper for each private conversation.

Trust boundaries and lifecycle

On device, the app owns the Detection adapter, privacy session, and Generation call; protected content can be sent to a provider while the private mapping stays local. In a server route or gateway, the adapter and mapping belong to your server and protect against the provider. Create one session per request, never one module-level session shared by users.

Generic inline callbacks and caller-supplied Detection models are trusted caller code. They are part of your boundary and are not sandboxed by local-pii.

Inline adapters resolve session, then anonymizer, then their default. Their cleanup runs even when a model or abort fails, with the primary failure taking precedence. TanStack passes hydration through and joins runs only for the same live session; persistence, full reload, cross-tab restoration, and a new session cannot restore a private conversation.