cognovís health
sdk · llm gateway · prompt formulation

Prompt-formulation guide.

How to format prompts for the LLM gateway declaration contract. Covers PII modes, quasi-ID conventions, the phi_references declaration contract, worked PASS and FAIL examples, and migration from the legacy combination_count API.

Implementation Status

The exhaustive declaration path, model-routed detection, authenticated SDK-context path, direct-identifier cross-check, and public-population Re-ID preflight are active gateway behavior.

Trust model

What the gateway guarantees — and what callers must do.

The gateway enforces a Zone-A → Zone-C anonymization boundary (ADR-privacy-and-agent-data-plane). Callers are internal Integration Layer services acting in good faith; adversarial misuse is addressed at the Keycloak / service-token access-control layer.

Gateway guarantees

  • PHI declared via phi_references is tokenized before leaving the gateway — the mapping lives in process memory only, never on disk or in logs. When every route of the job is privacy-approved, the original text is forwarded instead (privacy-approved routes).
  • Unless every route of the job is privacy-approved, personal data found on the model-routed path is reviewed by a physician before any model call: the known patient's supplied identifiers and the master-data patterns of any person (KVNR, street with house number, postal code with city, a date after a birth phrase) are matched deterministically, and other free text is assessed for person names only. Other dates, ages, classification and billing codes, units and dosage pass through unmodified.
  • Re-identification risk preflight blocks requests where the quasi-ID combination is too unique to be safely anonymized, unless every route of the job is privacy-approved.
  • Every call is audited — caller, model, capabilities, PII mode, tokenization counts, preflight result. Metadata only; never PHI values.

Caller responsibilities

  • When using declaration: "exhaustive", declare ALL PHI in the prompt via phi_references. The gateway cross-checks tokenized text — undeclared PII returns HTTP 422.
  • Send the known patient's gateway.patient_identity on known-patient requests and resend the identical request with the physician's explicit gateway.pii_review decision after a 428. With the envelope, declaration: "exhaustive" and a non-empty phi_references are refused with HTTP 400. Known-patient intents are patient-chat, patient-chat-proposal-extraction, befund-extraction and befund-grounding. A name part that is a single letter or an initial, or a name inside a date such as 1. Mai 2026, 1. Mai or seit Mai, is never a finding. The gateway does not generalize quasi-IDs.
  • Do not put generalized quasi-IDs (e.g. "51-65", "PLZ-Region 90") in phi_references.values — those are left verbatim in the generalized text and not tokenized. Classification and billing codes are not phi_references values.
  • Only the authenticated server boundary may attach origin: "sdk-context" with chp-sdk-patient-context/v1 provenance. Unknown markers, invalid provenance, and invalid service credentials fall back to model-routed detection.

Declaration modes

Declared vs undeclared mode.

The gateway supports two PHI-handling modes depending on whether the caller can enumerate all PHI in the prompt.

Declared mode — declaration: "exhaustive"

  1. 1.Tokenize phi_references values, replacing PHI strings with tokens.
  2. 2.Cross-check the tokenized text for a residual KVNR.
  3. 3.Run embedded-regex cross-check on the tokenized prompt.
  4. 4.No match: forward the request. Works even when the detector model is unavailable.
  5. 5.Match: return HTTP 422 caller_declaration_violation.

When to use: Background agents with full structural access to the FHIR resource (billing agents, coding suggestion agents). Lower latency without a detector-model request.

Undeclared mode — no declaration field

  1. 1.Route untrusted message text to the bound pii-detect model. The gateway does not refuse that route on residency.
  2. 2.Match the known patient's identity envelope deterministically and strictly validate grounded person-name spans.
  3. 3.A finding or an incomplete names assessment returns HTTP 428 pii_review_required with zero model calls; the physician confirms or cancels the identical request.
  4. 4.Without findings: tokenize declared references, run the Re-ID preflight for caller-supplied quasi_ids, and forward. Never a 503 for personal data and never a silent raw-data fallback.

Authenticated message submodes: versioned SDK context and application-controlled system messages skip the detector model only after exact service-token authentication. Both still run tokenization, the DOB/KVNR/PLZ cross-check, and the Re-ID preflight.

When to use: Unstructured free-text pipelines (scanned Arztbrief, free-text entries). Higher latency, fail-closed on detector failure, no PHI enumeration required.

