feat(server): declare private transparent proxy contracts

[Pouyanpi]

Description

Phase A establishes the private provider-neutral foundations for transparent provider proxying. It separates content checking from provider payloads and HTTP behavior before any provider integration is added.

This PR introduces the small private contracts used to check content while transparently proxying provider requests and responses.

It defines:

• the provider-neutral GuardedMessage value without exposing a provider API;
• input and output check inputs that preserve effective input context;
• allow, block, and checker-failure decisions;
• one statically bound checker with its inspection settings captured once;
• buffered guarded-operation declarations with validated names and projections;
• fail-closed validation for invalid checkers, unknown decisions, and requested content modification;
• fresh-interpreter import tests for the new private modules.

Why these private interfaces exist

• ContentChecker is a dependency-inversion boundary. Transparent proxy execution depends on this small protocol instead of importing the existing Guardrails checking APIs, which do not yet model all proxy requirements and may continue to evolve. An adapter can follow those changes without forcing them through provider parsing, proxy ordering, and HTTP forwarding.
• ContentInspectionPolicy is not a Rails configuration. A Rails configuration describes guardrail behavior. This type is only the validated runtime snapshot of whether one checker instance examines input, output, or both.
• GuardedMessageProjection lets a provider select content for checking without moving provider payload types into the checker contract.
• BufferedGuardedOperation gives each internal operation a stable identity and its two provider-owned projections without deciding HTTP routing or provider composition.

Stable and temporary parts

The private checker dependency direction and provider-neutral message, check-input, and decision shapes are intended to remain.

The deliberately narrow parts are:

• one checker is bound statically for all requests in this PR; application integration later resolves a checker from trusted request context;
• ContentInspectionPolicy currently captures only input and output checks; streaming adds its own inspection requirements without exposing provider events to the checker;
• projections currently return the message to inspect; provider integration retains the parsed payload and exact provider target around that message;
• replacement remains rejected until buffered exact-target mutation and HTTP rewrite integrity are available.

InvalidContentChecker validates the structural protocol. UnsupportedContentCheckerConfiguration separately represents a valid checker configuration that the proxy cannot execute.

Review focus

• Does ContentChecker invert the dependency on evolving Guardrails checking APIs without becoming a public abstraction?
• Is the distinction between Rails configuration and captured inspection settings clear?
• Is it clear which declarations are stable and which static assumptions are temporary?
• Do invalid checkers and decisions fail closed?
• Is requested content modification unambiguously unsupported?
• Do these declarations remain independent of FastAPI, HTTPX, providers, configuration resolution, and streaming?

Non-goals

• HTTP routing or forwarding;
• provider payload models or contracts;
• streaming;
• Rails configuration resolution;
• safe replacement;
• a public provider-extension API.

Phase A stack

Review every PR against its parent branch rather than against develop, except for PR 1.

Order	PR	Branch	Base
1	#2404	pouyanpi/transparent-proxy-kernel-1	develop
2	#2405	pouyanpi/transparent-proxy-buffered-kernel-2	pouyanpi/transparent-proxy-kernel-1
3	#2406	pouyanpi/transparent-proxy-http-kernel-3	pouyanpi/transparent-proxy-buffered-kernel-2
4	#2407	pouyanpi/transparent-proxy-projection-outcomes-4	pouyanpi/transparent-proxy-http-kernel-3

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change.

Checklist

• I've read the CONTRIBUTING guidelines.
• This is maintainer-led work tracked internally.
• The PR title follows the project commit convention.
• Public documentation is not applicable to this private declaration-only change.
• Tests cover the introduced behavior.
• Verification and checks not run are documented.
• Generated changelog files were not edited manually.
• All automated and human review comments are addressed or answered.
• The responsible reviewer or team is mentioned.

[codecov]

Codecov Report

❌ Patch coverage is 93.06931% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...guardrails/server/experimental/_content_checker.py	89.70%	7 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

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: dae657c4-385f-4176-89a1-f033e60fe503

📥 Commits

Reviewing files that changed from the base of the PR and between e549dda and a46e449.

📒 Files selected for processing (8)

• nemoguardrails/server/experimental/__init__.py
• nemoguardrails/server/experimental/_content_checker.py
• nemoguardrails/server/experimental/_guarded_operation.py
• nemoguardrails/server/experimental/provider/__init__.py
• nemoguardrails/server/experimental/provider/types.py
• tests/server/experimental/test_content_checker.py
• tests/server/experimental/test_guarded_operation.py
• tests/server/experimental/test_import_boundaries.py

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

---

📝 Walkthrough

Walkthrough

The experimental server package adds guarded-message and buffered-operation declarations. It also adds content-checker data types, a protocol, validation functions, and tests for these contracts and package imports.

Changes

Guard contracts

Layer / File(s)	Summary
Guarded messages and operation projections nemoguardrails/server/experimental/provider/types.py, nemoguardrails/server/experimental/_guarded_operation.py, tests/server/experimental/test_guarded_operation.py, nemoguardrails/server/experimental/__init__.py, nemoguardrails/server/experimental/provider/__init__.py, tests/server/experimental/test_import_boundaries.py	Adds a frozen GuardedMessage type and a generic BufferedGuardedOperation descriptor. The descriptor validates dotted operation names and callable projections. Tests cover projections, validation errors, and imports in fresh interpreters.
Content-checker decisions and validation nemoguardrails/server/experimental/_content_checker.py, tests/server/experimental/test_content_checker.py	Adds checker policies, input and output check payloads, decision types, a checker protocol, and validation functions. Tests cover checker and policy validation, supported decisions, and rejection of content replacement.

Priority: ⬇️ Low

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

Change: Feature

Merge Risk: ⚪ Minimal · up to a46e4

No actionable issue is established for this PR’s private contracts; it is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 8 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	The PR contains major changes: it adds 522 lines across new server contracts and three test modules. The description includes testing information, including fresh-interpreter import tests and contract…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding private server contracts for transparent proxy content checking.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

[greptile-apps]

Confidence Score: 5/5

[Low risk] Adds new private type declarations and tests.

The PR appears safe to merge; no outstanding finding or new actionable issue was identified.

Summary

The PR declares private, provider-neutral contracts for content checking and buffered guarded operations.

• Adds runtime validation for guarded-message roles and text content.
• Adds contract and fresh-interpreter import tests.

_{Reviews (2) · Last reviewed commit: "test(server): raise unsupported checker ..."}

[tgasser-nv]

Looks good, can you are you address the following before merging:

1. The directory is named experimental. When this changes from to the default, you'll have to move files around as it becomes the default rather than experimental. Recommend picking a directory that describes the operation instead (maybe just proxy?). This will churn every PR in the stack so you could move/rename as a new PR at the end
2. Could you add tests to get patch coverage up to 100%?
3. Can you take a look at Mac's (@m-misiura ) comments?