feat(server): add OpenAI Chat stream projections and hooks

[Pouyanpi]

Summary

Declares OpenAI Chat stream policy in typed Python models, derives classification metadata, and supplies handwritten completion hooks and native error framing.

What Changed

• Adds typed payload and provider-error models, with explicit guarded-delta, metadata, and terminal-event classification rules.
• Derives reviewed-field coverage and guarded text paths through reusable stream-policy helpers; replacement blockers on stream subjects are validated like buffered ones.
• Keeps unknown choice and delta fields closed, accepts null or empty tool_calls, and requires the choice index to be exactly the integer 0.
• Field helpers now accept ge, le, and strict alongside length and pattern, so exact integers need no custom validator. Export checks separately whether the contract can carry a constraint.
• Gives data-less keepalives their own keepalive shape and drops unused classifier aliases.
• Requires [DONE] for successful completion and rejects duplicate termination or later payloads. Data-less keepalives and provider-error endings remain supported.
• Tests the Python declarations, derived classification metadata, event inventory, transport policy, and handwritten hooks without loading an authored YAML contract.

Review Notes

Review the typed policy, derived coverage and text paths, event inventory, strict JSON, and handwritten completion/error hooks. Endpoint/HTTP integration lands in the final PR.

With output inspection enabled, missing completion produces a native stream error and withholds pending text. Previously approved bytes already sent cannot be retracted. Provider errors can end the stream without [DONE]; the proxy preserves that failure without adding a missing-completion error.

AI Assistance

• No AI tools were used.
• AI tools were used (Codex and Claude Code assisted with implementation, regression tests, review probes, and PR drafting). Human review of the new diff is pending.

Checklist

• I've read the CONTRIBUTING guidelines.
• This is maintainer-directed work.
• The PR title follows the project commit convention.
• Applicable declarations and tests are included.
• Generated changelog files were not edited manually.
• Automated and human review comments are addressed or answered.
• The responsible reviewer or team is mentioned.

Stack Position

Part 2 of 4.

• Previous: feat(server): execute guarded provider streams #2434
• Next: feat(server): bind guarded streams to HTTP #2436

Stack Context

Adds OpenAI Chat streaming above the merged buffered implementation on develop in four parts: provider-neutral execution, typed OpenAI stream declarations and handwritten hooks, injected HTTP lifecycle handling, and integration with the buffered request pipeline.

The open chain is develop → #2434 → #2435 → #2436 → #2437. The buffered foundation is merged; #2412 is closed.

Python declarations own field and event policy. Hooks are handwritten and created for each stream by the integration. The final PR exports the bound buffered and streaming policy for inspection; export never constructs runtime components. Concrete outbound HTTP, deployment configuration, and replacement execution land separately.

Review each PR against its listed base branch.

Order	PR	Branch	Base
1	#2434	pouyanpi/transparent-proxy-streaming-kernel-1	develop
2	#2435	pouyanpi/openai-chat-streaming-contract-2	pouyanpi/transparent-proxy-streaming-kernel-1
3	#2436	pouyanpi/transparent-proxy-streaming-http-3	pouyanpi/openai-chat-streaming-contract-2
4	#2437	pouyanpi/openai-chat-streaming-integration-4	pouyanpi/transparent-proxy-streaming-http-3

Summary by CodeRabbit

• New Features
  • Added streaming support for OpenAI Chat Completions, including guarded text chunks, provider error events, and stream termination handling.
  • Added validation for stream payload shapes and terminal events, with errors formatted as OpenAI-style events.
• Documentation
  • Updated the streaming policy documentation to describe supported declarations and validation limits.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge in the reviewed stack, with numeric contract export support completed by PR #2437.

Summary

Adds typed OpenAI Chat stream models, derived field and event coverage, and handwritten completion hooks.