Dimension declaration: "exhaustive" No declaration
PHI discovery Caller enumerates Approved model-routed detector
Detection engine Embedded regex Local or EU-hosted piiDetection model
Detector unavailable Request proceeds HTTP 428 physician review
Latency Low Higher (detector model round-trip)
Caller effort High (must declare all PHI) Low

Privacy-approved routes

Both modes and the known-patient review apply only when at least one route the deployment binding resolves for the request's job, the first route or any fallback, is not privacy-approved. A route is privacy-approved when the binding declares it residency: local, or residency: eu-hosted with processingAgreementCovered: true.

When every route of the job is privacy-approved, a pii: "anonymized" request is forwarded with its original text. The gateway makes no pii-detect call and runs no matching, tokenization, KVNR cross-check or Re-ID preflight. It returns no pii_review_required, and it restores nothing in the answer. A decision that names a pending review returns HTTP 409 pii_review_invalidated and invalidates that review; an unknown or expired review id keeps pii_review_unknown, and a consumed or cancelled review keeps pii_review_consumed. The request reaches the model on the existing service or consumer authentication, without a physician confirmation and without a practitioner JWT. The output filter still applies, internal gateway fields are still stripped, and the audit records the detector result not_required with the reason privacy-approved-route.

Callers do not change their requests: keep pii: "anonymized", the identity envelope and your phi_references. pii: "real" still requires a practitioner JWT of the request tenant. For Mode A callers, the phi_references values are not tokenized on privacy-approved routes, so the answer is the model's answer on the original text and contains no token-to-FHIR-reference replacement. The coverage declaration is the operator's; the gateway does not verify it.

Quasi-ID conventions

Quasi-identifier conventions.

Quasi-identifiers are indirect attributes that can re-identify a patient when combined. The gateway does not generalize them; it forwards dates, ages and postal codes as written. These conventions are caller choices for declared-mode prompts and for caller-supplied quasi_ids.

Age groups

Use: Altersgruppe <range> or Patientin in Altersgruppe <range>

Age Correct form
0 – 17 Altersgruppe 0-17
18 – 30 Altersgruppe 18-30
31 – 50 Altersgruppe 31-50
51 – 65 Altersgruppe 51-65
66 – 80 Altersgruppe 66-80
81+ Altersgruppe 81+

Never include the exact age: "die 64-jährige Patientin" exposes the direct birth year. Use instead: "Patientin in Altersgruppe 51-65".

Classification and billing codes

Pass classification and billing codes through exactly as dictated or stored:

Code family Forwarded form
ICD-10-GM Hauptdiagnose J06.9
OPS OPS 5-470
SNOMED procedure subset SNOMED 80146002
Billing codes EBM 03000, GOZ 0010, GOÄ 1

Use Hauptdiagnose for primary, Diagnose for secondary. Do not expand a code into additional rare clinical narrative unless required for the task.

Dates

Use relative encoding where a reference event is known:

Encounter +3 Tage nach Anamnese
Diagnose gestellt +7 Tage nach Erstvorstellung
Kontrolle geplant +14 Tage

Never include absolute dates: "15.04.2026" uniquely identifies a visit timeline. If relative encoding is not meaningful, use month+year only: "April 2026".

PLZ (Postleitzahl)

Use the first 2 digits (PLZ-2-prefix):

Raw PLZ Generalized form
90402 PLZ-Region 90
80331 PLZ-Region 80
10115 PLZ-Region 10
20095 PLZ-Region 20

Never include the full PLZ, Ortsname, or Stadtteil name — those can be cross-correlated with age + diagnosis to narrow the population to re-identifiable size.

PHI declaration

Declaring PHI via phi_references.

The phi_references array maps FHIR resource IDs to the PHI strings that appear in the prompt. Every string in values that occurs in any message will be replaced by the token for that resource.

phi_references structure

"gateway": {
  "phi_references": [
    {
      "resourceType": "Patient",
      "id": "pvs-patient-12345",
      "values": [
        "Müller",
        "Erika Müller",
        "Frau Müller",
        "A123456789"   // KVNR, if present
      ]
    },
    {
      "resourceType": "Practitioner",
      "id": "pvs-practitioner-42",
      "values": [
        "Dr. Schmidt",
        "Schmidt",
        "123456789"    // LANR
      ]
    }
  ],
  "declaration": "exhaustive"
}

