> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/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.

# nemoguardrails.server.experimental.provider.payload

Payload projection models and guarded text locations.

## Module Contents

### Classes

| Name                                                                                                          | Description                                                         |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`GuardedArraySelection`](#nemoguardrails-server-experimental-provider-payload-GuardedArraySelection)         | Select one array member by provider field values.                   |
| [`GuardedContentModel`](#nemoguardrails-server-experimental-provider-payload-GuardedContentModel)             | Mark a content-bearing provider object.                             |
| [`GuardedMessageTarget`](#nemoguardrails-server-experimental-provider-payload-GuardedMessageTarget)           | Identify the exact provider message field guarded by the pipeline.  |
| [`GuardedPayloadModel`](#nemoguardrails-server-experimental-provider-payload-GuardedPayloadModel)             | Validate and locate guarded text in a provider payload projection.  |
| [`GuardedProjectionModel`](#nemoguardrails-server-experimental-provider-payload-GuardedProjectionModel)       | Provide common validation behavior for guarded payload projections. |
| [`GuardedRequestModel`](#nemoguardrails-server-experimental-provider-payload-GuardedRequestModel)             | Validate a provider request and determine its response mode.        |
| [`GuardedTextAlternatives`](#nemoguardrails-server-experimental-provider-payload-GuardedTextAlternatives)     | Select one of several provider encodings for the same guarded text. |
| [`GuardedTextLocation`](#nemoguardrails-server-experimental-provider-payload-GuardedTextLocation)             | Locate one guarded text member in a validated provider payload.     |
| [`PayloadCapabilityProfile`](#nemoguardrails-server-experimental-provider-payload-PayloadCapabilityProfile)   | Identify a closed payload capability understood by the framework.   |
| [`PayloadProjectionContract`](#nemoguardrails-server-experimental-provider-payload-PayloadProjectionContract) | Describe the runtime semantics of one guarded payload projection.   |
| [`ProjectionFieldCoverage`](#nemoguardrails-server-experimental-provider-payload-ProjectionFieldCoverage)     | Classify every reviewed field of one provider object.               |
| [`ProjectionModelContract`](#nemoguardrails-server-experimental-provider-payload-ProjectionModelContract)     | Bind field coverage to one nested projection model.                 |

### Functions

| Name                                                                                                                                | Description                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`_require_boolean`](#nemoguardrails-server-experimental-provider-payload-_require_boolean)                                         | Reject integer values where a strict boolean is required.                      |
| [`guarded_schema_error`](#nemoguardrails-server-experimental-provider-payload-guarded_schema_error)                                 | Describe one projection failure without echoing provider content.              |
| [`unknown_content_field_policy`](#nemoguardrails-server-experimental-provider-payload-unknown_content_field_policy)                 | Return the unknown-field policy requested for a validation, closed by default. |
| [`validate_payload_projection_contract`](#nemoguardrails-server-experimental-provider-payload-validate_payload_projection_contract) | Validate and return the semantic contract attached to a payload model.         |

### Data

[`StrictFalse`](#nemoguardrails-server-experimental-provider-payload-StrictFalse)

[`_UNKNOWN_CONTENT_FIELDS_CONTEXT`](#nemoguardrails-server-experimental-provider-payload-_UNKNOWN_CONTENT_FIELDS_CONTEXT)

### API

```python
class nemoguardrails.server.experimental.provider.payload.GuardedArraySelection(
    match: tuple[tuple[str, str | int | bool], ...],
    cardinality: typing.Literal['exactly_one']
)
```

Dataclass

Select one array member by provider field values.

**`cardinality`** `Literal['exactly_one']`

---

**`match`** `tuple[tuple[str, str | int | bool], ...]`

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedArraySelection.select(
    items: collections.abc.Sequence[object]
) -> object
```

Return the single array item matching the declared discriminator.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedContentModel()
```

**Bases:** [GuardedProjectionModel](#nemoguardrails-server-experimental-provider-payload-GuardedProjectionModel)

Mark a content-bearing provider object.

Its object policy decides whether unreviewed members are accepted.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget(
    role: typing.Literal['user', 'assistant'],
    _object: nemoguardrails.server.experimental.provider.types.JsonObject,
    _member: str,
    allows_replacement: bool
)
```

Dataclass

Identify the exact provider message field guarded by the pipeline.

**`_member`** `str`

---

**`_object`** `JsonObject`

---

**`allows_replacement`** `bool`

---

**`has_text`** `bool`

Return whether the target holds text for content checks.

A validated projection reaches an empty or null target only when its
location allows empty text. The projection has then rejected generated
content in other reviewed fields; opaque metadata is not inspected.

---

**`message`** `GuardedMessage`

Return the message currently stored at the target.

---

**`role`** `Literal['user', 'assistant']`

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget.replace_content(
    content: str
) -> None
```

Replace guarded content when the contract permits modification.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedPayloadModel()
```

**Bases:** [GuardedProjectionModel](#nemoguardrails-server-experimental-provider-payload-GuardedProjectionModel)

Validate and locate guarded text in a provider payload projection.

**`guarded_text_location`** `GuardedTextLocation | GuardedTextAlternatives | None = None`

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedPayloadModel.has_guarded_text_binding() -> bool
```

classmethod

Return whether the model declares how to locate guarded text.

```python
nemoguardrails.server.experimental.provider.payload.GuardedPayloadModel.locate_guarded_message(
    payload: nemoguardrails.server.experimental.provider.types.JsonObject
) -> nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget
```

Locate the guarded message in the original provider payload.

```python
nemoguardrails.server.experimental.provider.payload.GuardedPayloadModel.validate_guarded_text_target() -> typing_extensions.Self
```

Validate the declared guarded text location after model parsing.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedProjectionModel()
```

**Bases:** `BaseModel`

Provide common validation behavior for guarded payload projections.

**`model_config`** `= ConfigDict(extra='allow', frozen=True)`

---

**`projection_contract`** `PayloadProjectionContract | None = None`

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedProjectionModel.validate_payload(
    document: object,
    unknown_content_fields: nemoguardrails.server.experimental.provider.types.UnknownContentFieldPolicy = UnknownContentFieldPolicy.F...
) -> typing_extensions.Self
```

classmethod

Validate a provider payload with the requested unknown-field policy.

FORBID is the default. ALLOW opens only objects whose policy declares
configurable unknown fields, and is reserved for trusted configuration.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedRequestModel()
```

**Bases:** [GuardedPayloadModel](#nemoguardrails-server-experimental-provider-payload-GuardedPayloadModel)

Validate a provider request and determine its response mode.

**`stream_selector_field`** `str | None = None`

---

**`streams_response`** `bool`

Read the validated selector; a permitted null selects buffered output.

Missing fields use their model default. The field declaration determines
whether null is accepted; the binding does not make a field nullable.

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedRequestModel.has_response_mode_binding() -> bool
```

classmethod

Return whether the request declares how to detect streaming.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives(
    locations: tuple[nemoguardrails.server.experimental.provider.payload.GuardedTextLocation, ...]
)
```

Dataclass

Select one of several provider encodings for the same guarded text.

**`locations`** `tuple[GuardedTextLocation, ...]`

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives._projection_location(
    projection: pydantic.BaseModel
) -> nemoguardrails.server.experimental.provider.payload.GuardedTextLocation
```

Return the single location matching the projected representation.

```python
nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives.locate(
    projection: pydantic.BaseModel,
    payload: nemoguardrails.server.experimental.provider.types.JsonObject
) -> nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget
```

Locate guarded text using the projected provider representation.

```python
nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives.validate_projection(
    projection: pydantic.BaseModel
) -> None
```

Require exactly one alternative to match the projection.

```python
class nemoguardrails.server.experimental.provider.payload.GuardedTextLocation(
    role: typing.Literal['user', 'assistant'],
    object_path: tuple[str | int | nemoguardrails.server.experimental.provider.payload.GuardedArraySelection, ...],
    member: str,
    allows_replacement: bool,
    replacement_blocked_by: str | None = None,
    allows_empty: bool = False
)
```

Dataclass

Locate one guarded text member in a validated provider payload.

**`allows_empty`** `bool = False`

---

**`allows_replacement`** `bool`

---

**`member`** `str`

---

**`object_path`** `tuple[str | int | GuardedArraySelection, ...]`

---

**`replacement_blocked_by`** `str | None = None`

---

**`role`** `Literal['user', 'assistant']`

---

```python
nemoguardrails.server.experimental.provider.payload.GuardedTextLocation.locate(
    payload: nemoguardrails.server.experimental.provider.types.JsonObject
) -> nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget
```

Locate guarded text in the original provider payload.

```python
nemoguardrails.server.experimental.provider.payload.GuardedTextLocation.matches_projection(
    projection: pydantic.BaseModel
) -> bool
```

Return whether this location resolves to text in the projection.

```python
nemoguardrails.server.experimental.provider.payload.GuardedTextLocation.validate_projection(
    projection: pydantic.BaseModel
) -> None
```

Require the projected location to resolve to text.

```python
class nemoguardrails.server.experimental.provider.payload.PayloadCapabilityProfile
```

**Bases:** `enum.Enum`

Identify a closed payload capability understood by the framework.

**`SINGLE_TEXT_V1`** `= 'single_text.v1'`

---

```python
class nemoguardrails.server.experimental.provider.payload.PayloadProjectionContract(
    projection_id: str,
    direction: typing.Literal['request', 'response'],
    profile: nemoguardrails.server.experimental.provider.payload.PayloadCapabilityProfile,
    root: nemoguardrails.server.experimental.provider.payload.ProjectionFieldCoverage,
    content_models: tuple[nemoguardrails.server.experimental.provider.payload.ProjectionModelContract, ...] = ()
)
```

Dataclass

Describe the runtime semantics of one guarded payload projection.

**`content_models`** `tuple[ProjectionModelContract, ...] = ()`

---

**`direction`** `Literal['request', 'response']`

---

**`profile`** `PayloadCapabilityProfile`

---

**`projection_id`** `str`

---

**`root`** `ProjectionFieldCoverage`

---

```python
nemoguardrails.server.experimental.provider.payload.PayloadProjectionContract.__post_init__() -> None
```

Validate the projection identity and nested model declarations.

```python
class nemoguardrails.server.experimental.provider.payload.ProjectionFieldCoverage(
    guarded_fields: frozenset[str] = frozenset(),
    constrained_fields: frozenset[str] = frozenset(),
    opaque_fields: frozenset[str] = frozenset(),
    local_extension_fields: frozenset[str] = frozenset()
)
```

Dataclass

Classify every reviewed field of one provider object.

**`constrained_fields`** `frozenset[str] = frozenset()`

---

**`guarded_fields`** `frozenset[str] = frozenset()`

---

**`local_extension_fields`** `frozenset[str] = frozenset()`

---

**`opaque_fields`** `frozenset[str] = frozenset()`

---

**`reviewed_fields`** `frozenset[str]`

Return every field accounted for by this coverage declaration.

---

```python
nemoguardrails.server.experimental.provider.payload.ProjectionFieldCoverage.__post_init__() -> None
```

Require each reviewed field to have exactly one classification.

```python
class nemoguardrails.server.experimental.provider.payload.ProjectionModelContract(
    model: type[pydantic.BaseModel],
    coverage: nemoguardrails.server.experimental.provider.payload.ProjectionFieldCoverage,
    source_schema: str | None = None
)
```

Dataclass

Bind field coverage to one nested projection model.

**`coverage`** `ProjectionFieldCoverage`

---

**`model`** `type[BaseModel]`

---

**`source_schema`** `str | None = None`

---

```python
nemoguardrails.server.experimental.provider.payload.ProjectionModelContract.__post_init__() -> None
```

Validate an explicitly declared provider source schema.

```python
nemoguardrails.server.experimental.provider.payload._require_boolean(
    value: object
) -> object
```

Reject integer values where a strict boolean is required.

```python
nemoguardrails.server.experimental.provider.payload.guarded_schema_error(
    error: pydantic.ValidationError,
    subject: str
) -> str
```

Describe one projection failure without echoing provider content.

```python
nemoguardrails.server.experimental.provider.payload.unknown_content_field_policy(
    info: pydantic.ValidationInfo
) -> nemoguardrails.server.experimental.provider.types.UnknownContentFieldPolicy
```

Return the unknown-field policy requested for a validation, closed by default.

```python
nemoguardrails.server.experimental.provider.payload.validate_payload_projection_contract(
    model: type[pydantic.BaseModel],
    expected_direction: typing.Literal['request', 'response']
) -> nemoguardrails.server.experimental.provider.payload.PayloadProjectionContract
```

Validate and return the semantic contract attached to a payload model.

```python
nemoguardrails.server.experimental.provider.payload.StrictFalse = Annotated[Literal[False], BeforeValidator(_require_boolean)]
```

```python
nemoguardrails.server.experimental.provider.payload._UNKNOWN_CONTENT_FIELDS_CONTEXT = 'unknown_content_fields'
```