> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Gateway PII Analyzer (Presidio)

> Point the AI Gateway at your own Microsoft Presidio analyzer for named-entity PII detection — deploying the sidecar, the URL rules on cloud versus self-hosted, timeout and confidence settings, and how degradation is reported.

# AI Gateway PII Analyzer (Presidio)

The AI Gateway's built-in detectors find *structured* identifiers — card numbers, national IDs, emails, keys — with pattern and checksum tiers. **Names, street addresses and free-text medical identifiers need a named-entity recognizer**, and KnoxCall runs that tier on a [Microsoft Presidio](https://microsoft.github.io/presidio/) analyzer **you** operate, so prompt text never leaves your boundary for analysis.

**Scope: This tenant.** Each workspace points at its own analyzer; there is no platform default.

**Before you start**

* Somewhere to run a container that the KnoxCall gateway can reach over HTTPS.
* Read [PII redaction](/ai-gateway/pii-redaction#presidio-optional) for what the tier adds and how it combines with policies.

## 1. Deploy the analyzer

Run the official analyzer image (`mcr.microsoft.com/presidio-analyzer`) or the sidecar packaging in the KnoxCall repository (`docker/presidio-sidecar/`). KnoxCall calls `POST /analyze` on the base URL you configure, with the text, the language and the entity list.

Where it must live depends on how you run KnoxCall:

| Deployment         | Analyzer URL                                                                                                                                                                                                                                                           |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **KnoxCall Cloud** | A **publicly routable** host, over HTTPS, in front of your own authentication if you add any. A private address (`10.x`, `192.168.x`, `127.0.0.1`, `169.254.x`) is refused when you save it — the private network reachable from the gateway is KnoxCall's, not yours. |
| **Self-hosted**    | May be a private-network address on the network you own, if you tick the private-host acknowledgement below. Link-local and cloud-metadata addresses (`169.254.0.0/16`, `fe80::/10`) are refused everywhere.                                                           |

Put the analyzer behind TLS and restrict who can reach it: the requests carry the prompt text being inspected.

## 2. Enter it in KnoxCall

**Settings → Integrations → This tenant → AI Gateway PII analyzer (Presidio)** → *Configure*:

| Field                                                | Value                                                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Presidio analyzer URL**                            | Base URL, e.g. `https://presidio.your-company.com` — no `/analyze` suffix             |
| **Language**                                         | `en` unless your model supports another                                               |
| **Per-call timeout (ms)**                            | Default `1500`. Keep it short — the built-in tiers still run if the analyzer is slow. |
| **Confidence threshold (0–1)**                       | Default `0.4`. Matches below it are dropped.                                          |
| **Analyzer is on this deployment's private network** | Self-hosted only. Tick it for a private address you own. Ignored on Cloud.            |

**Save.** The URL is validated when you save: a refused destination returns `presidio_url_blocked` with the reason, rather than being stored and discovered later.

## 3. Verify

Send a prompt containing a name and an address through a gateway with a PII policy that includes Presidio entities; the [PII events](/ai-gateway/pii-redaction#pii-events) ledger shows the match with the Presidio recognizer as its source.

## How failure is reported

The analyzer is called on the buffered request path with a circuit breaker; five consecutive failures open it and the stack falls back to the built-in tiers.

* **With a PII policy attached**, that fallback is refused rather than served: the request gets `503 pii_policy_degraded`, because a policy that promised name detection cannot be silently enforced without it.
* **With no policy attached**, the request is served with `X-Knox-AI-Pii-Degraded: presidio_url_refused` or `presidio_circuit_open`, and a `detector_unavailable` row is written to the PII events ledger.

## Things that bite

* **The URL is re-resolved and pinned on every call.** A hostname that later starts resolving to a private address on Cloud stops being used; check the gateway's PII events if detection quietly drops off.
* **Timeout is per call, on the request path.** A generous timeout makes every gateway request that long when the analyzer is unhealthy.
* **Changing the URL or threshold takes effect on the next request** — no restart.

## Related

* [PII redaction](/ai-gateway/pii-redaction) — tiers, policies and the events ledger
* [AI Gateway firewall](/ai-gateway/firewall)