Rules

  • Include all surface forms the name may appear as (full name, surname only, title + surname).
  • Include identifier strings (KVNR, LANR, BSNR) if they appear in the prompt.
  • Do not include generalized quasi-IDs ("51-65", "PLZ-Region 90") in values — those are left verbatim.
  • Do not pre-substitute tokens ([Patient-1]) into your prompt text — token numbers are randomized per request.
  • Token format: [Patient-N], [Practitioner-N], [Encounter-N], [Condition-N]. Numbers are scoped to the request.

Correct pattern

Write the prompt with real PHI values in the message text. List all PHI strings in phi_references.values. The gateway tokenizes on your behalf — callers never see or control the generated tokens.

What the caller sends

{
  "role": "user",
  "content": "Prüfe den Fall für
    Frau Müller, Altersgruppe
    51-65, Hauptdiagnose E11.65."
}

What the gateway forwards

{
  "role": "user",
  "content": "Prüfe den Fall für
    [Patient-1], Altersgruppe
    51-65, Hauptdiagnose E11.65."
}

PASS and FAIL examples

Worked examples.

PASS examples are shown as the caller sends them (with real PHI values, declared in phi_references), plus the tokenized form the gateway forwards. FAIL examples show the exact pattern that triggers caller_declaration_violation.

pass

Example 1 — Billing coding suggestion

What the caller sends

{
  "messages": [
    {
      "role": "user",
      "content": "Encounter für Erika
        Müller, Altersgruppe 51-65.
        Hauptdiagnose E11.65.
        Behandelnder Arzt: Dr. Schmidt.
        Abgerechnete Ziffern: EBM 03220.
        Prüfe weitere EBM-Ziffern."
    }
  ],
  "gateway": {
    "requires": ["text", "medicalCoding"],
    "pii": "anonymized",
    "phi_references": [
      { "resourceType": "Patient",
        "id": "pvs-patient-12345",
        "values": ["Müller",
                   "Erika Müller"] },
      { "resourceType": "Practitioner",
        "id": "pvs-practitioner-42",
        "values": ["Dr. Schmidt"] }
    ],
    "declaration": "exhaustive"
  }
}

What the gateway forwards to the LLM

"Encounter für [Patient-1],
 Altersgruppe 51-65.
 Hauptdiagnose E11.65.
 Behandelnder Arzt: [Practitioner-1].
 Abgerechnete Ziffern: EBM 03220.
 Prüfe weitere EBM-Ziffern."

Why it passes: All PHI is declared in phi_references and replaced by the gateway. The age group is already generalized. Classification and billing codes pass through unmodified. No exact dates or full PLZ.

pass

Example 2 — Diagnosis documentation

What the caller sends

{
  "messages": [
    {
      "role": "user",
      "content": "Formuliere eine SOAP-Notiz
        für Tobias Weber (Altersgruppe
        18-30) mit Hauptdiagnose F32.1.
        Encounter +3 Tage nach
        Erstvorstellung."
    }
  ],
  "gateway": {
    "pii": "anonymized",
    "phi_references": [
      { "resourceType": "Patient",
        "id": "pvs-patient-99001",
        "values": ["Weber",
                   "Tobias Weber"] }
    ],
    "declaration": "exhaustive"
  }
}

Gateway forwards

"Formuliere eine SOAP-Notiz für
 [Patient-1] (Altersgruppe 18-30)
 mit Hauptdiagnose F32.1.
 Encounter +3 Tage nach
 Erstvorstellung."

Why it passes: Patient name declared and tokenized. Relative date used. Classification code passed through unmodified. No PLZ or city mentioned.

fail

Example 3 — Undeclared insurance number in free text

{
  "messages": [
    {
      "role": "user",
      "content": "Patient KVNR A123456789,
        Diagnose E11.65.
        Schlage EBM-Ziffern vor."
    }
  ],
  "gateway": {
    "phi_references": [],
    "declaration": "exhaustive"
  }
}

Why it fails

"A123456789" matches the KVNR cross-check [A-Z]\d{9}. The cross-check fires caller_declaration_violation because declaration: "exhaustive" was set but an undeclared identifier remains. Dates are not part of the cross-check.

Fix:

Declare the KVNR in phi_references.values or remove it.

fail

Example 4 — KVNR embedded in prompt text

{
  "messages": [
    {
      "role": "user",
      "content": "Versicherter A123456789
        hat Diagnose E11.65.
        Schlage EBM-Ziffern vor."
    }
  ],
  "gateway": {
    "phi_references": [],
    "declaration": "exhaustive"
  }
}

