> This page is for version v0.24.1.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.library.polygraf.actions

PII detection using Polygraf.

## Module Contents

### Functions

| Name                                                                                        | Description                                                                    |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`_classify_entities`](#nemoguardrails-library-polygraf-actions-_classify_entities)         | Split Polygraf entities into safe spans and report whether any                 |
| [`_detection_outcome`](#nemoguardrails-library-polygraf-actions-_detection_outcome)         | -                                                                              |
| [`_entity_shape`](#nemoguardrails-library-polygraf-actions-_entity_shape)                   | Return a PII-free structural description of an entity for logging.             |
| [`_get_polygraf_api_key`](#nemoguardrails-library-polygraf-actions-_get_polygraf_api_key)   | -                                                                              |
| [`_is_int`](#nemoguardrails-library-polygraf-actions-_is_int)                               | Strict integer check.                                                          |
| [`_mask_outcome`](#nemoguardrails-library-polygraf-actions-_mask_outcome)                   | -                                                                              |
| [`_resolve_source_config`](#nemoguardrails-library-polygraf-actions-_resolve_source_config) | Resolve the Polygraf config and per-source entity filter, validating `source`. |
| [`polygraf_detect_pii`](#nemoguardrails-library-polygraf-actions-polygraf_detect_pii)       | Checks whether the provided text contains any PII using Polygraf.              |
| [`polygraf_mask_pii`](#nemoguardrails-library-polygraf-actions-polygraf_mask_pii)           | Masks any detected PII in the provided text using Polygraf.                    |

### Data

[`FAILSAFE_MASK_PLACEHOLDER`](#nemoguardrails-library-polygraf-actions-FAILSAFE_MASK_PLACEHOLDER)

[`log`](#nemoguardrails-library-polygraf-actions-log)

### API

```python
nemoguardrails.library.polygraf.actions._classify_entities(
    entities: typing.List[typing.Any],
    enabled_entities: typing.Optional[typing.List[str]],
    text_length: int
) -> typing.Tuple[typing.List[typing.Tuple[int, int, str]], bool]
```

Split Polygraf entities into safe spans and report whether any
span is unsafe enough to require failing closed.

**Parameters:**

**`entities`** `List[Any]`

Raw entity records returned by Polygraf.

---

**`enabled_entities`** `Optional[List[str]]`

The configured entity-type filter (or `None` to
accept every Polygraf-reported type).

---

**`text_length`** `int`

Length of the original payload, used to validate that
integer offsets actually point inside the text.

---

**Returns:** `List[Tuple[int, int, str]]`

(safe\_spans, has\_malformed\_selected)

```python
nemoguardrails.library.polygraf.actions._detection_outcome(
    has_pii: bool
) -> nemoguardrails.actions.rail_outcome.RailOutcome
```

```python
nemoguardrails.library.polygraf.actions._entity_shape(
    entity: typing.Any
) -> str
```

Return a PII-free structural description of an entity for logging.

```python
nemoguardrails.library.polygraf.actions._get_polygraf_api_key() -> typing.Optional[str]
```

```python
nemoguardrails.library.polygraf.actions._is_int(
    value: typing.Any
) -> bool
```

Strict integer check.

`bool` is a subclass of `int` in Python, so a plain `isinstance(x, int)`
would accept `True`/`False` as valid offsets. Explicitly reject booleans
so a Polygraf response cannot smuggle bogus span coordinates past validation.

```python
nemoguardrails.library.polygraf.actions._mask_outcome(
    source: str,
    original_text: str,
    masked_text: str
) -> nemoguardrails.actions.rail_outcome.RailOutcome
```

```python
nemoguardrails.library.polygraf.actions._resolve_source_config(
    config: nemoguardrails.RailsConfig,
    source: str
) -> typing.Tuple[nemoguardrails.rails.llm.config.PolygrafDetection, typing.Any, typing.Optional[typing.List[str]]]
```

Resolve the Polygraf config and per-source entity filter, validating `source`.

```python
nemoguardrails.library.polygraf.actions.polygraf_detect_pii(
    source: str,
    text: str,
    config: nemoguardrails.RailsConfig,
    http_client: typing.Optional[nemoguardrails.http.HTTPClient] = None,
    kwargs = {}
) -> nemoguardrails.actions.rail_outcome.RailOutcome
```

async

Checks whether the provided text contains any PII using Polygraf.

**Parameters:**

**`source`** `str`

The source for the text, i.e. "input", "output", "retrieval".

---

**`text`** `str`

The text to check.

---

**`config`** `RailsConfig`

The rails configuration object.

---

**Returns:** `RailOutcome`

RailOutcome.block() if PII is detected or detection cannot complete safely,

**Raises:**

* `ValueError`: Only if `source` is not one of the allowed flows.
  Provider/network failures are caught and treated as fail-closed
  (the action returns a blocking outcome).

```python
nemoguardrails.library.polygraf.actions.polygraf_mask_pii(
    source: str,
    text: str,
    config: nemoguardrails.RailsConfig,
    http_client: typing.Optional[nemoguardrails.http.HTTPClient] = None,
    kwargs = {}
) -> nemoguardrails.actions.rail_outcome.RailOutcome
```

async

Masks any detected PII in the provided text using Polygraf.

**Parameters:**

**`source`** `str`

The source for the text, i.e. "input", "output", "retrieval".

---

**`text`** `str`

The text to check.

---

**`config`** `RailsConfig`

The rails configuration object.

---

**Returns:** `RailOutcome`

A transform outcome with PII masked. The transform uses

**Raises:**

* `ValueError`: Only if `source` is not one of the allowed flows.
  Provider/network failures are caught and treated as fail-closed.

```python
nemoguardrails.library.polygraf.actions.FAILSAFE_MASK_PLACEHOLDER = '<REDACTED>'
```

```python
nemoguardrails.library.polygraf.actions.log = logging.getLogger(__name__)
```