• OpenAI Chat stream events have clear rules for text, metadata, and errors.
• Typed stream bindings derive text paths and event coverage from their declarations.
• Chat streams distinguish successful endings from provider errors.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Provider SSE event] --> B{Data present?}
  B -- No --> C[Keepalive]
  B -- Yes --> D{DONE marker?}
  D -- Yes --> E[Mark completion]
  D -- No --> F[Select and validate event model]
  F --> G{Event kind}
  G -- Text --> H[Extract original guarded text]
  G -- Metadata --> I[Keep reviewed metadata]
  G -- Error --> J[Mark provider failure]
  H --> K[Run output checks before release]
  C --> L[Check stream history]
  E --> L
  I --> L
  J --> L
  L --> M[Require DONE or provider failure at stream end]

Loading

_{Reviews (9) · Last reviewed commit: "test(server): cover typed stream policy ..." · Reviewed by Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 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: 3f8ad0e2-4192-4f5c-afb9-014efdad019f

---

📥 Commits

Reviewing files that changed from the base of the PR and between cb9fb48 and 969832f.

---

📒 Files selected for processing (8)

• nemoguardrails/server/experimental/provider/stream_classifier.py
• nemoguardrails/server/experimental/provider/stream_policy.py
• nemoguardrails/server/experimental/providers/openai/chat_completions/README.md
• nemoguardrails/server/experimental/providers/openai/chat_completions/stream_classifier.py
• nemoguardrails/server/experimental/providers/openai/chat_completions/stream_hooks.py
• nemoguardrails/server/experimental/providers/openai/chat_completions/stream_projection.py
• tests/server/experimental/test_openai_chat_streaming_projections.py
• tests/server/experimental/test_stream_policy.py

---

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

---

---

📝 Walkthrough

Walkthrough

The changes add shared stream-policy helpers and an OpenAI Chat Completions streaming policy. The new policy defines payload and error projections, classifies stream events, and tracks terminal events and provider errors. Tests cover policy derivation, classification, and stream handling.

Changes

Chat Completions streaming

Layer / File(s)	Summary
Shared stream policy nemoguardrails/server/experimental/provider/stream_policy.py, tests/server/experimental/test_stream_policy.py	Adds guarded text-path derivation and event-shape coverage. Tests check supported and rejected schemas, role conflicts, and classifier contract consistency.
OpenAI stream projection and classification nemoguardrails/server/experimental/providers/openai/chat_completions/stream_projection.py, nemoguardrails/server/experimental/providers/openai/chat_completions/stream_classifier.py, nemoguardrails/server/experimental/provider/stream_classifier.py, nemoguardrails/server/experimental/providers/openai/chat_completions/README.md, tests/server/experimental/test_openai_chat_streaming_projections.py	Adds OpenAI payload and error projection models, stream event rules, derived coverage, and a classifier. The README documents the declarations and their limits. Tests check schemas, event classification, and declaration metadata. The shared classifier module’s documentation now describes declarative rules.
Stream lifecycle handling nemoguardrails/server/experimental/providers/openai/chat_completions/stream_hooks.py, tests/server/experimental/test_openai_chat_streaming_projections.py	Adds hooks that track [DONE] and provider errors, reject disallowed events after termination, validate stream completion, and encode provider errors. Tests cover hook state and guarded-stream handling.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

---

Merge Risk: ⚪ Minimal · up to 96983

No identified streaming-policy defect remains to resolve before merging this PR.

Pre-merge checks | 5 | 1

❌ Failed checks (1 warning)

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

✅ Passed checks (5 passed)

Check name	Status	Explanation
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 contains major changes, including new stream policy, projection, classifier, and hook code. The description includes specific testing information: it lists coverage for declarations, derived me…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main changes: OpenAI Chat stream projections and hooks.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 18.37% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 49 functions across 7 files. (1 skipped: 1 unsupported.)

---

• 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.}

[tgasser-nv]

Looks good! Can you add some more test coverage for the missing lines before merging?