feat(library): add Polygraf PII detection and masking integration

docs/about/overview.mdx

@@ -103,6 +103,7 @@ The NeMo Guardrails library supports PII detection through multiple integrations
 - **Gliner**: Use [NVIDIA GLiNER-PII](/configure-guardrails/guardrail-catalog/third-party/gliner) for detecting entities such as names, email addresses, phone numbers, social security numbers, and more.
 - **Presidio-based detection**: Use [Microsoft Presidio](/configure-guardrails/guardrail-catalog/third-party/presidio) for detecting entities such as names, email addresses, phone numbers, social security numbers, and more.
 - **Private AI**: Integrate with [Private AI](/configure-guardrails/guardrail-catalog/third-party/privateai) for advanced PII detection and masking.
+- **Polygraf**: Integrate with [Polygraf](/configure-guardrails/guardrail-catalog/third-party/polygraf) for advanced PII detection and masking.
 - **AutoAlign**: Use [AutoAlign PII detection](/configure-guardrails/guardrail-catalog/third-party/auto-align) with customizable entity types.
 - **GuardrailsAI**: Access [GuardrailsAI PII validators](/configure-guardrails/guardrail-catalog/third-party/guardrails-ai) from the Guardrails Hub.
 

docs/configure-rails/guardrail-catalog/community/polygraf.mdx

