Skip to navigation

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:

ArtifactPurpose
Gateway manifest or Python application configSelect upstreams, operations, dialects, and Rails configurations.
Rails configurationDefine the checks that run on selected content.
Guard contractReview the bound operation’s content coverage and declared stream behavior.

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:

ClassificationMeaningExample
GuardedContent selected for checks, or a container leading to that content.A user message’s text.
ConstrainedA value or shape restricted for supported behavior or integrity.A role fixed to user, or a choice index fixed to zero.
OpaqueA reviewed field left under provider authority without inspection of its value or nested contents.Usage accounting or a model identifier.

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:

minLength: 1
type: string
x-nemo-guardrails:
classification: guarded
subject:
kind: text
replaceable: true
role: user

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:

x-nemo-guardrails:
classification: opaque

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:

SectionDescribes
version, operationId, profileDocument format, provider operation, and payload capability.
request, responsePayload shapes and their field policies.
streamBound event payloads, selection roles, missing-text behavior, and framing declarations.
excluded_stream_eventsExplicit exclusions recorded by the binding.
integration.endpointEndpoint identity, routes, errors, and descriptive implementation references.

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:

Event roleMeaning
guarded_deltaText deltas selected for output checks.
snapshotText snapshots checked for consistency with the accumulated deltas.
opaqueReviewed metadata whose values are not inspected as text.
provider_errorA recognized provider error event.

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:

python -m nemoguardrails.server.experimental.provider.contract_export \
nemoguardrails.server.experimental.providers.openai.chat_completions.endpoint:CHAT_COMPLETIONS_ENDPOINT \
--output chat.guard.yaml

Check for drift without modifying the file:

python -m nemoguardrails.server.experimental.provider.contract_export \
nemoguardrails.server.experimental.providers.openai.chat_completions.endpoint:CHAT_COMPLETIONS_ENDPOINT \
--check chat.guard.yaml

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.