nemoguardrails.server.experimental.provider.projection_policy
nemoguardrails.server.experimental.provider.projection_policy
Field and object policies for provider payload projections.
Model declarations provide field coverage, guarded text locations, and exported contract schemas.
Module Contents
Classes
Functions
Data
API
Identify one reviewed object branch in a heterogeneous array.
Match keys must be required singleton Literal fields of the owning model. Cardinality applies when a text binding selects this branch from an array, not when the object is validated in isolation. Non-text branches use ‘any’. The same declaration describes selection in exported guard contracts.
Reject ambiguous or unrepresentable selector declarations.
Describe the reviewed boundary of one JSON object.
This metadata does not select guardrails, a deployment configuration, or a capability profile. Field-specific policy belongs on the field annotations.
Reviewed passthrough fields not declared as Pydantic fields. Names must be unique and must not overlap declared fields.
Provider component schema name, without a JSON Pointer prefix. This is provenance metadata, not a schema lookup or validation step.
How unreviewed members are handled. “forbid” always rejects them. “configurable” rejects them unless validation explicitly allows unknown content fields, which is reserved for trusted configuration. Members listed in opaque are reviewed.
Optional discriminator and selection cardinality when this model is a branch of a guarded heterogeneous array.
Reject values the exported contract format cannot represent.
Bases: BaseModel
Require declared fields to carry guard policy metadata.
Combine this base with the appropriate runtime projection base. At subclass creation it checks field classifications, opaque inventory overlap, disabled field defaults, and unsupported aliases. At validation it enforces the object’s unknown-field policy. It does not prove upstream field coverage or serialize arbitrary custom validators into the exported schema.
Attach policy using model identity, independent of schema display titles.
Keep Pydantic’s references and validation assertions. Object closure describes default validation; trusted overrides and case-alias checks remain explicit guard annotations.
Check local policy consistency after Pydantic has assembled fields.
Keep parsed variant selection consistent with the original payload.
Reject members outside the reviewed fields unless policy allows them.
A case variant of a reviewed name, such as Tools, is always
rejected: some providers match member names case-insensitively, so it
could reach a field this policy disables or inspects.
Require a structured reason such as core_capability.tool_content.
Build Annotated field metadata while keeping defaults in assignments.
Mark a field restricted by its type and optional Pydantic constraints.
The optional reason explains the restriction in the exported contract. This helper adds no restriction by itself; the annotation and constraints must express it. Defaults belong on the field assignment.
Declare an unsupported feature as an omittable, null-only field.
Use field: Annotated[None, disabled(reason)] = None. Non-null values are rejected by the field type, and PolicyModel checks this declaration. A nonblank structured reason explains the restriction. Set extension for a locally recognized field outside the pinned provider schema.
Export a fresh, inline schema with object and field guard annotations.
This function does not validate the complete contract format, inspect an upstream provider schema, or capture arbitrary Python validator behavior. The operation exporter is responsible for format validation.
Parameters:
type[ PolicyModel ] — Trusted policy-annotated model to describe.
Exported root title; the class name remains model metadata.
Returns: dict[str, Any]
A payload schema, not a complete operation contract.
Raises:
ValueError: Nested models are not policy-annotated, names collide, references recurse, or an anyOf union cannot be safely converted.
Derive disjoint runtime field inventories from one object’s declarations.
Local extensions occupy a separate inventory even when their annotation is constrained. The opaque inventory includes declared opaque attributes and ObjectPolicy.opaque names. This does not check an upstream schema.
Read a field’s guard metadata, returning an empty mapping if absent.
The returned mapping may belong to the field; callers must not mutate it.
Mark guarded content or a container leading to guarded content.
Use inside Annotated and put defaults on the field assignment. Declaring replacement eligibility does not enable runtime replacement support.
Parameters:
Text subject role. Omit for structural container fields.
Whether the subject permits replacement. The buffered binding defaults to read-only when this is not declared.
Sibling field whose non-empty value prevents replacement.
Structured reason for the replacement restriction.
min_length, max_length, pattern, ge, le, or strict. Format support is checked separately when exporting a complete guard contract; strictness has no JSON Schema keyword.
Resolve the one text-bearing branch of a reviewed object union.
Every branch must declare a mutually exclusive discriminator. The selected branch has bounded cardinality; other branches must not hide guarded text. Return None for a non-union item, whose ordinary array bounds apply instead. No JSON Schema generation or provider lookup participates in binding.
Collect the root and nested policy models in traversal order.
Models are keyed by class name. Reject nested models without policy and distinct models sharing a name. Repeated references are visited once; recursive schema export is rejected separately.
Mark a declared field as provider-owned data outside guarded content.
Use field: Annotated[Any, opaque()] = None for an unconstrained optional value. ObjectPolicy.opaque is the alternative for reviewed fields that do not need a model attribute. Do not declare the same field in both places.
Build runtime coverage metadata for a request or response projection.
Parameters:
type[ PolicyModel ] — Policy-annotated root, with policy-annotated nested models.
Stable identifier for this payload projection.
Whether the projection describes a request or response.
PayloadCapabilityProfile — Framework-defined capability implemented by the runtime.
Returns: PayloadProjectionContract
Root and nested-model coverage, ready to attach in a binding module.
Describe default object validation without the contract’s union restrictions.
Add reviewed opaque properties, default closure, and explicit object policy to the root and nested model definitions. Inline references so the schema can be embedded in an OpenAPI document without dangling definition paths; retain union semantics. Recursive models cannot be inlined and are rejected. The result is fresh; arbitrary Python validators are not serialized.
Return a subject’s replacement blocker after checking it names a reviewed sibling.
A misspelled blocker would never match a provider member and would silently allow replacement, so buffered and stream subjects both validate it.
Raises:
ValueError: The blocker is not a declared or reviewed opaque field of the model.
Derive one buffered text target directly from typed field declarations.
Follow guarded models and exactly-one-item lists without schema generation or contract-format conversion. Heterogeneous arrays use ObjectPolicy.variant to select exactly one text-bearing member. A nullable subject, or one without a minimum length, may hold no text.
Raises:
ValueError: A subject is missing or ambiguous, a guarded container is unsupported, or a replacement blocker is not a reviewed sibling.