Why it fails

"A123456789" matches the KVNR pattern \b[A-Z]\d{9}\b. The cross-check fires caller_declaration_violation because declaration: "exhaustive" was set but an undeclared identifier remains.

Fix:

Declare the patient in phi_references so tokenization replaces the KVNR before the cross-check runs:

{ "resourceType": "Patient",
  "id": "pvs-patient-<id>",
  "values": ["A123456789"] }

After tokenization: "Versicherter [Patient-1] hat Diagnose E11.65."

Note: The embedded cross-check detects a KVNR via regex only — not surnames or free-text names. Name-based leakage (e.g. "Herr Bauer" without a matching phi_references entry) is caught by the tokenizer when the name is declared, but is silently forwarded if undeclared. Use undeclared mode with model-routed PII detection if name detection is required.

Cross-check failure modes

Debugging caller_declaration_violation.

When the embedded-regex cross-check finds a leftover PII pattern in the tokenized prompt, the gateway returns HTTP 422 with caller_declaration_violation and a doc_url pointing to this page.

Cause What you see Fix
Patient name not in phi_references caller_declaration_violation Add all name surface forms to phi_references.values
Exact date in message text caller_declaration_violation Replace with relative date or month+year
Full PLZ in message text caller_declaration_violation Replace with PLZ-2-prefix (PLZ-Region XX)
KVNR/LANR/BSNR in free text, not declared caller_declaration_violation Add identifier string to phi_references.values

Debugging workflow

  1. 1. Check the audit entry in chp_llm_audit.llm_audit_events for pii_scan_triggered = true.
  2. 2. Review your prompt text for the cross-check pattern: KVNR (single uppercase letter + 9 digits).
  3. 3. Ensure every name that appears in the prompt is listed in phi_references.values.
  4. 4. Ensure every identifier (KVNR, LANR) that appears in the prompt is listed in phi_references.values.
  5. 5. Resubmit. Multi-turn conversations require re-declaring PHI on each turn (ADR-privacy-and-agent-data-plane: no implicit cross-turn mapping retention).

Migration guide

Migration from the legacy combination_count API.

The legacy API required a caller-supplied combination_count and practice_size inside gateway.reid_preflight. The current API still accepts reid_preflight.quasi_ids and reid_preflight.combination_count, but the preferred path is to use declaration: "exhaustive" with phi_references instead, which removes the need to supply a caller-computed count.

Before — legacy API

{
  "messages": [{
    "role": "user",
    "content": "Patient Müller,
      64 Jahre, E11.65 ..."
  }],
  "gateway": {
    "pii": "anonymized",
    "reid_preflight": {
      "quasi_ids": {
        "age": "64",
        "icd": "E11.65"
      },
      "combination_count": 12,
      "practice_size": 1800
    }
  }
}

After — declaration contract

{
  "messages": [{
    "role": "user",
    "content": "Müller, Altersgruppe
      51-65, Hauptdiagnose E11.65 ..."
  }],
  "gateway": {
    "pii": "anonymized",
    "phi_references": [
      { "resourceType": "Patient",
        "id": "pvs-patient-...",
        "values": ["Müller",
                   "Patient Müller"] }
    ],
    "declaration": "exhaustive"
  }
}

Migration steps

  1. 1. Remove gateway.reid_preflight.combination_count — The legacy request field is rejected. Supply generalized gateway.quasi_ids instead.
  2. 2. Remove gateway.reid_preflight.practice_size — The legacy request field is rejected; the gateway uses the public-population model.
  3. 3. Generalize quasi-IDs inline in the prompt — Replace exact age, date, and PLZ values with generalized forms directly in the prompt text (e.g. "Altersgruppe 51-65", "PLZ-Region 90"). Classification and billing codes remain exact.
  4. 4. Add gateway.declaration: "exhaustive" — If your caller can enumerate all PHI. Otherwise omit it and the gateway will use model-routed entity discovery.
  5. 5. Move declared PHI into phi_references — From wherever it was inlined in the prompt text. Tokenization replaces the values before forwarding.

Canonical references

ADR-privacy-and-agent-data-plane is the normative specification for the tokenization mechanism and quasi-ID generalization rules. ADR-llm-gateway v2 is the authoritative source for the gateway API, capability vocabulary, authentication, and audit trail schema.