feat(server): add OpenAI Chat buffered projections

nemoguardrails/server/experimental/_json_payload.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from nemoguardrails.server.experimental.provider.types import JsonObject
+
+
+class InvalidJson(ValueError):
+    """Report a payload that is not standards-compliant JSON."""
+
+
+class UnsupportedJsonShape(ValueError):
+    """Report valid JSON that cannot be handled without ambiguity."""
+
+
+def _unique_object(pairs: Sequence[tuple[str, Any]]) -> JsonObject:
+    """Build an object while rejecting duplicate member names.
+
+    Names that differ only by case are left to the projection models, which
+    close every reviewed object. Opaque provider data may legitimately use
+    such names.
+    """
+    result: JsonObject = {}
+    for key, value in pairs:
+        if key in result:
+            raise UnsupportedJsonShape(f"Duplicate JSON member {key!r} is not supported.")
+        result[key] = value
+    return result
+
+
+def _reject_nonstandard_number(value: str):
+    """Reject JSON constants that are not part of the standard grammar."""
+    raise InvalidJson(f"Non-standard JSON number {value!r} is not supported.")
+
+
+def _parse_finite_float(value: str) -> float:
+    """Parse a JSON float only when it has a finite value."""
+    parsed = float(value)
+    if not math.isfinite(parsed):
+        raise InvalidJson(f"Non-finite JSON number {value!r} is not supported.")
+    return parsed
+
+
+def _parse_integer(value: str) -> int:
+    """Parse an integer while normalizing interpreter size-limit failures."""
+    try:
+        return int(value)
+    except ValueError as error:
+        raise InvalidJson("The JSON integer exceeds the supported size.") from error
+
+
+def parse_json_object(body: bytes) -> JsonObject:
+    """Parse a JSON object without accepting ambiguous or nonstandard input."""
+
+    if not isinstance(body, bytes):
+        raise TypeError("A provider JSON body must be bytes.")
+    try:
+        payload = json.loads(
+            body,
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_nonstandard_number,
+            parse_float=_parse_finite_float,
+            parse_int=_parse_integer,
+        )
+    except UnsupportedJsonShape:
+        raise
+    except (UnicodeDecodeError, json.JSONDecodeError, RecursionError, InvalidJson) as error:
+        raise InvalidJson("The payload must be valid JSON.") from error
+    if not isinstance(payload, dict):
+        raise UnsupportedJsonShape("The JSON payload must be an object.")
+    return payload
+
+
+def encode_json_object(payload: Mapping[str, Any]) -> bytes:
+    """Serialize a modified provider object as compact UTF-8 JSON."""
+
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode()

nemoguardrails/server/experimental/contracts/README.md

@@ -42,11 +42,13 @@ allowed, but every other key starting with `x-nemo` is reserved and rejected.
 | `classification: constrained` | Restricts a value or shape without making it a rail subject. |
 | `gate: disabled` | Marks a constrained, null-only field for an unsupported feature. |
 | `classification: opaque` | Leaves the value under provider authority, without guardrail inspection. |
-| `opaque_fields` | Lists reviewed opaque names on this object without declaring each property. |
+| `opaque_fields` | Legacy object-level inventory; canonical exports use opaque-classified properties. |
 | `reason` | Explains a restriction: capability, provider integrity, or projection policy. |
 
 Opaque does not mean safe or trusted. Its nested content is not independently
-reviewed. Opaque names should not overlap declared properties or use wildcards.
+reviewed. Canonical exports declare each reviewed opaque name in `properties`.
+A legacy `opaque_fields` inventory must not overlap declared properties or use
+wildcards.
 `extension: true` identifies a local compatibility field outside the pinned
 provider schema, not an exemption from review.
 
@@ -65,8 +67,18 @@ enables a detector or a runtime capability.
 
 `model` identifies the Python model; `source` identifies a provider schema
 component. `unknown_fields: configurable` marks an object whose unknown-field
-handling depends on runtime validation context. Generic JSON Schema validators
-do not enforce this annotation. `additionalProperties` remains the ordinary
+handling depends on runtime validation context. Validation rejects unknown
+members by default; only trusted configuration may allow them on such an object.
+Objects without the marker always reject them. Generic JSON Schema validators
+do not enforce this annotation. Reviewed opaque names appear as properties
+classified `opaque`, so `additionalProperties` describes only unreviewed members.
+
+A member whose name matches a listed property only after Unicode case folding
+(`casefold()`), such as `Tools` beside `tools`, is always rejected, even where
+unknown members are allowed: some providers match names case-insensitively.
+Whitespace remains part of the name. JSON Schema could state this with
+`propertyNames`, but the contract vocabulary does not include it, so runtimes
+and generators must implement the rule themselves. `additionalProperties` remains the ordinary
 schema-level object closure rule. Provider-required opaque fields may be left
 to provider validation; a projection is not a full provider request validator.
 