@@ -0,0 +1,126 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Polygraf Integration"
+---
+[Polygraf](https://polygraf.ai/) offers a state-of-the-art PII detection and masking API designed to help identify and protect sensitive information in your text. This integration enables NeMo Guardrails to use Polygraf for PII detection and masking in input, output, and retrieval flows.
+
+## Setup
+
+1. Obtain a Polygraf API key and set it as an environment variable so the integration can authenticate cloud requests:
+
+    ```bash
+    export POLYGRAF_API_KEY="your-polygraf-api-key"
+    ```
+
+2. Pick the endpoint that matches your deployment:
+
+    - For **Polygraf cloud**, use `https://governance.api.polygraf.ai/gcp/pii/text-detect`.
+    - For **self-hosted** deployments, set this to your service endpoint (the local default is typically `http://localhost:8000/v1/pii/text-detect`).
+
+3. Update your `config.yml` file to include the Polygraf settings.
+
+    **PII detection config**
+
+    ```yaml
+    rails:
+      config:
+        polygraf:
+          server_endpoint: "https://governance.api.polygraf.ai/gcp/pii/text-detect"
+          input:
+            entities:  # If no entity is specified here, any detected PII will trigger the rail.
+              - Email
+              - Person
+              - Phone
+          output:
+            entities:
+              - Email
+              - Person
+              - Phone
+      input:
+        flows:
+          - polygraf detect pii on input
+      output:
+        flows:
+          - polygraf detect pii on output
+    ```
+
+    The detection flow blocks the input, output, or retrieval text if PII is detected and an entity match is configured.
+
+    **PII masking config**
+
+    ```yaml
+    rails:
+      config:
+        polygraf:
+          server_endpoint: "https://governance.api.polygraf.ai/gcp/pii/text-detect"
+          input:
+            entities:
+              - Email
+              - Person
+              - Phone
+          output:
+            entities:
+              - Email
+              - Person
+              - Phone
+      input:
+        flows:
+          - polygraf mask pii on input
+      output:
+        flows:
+          - polygraf mask pii on output
+    ```
+
+    The masking flow replaces detected PII spans with `<EntityType>` placeholders. For example, `Hi John, my email is john@example.com` becomes `Hi <Person>, my email is <Email>`.
+
+### Retrieval Flows
+
+To detect or mask PII in retrieved documents, configure the `retrieval` entities and enable the retrieval flow variant:
+
+```yaml
+rails:
+  config:
+    polygraf:
+      server_endpoint: "https://governance.api.polygraf.ai/gcp/pii/text-detect"
+      retrieval:
+        entities:
+          - Email
+          - Person
+          - Phone
+
+  retrieval:
+    flows:
+      - polygraf detect pii on retrieval
+      # or for masking:
+      # - polygraf mask pii on retrieval
+```
+
+## Usage
+
+Once configured, the Polygraf integration can automatically:
+
+1. Detect or mask PII in user inputs before they are processed by the LLM.
+2. Detect or mask PII in LLM outputs before they are sent back to the user.
+3. Detect or mask PII in retrieved chunks before they are sent to the LLM.
+
+The `polygraf_detect_pii` and `polygraf_mask_pii` actions in `nemoguardrails/library/polygraf/actions.py` handle the PII detection and masking processes, respectively.
+
+## Entity Types
+
+You can customize the PII handling behavior by modifying the `entities` lists under `input`, `output`, and `retrieval`. Entity labels should match the labels returned by your Polygraf deployment. Common entities include:
+
+- `Person`
+- `Email`
+- `Phone`
+
+For a complete list of supported entity types, refer to the [Polygraf documentation](https://polygraf.ai/api-agents/).
+
+## Failure Handling
+
+The integration is fail-closed: a Polygraf failure must not allow potentially-PII text to pass through the rail.
+
+- **Provider/network failure** (timeout, DNS, TLS, non-200 response, invalid JSON, malformed response shape). The underlying HTTP helper raises `ValueError`, which the actions catch internally. `polygraf detect pii on …` returns `True` (the rail blocks the message). `polygraf mask pii on …` replaces the entire payload with the `<REDACTED>` placeholder. The actions log a structural warning (failure category only); request bodies, response bodies, and entity values are never logged.
+- **Malformed entity span** (Polygraf returns an entry without a known `entity_type`, or with non-integer offsets, or with offsets outside `0 <= start < end <= len(text)`). The actions also fail closed: detection blocks the message and masking redacts the whole payload, rather than silently skipping the malformed span and forwarding the rest.
+- **Default timeout**: `30` seconds per call. Slow or unreachable endpoints cannot hang the rail pipeline.
+- **Missing API key**: if `POLYGRAF_API_KEY` is not set, the integration logs a warning since cloud endpoints typically reject unauthenticated requests, and proceeds to call the endpoint without an `Authorization` header.

docs/index.yml

@@ -179,6 +179,9 @@ navigation:
               - page: PolicyAI
                 path: configure-rails/guardrail-catalog/community/policyai.mdx
                 slug: policyai
+              - page: Polygraf
+                path: configure-rails/guardrail-catalog/community/polygraf.mdx
+                slug: polygraf
               - page: Presidio
                 path: configure-rails/guardrail-catalog/community/presidio.mdx
                 slug: presidio

examples/configs/polygraf/pii_detection/config.yml

@@ -0,0 +1,30 @@
+models:
+  - type: main
+    engine: openai
+    model: gpt-3.5-turbo-instruct
+
+rails:
+  config:
+    polygraf:
+      # For Polygraf cloud, use the governance endpoint. For self-hosted deployments,
+      # set this to your service endpoint (the default local example is typically
+      # "http://localhost:8000/v1/pii/text-detect").
+      server_endpoint: "https://governance.api.polygraf.ai/gcp/pii/text-detect"
+      input:
+        entities:
+          - Email
+          - Person
+          - Phone
+      output:
+        entities:
+          - Email
+          - Person
+          - Phone
+
+  input:
+    flows:
+      - polygraf detect pii on input
+
+  output:
+    flows:
+      - polygraf detect pii on output

examples/configs/polygraf/pii_masking/config.yml

@@ -0,0 +1,30 @@
+models:
+  - type: main
+    engine: openai
+    model: gpt-3.5-turbo-instruct
+
+rails:
+  config:
+    polygraf:
+      # For Polygraf cloud, use the governance endpoint. For self-hosted deployments,
+      # set this to your service endpoint (the default local example is typically
+      # "http://localhost:8000/v1/pii/text-detect").
+      server_endpoint: "https://governance.api.polygraf.ai/gcp/pii/text-detect"
+      input:
+        entities:
+          - Email
+          - Person
+          - Phone
+      output:
+        entities:
+          - Email
+          - Person
+          - Phone
+
+  input:
+    flows:
+      - polygraf mask pii on input
+
+  output:
+    flows:
+      - polygraf mask pii on output

nemoguardrails/library/polygraf/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.