[Pouyanpi]

Description

Add buffered and streaming OpenAI Responses support to the experimental transparent proxy. Typed Python declarations define the guarded content and reviewed metadata; the existing HTTP transport, streaming kernel, and application assembly execute them.

What changes

• Declare the request, response, and SSE event policies, derive text locations from typed array variants, and export the bound endpoint as an inspection-only guard contract.
• Recognize native response metadata, including store, access_programs, billing, frequency_penalty, presence_penalty, and tool_usage, in buffered responses and streaming lifecycle snapshots.
• Apply output checks to text deltas and verify repeated text snapshots. Handwritten hooks handle native completion, supplied identity/sequence checks, and Responses error framing.
• Add create_openai_integration selection for Chat Completions, Responses, or both. Keep create_openai_chat_integration Chat-only.
• Add four native OpenAI recordings covering buffered/streaming success and provider HTTP errors. Offline replay checks exact interaction counts, inspected text, preserved sanitized bytes, response relay, and output blocking, including later windows and overlapping context.
• Cover typed policy, export parity, protocol rejection, and application composition with offline regex Rails and HTTPX ownership checks.

Supported boundary

The guarded path supports one nonempty string input, foreground execution, and one assistant text output with reviewed reasoning metadata. Input arrays, additional plaintext context/history, tools, plaintext reasoning summaries, citations, token logprobs, and replacement remain unsupported.

Guarded-request restrictions apply even when inspection is disabled. With output inspection enabled, unsupported response shapes and events fail closed. Disabled output inspection retains raw response relay. Forwarded payloads and SSE bytes are not reconstructed from projection models.

Opaque metadata is preserved without inspection. The hooks are not a complete provider schema or lifecycle validator. Recordings establish compatibility with the captured native profile and sanitized replay representation, not original network chunking, socket delivery, every OpenAI-compatible backend, or complete interrupted-cleanup safety.

Checklist

• Adds tests and updates the relevant documentation.
• Uses signed-off commits and follows the project commit convention.
• Does not manually update generated changelog files.
• Human review and review-comment resolution are complete.

Summary by CodeRabbit

• New Features

  • Added experimental support for OpenAI Responses through the guarded proxy, including request validation, response filtering, streaming, lifecycle handling, and provider error reporting.
  • OpenAI integrations can now enable Chat Completions, Responses, or both operations.
  • Added support for validating heterogeneous response arrays and selecting bounded assistant message variants.

• Bug Fixes

  • Improved stream validation to reject malformed sequences, incomplete terminal states, ambiguous output, and unsupported content.

• Documentation

  • Added comprehensive OpenAI Responses setup, contract, streaming, and policy documentation.

[codecov]

Codecov Report

❌ Patch coverage is 98.75389% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../server/experimental/provider/projection_policy.py	95.00%	3 Missing ⚠️
...ails/server/experimental/provider/stream_policy.py	87.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA-NeMo/Guardrails/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 353e4903-608b-43c2-bd1b-284ba0f19ea7

📥 Commits

Reviewing files that changed from the base of the PR and between 6b13f18 and 15ab8a9.

⛔ Files ignored due to path filters: 1