@@ -105,3 +117,7 @@ choose deployment rails or enable runtime profile selection.
 This is a NeMo Guardrails document using JSON Schema vocabulary, not an OpenAPI
 document or an OpenAPI Overlay. Generic schema tools do not execute its guardrail
 annotations.
+
+## Provider boundaries
+
+- [OpenAI Chat Completions](openai/README.md)

nemoguardrails/server/experimental/contracts/openai/README.md

@@ -0,0 +1,54 @@
+# OpenAI Chat Completions contract
+
+Operation `createChatCompletion` uses the `single_text.v1` capability profile
+for its guarded text boundary. This page summarizes that boundary and its
+provider source. Neither the summary nor the source pin enables runtime
+behavior. See [Guard contracts](../README.md) for the document vocabulary.
+
+## Guarded boundary
+
+| Area | Single-text boundary |
+| --- | --- |
+| Request | One user message with non-empty string content at `messages[0].content`. |
+| Buffered response | One assistant choice with string content at `choices[0].message.content`. Empty or null content means the response has nothing to inspect, because every other reviewed field is content-free. The projection reports this through `has_text`; relaying such a response without output checks is left to the integration. |
+| Constrained values | User/assistant roles, single-item arrays, and request `n` constrained to one. |
+| Unsupported content | Tool, audio, multimodal, refusal, participant name, and separate reasoning content where explicitly disabled. |
+| Opaque data | Reviewed provider-owned metadata and controls, not additional guarded subjects. |
+| Closed objects | The request, its user message, the buffered response, and its choice and assistant message reject members outside OpenAI's fields. The user message, choice, and assistant message are configurable: only trusted configuration may allow unknown members there. Fields specific to compatible servers belong to their own reviewed extensions. |
+
+This request boundary does not accept conversation histories, system/developer
+messages alongside the user message, or multimodal content blocks. Disabled
+fields are null-only: a non-null value does not become acceptable merely because
+it requests plain text or no tools. A few unsupported features are constrained
+instead, because OpenAI's schema also allows a value that carries no content:
+response `tool_calls` and `annotations` accept null or an empty list, and
+request `logprobs` accepts null or `false`.
+
+Log probabilities are unsupported: they carry token text that rails do not
+inspect. Request `logprobs` accepts only `false` or null, request `top_logprobs`
+accepts only null, and buffered response `choices[0].logprobs` accepts only null.
+The request check applies even when output inspection is off.
+
+Text replacement eligibility is separate from endpoint support for replacement
+outcomes. Response annotations must be null or empty, because citation text is
+not inspected. The policy still declares that non-empty annotations would block
+text replacement. Unrelated provider data must remain intact.
+
+The Python projections, bindings, and endpoint determine exact acceptance and
+runtime behavior. Their machine-readable contract belongs with the integration,
+not in a separately maintained handwritten policy here. Recognizing the request
+`stream` flag does not itself provide a streaming endpoint. Streaming needs its
+own event classification, lifecycle handling, and implementation tests; the
+buffered boundary is not a claim about accepted stream events.
+
+## Provider provenance
+
+[source.yaml](source.yaml) records the OpenAPI document's immutable revision,
+document version, download location, and expected SHA-256 digest. The pin is a
+review baseline, not a claim to cover every current OpenAI field or compatible
+provider.
+
+The offline metadata tests check pin structure and URL/revision consistency.
+They do not fetch the document or verify its bytes against the digest. Reviewing
+a provider update requires checking the source artifact and changes to guarded,
+constrained, disabled, and opaque fields separately from format validation.

nemoguardrails/server/experimental/contracts/openai/source.yaml

@@ -0,0 +1,5 @@
+document_url: https://github.com/openai/openai-openapi/blob/df63773f69f542ef875b9f00c3837c25ba5f4f2a/openapi.yaml
+download_url: https://raw.githubusercontent.com/openai/openai-openapi/df63773f69f542ef875b9f00c3837c25ba5f4f2a/openapi.yaml
+revision: df63773f69f542ef875b9f00c3837c25ba5f4f2a
+document_version: 2.3.0
+sha256: f2dae1a9aced09b91310db89edda51bf1e36ecbfb05230c3a50b239c07708469