> 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                 |
| [`_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.                                                          |
| [`_resolve_source_config`](#nemoguardrails-library-polygraf-actions-_resolve_source_config) | Resolve the Polygraf config and per-source entity filter, validating `source`. |
| [`detect_pii_mapping`](#nemoguardrails-library-polygraf-actions-detect_pii_mapping)         | Mapping for polygraf\_detect\_pii.                                             |
| [`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:**

Raw entity records returned by Polygraf.

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

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._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._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.detect_pii_mapping(
    result: bool
) -> bool
```

Mapping for polygraf\_detect\_pii.

Since the function returns True when PII is detected,
we block if result is True.

```python
nemoguardrails.library.polygraf.actions.polygraf_detect_pii(
    source: str,
    text: str,
    config: nemoguardrails.RailsConfig,
    kwargs = {}
) -> bool
```

async

Checks whether the provided text contains any PII using Polygraf.

**Parameters:**

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

The text to check.

The rails configuration object.

**Returns:** `bool`

True if PII is detected (or if the 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 True so the rail blocks the message).

```python
nemoguardrails.library.polygraf.actions.polygraf_mask_pii(
    source: str,
    text: str,
    config: nemoguardrails.RailsConfig,
    kwargs = {}
) -> str
```

async

Masks any detected PII in the provided text using Polygraf.

**Parameters:**

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

The text to check.

The rails configuration object.

**Returns:** `str`

The altered text with PII masked. Returns `FAILSAFE_MASK_PLACEHOLDER`

**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__)
```