Understand Guard Contracts
A guard contract makes an integration’s inspection boundary visible. It answers which content reaches checks, which shapes are restricted, and which fields remain provider-owned metadata. Use it to review coverage or evaluate a provider change without reconstructing the boundary from implementation details.
Three Different Configurations
Use these artifacts for distinct configuration and review tasks:
Typed Python projections, bindings, and endpoint declarations are authoritative. The contract is exported from those bound declarations. The running gateway does not load it to create policy, and changing the YAML does not change execution.
Read the Field Policy
The contract classifies fields by how the binding handles them:
Disabled features are represented by constraints, often a null-only field with
gate: disabled. Required presence, nullability, and replacement eligibility
are separate declarations. Opaque means uninspected; it does not mean safe.
For example, this is the current Chat export’s
request.properties.messages.items.properties.content declaration:
It identifies the text and role used for checking. replaceable: true records
subject eligibility, not a promise that the endpoint executes replacement
outcomes. The current built-in integrations reject unsupported modifications.
The current request’s model declaration illustrates opaque metadata:
These are excerpts from an exported binding, not a complete editable contract.
Inspect a Contract
Browse the generated native Chat Completions contract or Responses contract. Each page has request, response, and stream sections plus the exact export from that build’s bound Python declarations. Nested objects and schema alternatives remain separate.
The package includes bound exports for native Chat, native Responses, LiteLLM Chat, and LiteLLM Responses.
Each export includes the following sections:
Read these versions separately: the format revision identifies the document format, the provider revision identifies its source baseline, and the capability profile identifies supported content handling. Rails selects the checks.
Read Stream Declarations
The stream section records the classifier’s reviewed event shapes:
Each variant records its matching fields and shape. Missing-text behavior is a separate rule from nullability; transport declarations describe discriminators, sentinels, and non-data events. These declarations do not serialize stateful completion checks or native error encoding. Read completion and errors for runtime behavior and failures after HTTP 200.
Export From an Endpoint
From the repository root, export the actual bound endpoint:
Check for drift without modifying the file:
Use nemoguardrails.server.experimental.providers.openai.responses.endpoint:RESPONSES_ENDPOINT
for Responses. With neither destination option, the command writes YAML to
standard output. The endpoint reference imports Python, so use only trusted
local declarations.
The CLI validates the exported format. It rejects declarations it cannot represent faithfully, such as unsupported custom stream validators, rather than silently omitting them. Runtime bindings can have behavior beyond the standard export format.
Review a Change
Compare the request and response fields and stream declarations with the previous export. Pay particular attention to new opaque fields: their values bypass text inspection.
The export describes declared field policies and stream events. Stateful stream hooks, custom Python validation, transport behavior, and cleanup remain in code. Generic JSON Schema tools also omit guard-specific semantics; the format reference records the exact limitations.
When coverage changes, update the Python declarations and regenerate the contract from the endpoint. The policy customization walkthrough shows request restrictions, buffered and streaming metadata extensions, and export from the customized endpoint.