• nemoguardrails/server/experimental/contracts/openai/_generated/responses.guard.yaml is excluded by !**/_generated/**

📒 Files selected for processing: 24

• nemoguardrails/server/experimental/contracts/README.md
• nemoguardrails/server/experimental/contracts/openai/README.md
• nemoguardrails/server/experimental/provider/projection_policy.py
• nemoguardrails/server/experimental/provider/stream_policy.py
• nemoguardrails/server/experimental/providers/openai/chat_completions/README.md
• nemoguardrails/server/experimental/providers/openai/errors.py
• nemoguardrails/server/experimental/providers/openai/integration.py
• nemoguardrails/server/experimental/providers/openai/responses/README.md
• nemoguardrails/server/experimental/providers/openai/responses/__init__.py
• nemoguardrails/server/experimental/providers/openai/responses/endpoint.py
• nemoguardrails/server/experimental/providers/openai/responses/request_binding.py
• nemoguardrails/server/experimental/providers/openai/responses/request_projection.py
• nemoguardrails/server/experimental/providers/openai/responses/response_binding.py
• nemoguardrails/server/experimental/providers/openai/responses/response_projection.py
• nemoguardrails/server/experimental/providers/openai/responses/stream_classifier.py
• nemoguardrails/server/experimental/providers/openai/responses/stream_hooks.py
• nemoguardrails/server/experimental/providers/openai/responses/stream_projection.py
• tests/server/experimental/conftest.py
• tests/server/experimental/test_openai_responses_contract_export.py
• tests/server/experimental/test_openai_responses_integration.py
• tests/server/experimental/test_openai_responses_projections.py
• tests/server/experimental/test_openai_responses_streaming_integration.py
• tests/server/experimental/test_openai_responses_streaming_projections.py
• tests/server/experimental/test_projection_variants.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

📝 Walkthrough

This change adds an experimental OpenAI Responses endpoint with guarded request, response, and streaming policies. It adds operation selection for OpenAI integrations and extends projection policies to select guarded text from heterogeneous arrays using declared variants.

Changes: OpenAI Responses Guarded Integration

Layer / File(s)	Summary
Heterogeneous array variant policies nemoguardrails/server/experimental/provider/projection_policy.py, nemoguardrails/server/experimental/provider/stream_policy.py, tests/server/experimental/conftest.py, tests/server/experimental/test_projection_variants.py, nemoguardrails/server/experimental/contracts/README.md, nemoguardrails/server/experimental/providers/openai/chat_completions/README.md	Adds required literal-discriminator policies and cardinality rules for heterogeneous arrays. Buffered and streaming text-path derivation can select a declared variant. Schema export and tests cover variant constraints and selection.
Responses request and response projections nemoguardrails/server/experimental/providers/openai/responses/request_projection.py, request_binding.py, response_projection.py, response_binding.py, tests/server/experimental/test_openai_responses_projections.py	Adds guarded request and response contracts. Request validation restricts supported inputs and controls. Response validation requires one guarded assistant text message while preserving selected metadata.
Responses stream validation nemoguardrails/server/experimental/providers/openai/responses/stream_projection.py, stream_classifier.py, stream_hooks.py, tests/server/experimental/test_openai_responses_streaming_projections.py, tests/server/experimental/test_openai_responses_streaming_integration.py	Adds typed SSE event projections, text and metadata classification, and stream lifecycle checks. Tests cover event validation, terminal events, text blocking, error handling, and source cleanup.
Endpoint composition and operation selection nemoguardrails/server/experimental/providers/openai/responses/endpoint.py, nemoguardrails/server/experimental/providers/openai/integration.py, nemoguardrails/server/experimental/providers/openai/errors.py, tests/server/experimental/test_openai_responses_integration.py, tests/server/experimental/test_openai_responses_contract_export.py, nemoguardrails/server/experimental/contracts/openai/README.md, nemoguardrails/server/experimental/providers/openai/responses/README.md	Adds the Responses route and create_openai_integration, which selects one or both supported operations. Tests cover integration behavior and exported contracts. Documentation describes the endpoint, operation selection, and contract boundaries.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant GuardedProxy
  participant ResponsesEndpoint
  participant OpenAI
  participant StreamClassifier
  participant StreamHooks
  participant RailsChecker
  Client->>GuardedProxy: POST Responses request
  GuardedProxy->>ResponsesEndpoint: Route and validate request
  ResponsesEndpoint->>OpenAI: Forward accepted request
  OpenAI->>GuardedProxy: Stream SSE events
  GuardedProxy->>StreamClassifier: Classify events and extract guarded text
  StreamClassifier->>StreamHooks: Provide classified event
  GuardedProxy->>RailsChecker: Inspect guarded text
  GuardedProxy->>Client: Relay allowed stream bytes

Loading

Merge Risk: ⚪ Minimal · up to 15ab8

This change adds experimental, opt-in OpenAI Responses support to the transparent proxy. It accepts only a narrow reviewed profile and rejects unsupported request, response, or stream shapes. Existing Chat Completions behavior is preserved through the unchanged Chat-only factory. No concrete defects were identified, so the change appears ready to merge after normal checks.

Pre-merge checks: 5 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 31.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 93 functions across 20 files. (4 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 5 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: adding typed OpenAI Responses integration to the server.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes		The PR introduces a major OpenAI Responses feature, and the description documents testing information. It lists policy/export, buffered and streaming integration, HTTPX ownership, regex Rails, and Ope…

Full details: Test Results For Major Changes

Explanation

The PR introduces a major OpenAI Responses feature, and the description documents testing information. It lists policy/export, buffered and streaming integration, HTTPX ownership, regex Rails, and OpenAI SDK decoding tests. It also reports 1,599 experimental-suite tests, 730 affected offline tests, pre-commit validation, and a known existing shutdown-timeout failure. No numerics, convergence, or performance change is identified, so additional regression or performance numbers are not required.

Full details: Docstring Coverage

Explanation

Docstring coverage is 31.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 93 functions across 20 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge within its documented experimental boundary.

Summary

Adds typed OpenAI Responses support to the experimental proxy:

• The proxy inspects OpenAI Responses text in buffered and streaming replies.
• OpenAI integrations can guard Chat Completions, Responses, or both.

No new actionable issues were found. The previous dependent-contract issue is addressed by PR #2466, not this PR alone; that assessment depends on #2466. PR #2463 retains the fix.

Tests were not run during this review.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Responses request] --> B[Validate supported shape]
    B --> C[Check input]
    C --> D[Forward original request]
    D --> E{Response mode}
    E -->|Buffered| F[Select assistant text]
    E -->|Streaming| G[Collect deltas and verify snapshots]
    F --> H[Check output]
    G --> H
    H -->|Allowed| I[Release original bytes]
    H -->|Blocked| J[Return Responses error]

Loading

_{Reviews (14) · Last reviewed commit: "refactor(server): centralize validator f..." · Reviewed by Greptile}

[m-misiura]

thanks for all the modifications @Pouyanpi; I see no reasons not to LGTM now :)

[Pouyanpi]

Thanks @m-misiura, super helpful as always! 💪