Skip to navigation

nemoguardrails.server.experimental.provider.payload

View as MarkdownOpen in Claude

Payload projection models and guarded text locations.

Module Contents

Classes

NameDescription
GuardedArraySelectionSelect one array member by provider field values.
GuardedContentModelMark a content-bearing provider object.
GuardedMessageTargetIdentify the exact provider message field guarded by the pipeline.
GuardedPayloadModelValidate and locate guarded text in a provider payload projection.
GuardedProjectionModelProvide common validation behavior for guarded payload projections.
GuardedRequestModelValidate a provider request and determine its response mode.
GuardedTextAlternativesSelect one of several provider encodings for the same guarded text.
GuardedTextLocationLocate one guarded text member in a validated provider payload.
PayloadCapabilityProfileIdentify a closed payload capability understood by the framework.
PayloadProjectionContractDescribe the runtime semantics of one guarded payload projection.
ProjectionFieldCoverageClassify every reviewed field of one provider object.
ProjectionModelContractBind field coverage to one nested projection model.

Functions

NameDescription
_require_booleanReject integer values where a strict boolean is required.
guarded_schema_errorDescribe one projection failure without echoing provider content.
unknown_content_field_policyReturn the unknown-field policy requested for a validation, closed by default.
validate_payload_projection_contractValidate and return the semantic contract attached to a payload model.

Data

StrictFalse

_UNKNOWN_CONTENT_FIELDS_CONTEXT

API

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], ...]
nemoguardrails.server.experimental.provider.payload.GuardedArraySelection.select(
items: collections.abc.Sequence[object]
) -> object

Return the single array item matching the declared discriminator.

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

Bases: GuardedProjectionModel

Mark a content-bearing provider object.

Its object policy decides whether unreviewed members are accepted.

class nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget(
role: typing.Literal['user', 'assistant'],
_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']
nemoguardrails.server.experimental.provider.payload.GuardedMessageTarget.replace_content(
content: str
) -> None

Replace guarded content when the contract permits modification.

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

Bases: GuardedProjectionModel

Validate and locate guarded text in a provider payload projection.

guarded_text_location
GuardedTextLocation | GuardedTextAlternatives | None = None
nemoguardrails.server.experimental.provider.payload.GuardedPayloadModel.has_guarded_text_binding() -> bool
classmethod

Return whether the model declares how to locate guarded text.

nemoguardrails.server.experimental.provider.payload.GuardedPayloadModel.locate_guarded_message(

Locate the guarded message in the original provider payload.

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

Validate the declared guarded text location after model parsing.

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
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.

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

Bases: 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.

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

Return whether the request declares how to detect streaming.

class nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives(
)
Dataclass

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

locations
tuple[GuardedTextLocation, ...]
nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives._projection_location(
projection: pydantic.BaseModel

Return the single location matching the projected representation.

nemoguardrails.server.experimental.provider.payload.GuardedTextAlternatives.locate(
projection: pydantic.BaseModel,

Locate guarded text using the projected provider representation.

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

Require exactly one alternative to match the projection.

class nemoguardrails.server.experimental.provider.payload.GuardedTextLocation(
role: typing.Literal['user', 'assistant'],
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']
nemoguardrails.server.experimental.provider.payload.GuardedTextLocation.locate(

Locate guarded text in the original provider payload.

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

Return whether this location resolves to text in the projection.

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

Require the projected location to resolve to text.

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'
class nemoguardrails.server.experimental.provider.payload.PayloadProjectionContract(
projection_id: str,
direction: typing.Literal['request', 'response'],
)
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
nemoguardrails.server.experimental.provider.payload.PayloadProjectionContract.__post_init__() -> None

Validate the projection identity and nested model declarations.

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.

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

Require each reviewed field to have exactly one classification.

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

Bind field coverage to one nested projection model.

coverage
ProjectionFieldCoverage
model
type[BaseModel]
source_schema
str | None = None
nemoguardrails.server.experimental.provider.payload.ProjectionModelContract.__post_init__() -> None

Validate an explicitly declared provider source schema.

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

Reject integer values where a strict boolean is required.

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

Describe one projection failure without echoing provider content.

nemoguardrails.server.experimental.provider.payload.unknown_content_field_policy(
info: pydantic.ValidationInfo

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

nemoguardrails.server.experimental.provider.payload.validate_payload_projection_contract(
model: type[pydantic.BaseModel],
expected_direction: typing.Literal['request', 'response']

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

nemoguardrails.server.experimental.provider.payload.StrictFalse = Annotated[Literal[False], BeforeValidator(_require_boolean)]
nemoguardrails.server.experimental.provider.payload._UNKNOWN_CONTENT_FIELDS_CONTEXT = 'unknown_content_fields'