The proxy can only restore a PII span if the model reproduces the <MASKED_…> token verbatim in its reply. Models sometimes paraphrase a token ("the patient" instead of <MASKED_PERSON_a1b2c3d4>) or split, rename, or translate it, and then there is nothing for KINDI to substitute back.

The opt-in X-Kindi-Preserve-Tags header tells KINDI to inject a short instruction into the system prompt asking the model to treat each token as a literal, opaque identifier and reproduce it exactly.

How to enable it

Send the header with true or 1 (case-insensitive). It defaults off; when absent, KINDI forwards your request byte-for-byte and injects nothing.

1234POST /api/v1/proxy/openai/v1/chat/completions
Authorization: Bearer mk_live_...
X-Provider-Key: sk-...
X-Kindi-Preserve-Tags: true

With the SDK helper, pass preserve_tags / preserveTags; it adds the header for you:

123456789from openai import OpenAI
from kindi import proxy_config

cfg = proxy_config("openai", "mk_live_...", "sk-...", preserve_tags=True)
client = OpenAI(
    base_url=cfg["base_url"],
    default_headers=cfg["default_headers"],  # includes X-Kindi-Preserve-Tags
    api_key="unused",
)

What gets injected

When enabled, KINDI prepends this instruction to your system prompt (OpenAI: into the first system message, or a new one if you have none; Anthropic: into the top-level system). Your own system prompt is never clobbered; the instruction is merged ahead of it:

The text may contain opaque placeholder tokens shaped like <MASKED_TYPE_ID> (for example <MASKED_PERSON_NAME_a1b2c3d4>). Treat each as a literal, opaque identifier: reproduce it exactly and never translate, rename, split, merge, or alter it.

The instruction itself is injected after masking, so it is forwarded to the provider unmasked (it contains no PII).

Even with preservation on, defensively check that every input token survived the round-trip for high-stakes pipelines; long contexts can still drop a token. See the survival-check pattern in Common mistakes.

Preservation is best-effort: it improves token survival but does not guarantee it. The model still controls its own output.