[miyoungc]

Description

Generate the experimental Guardrails proxy API reference from the registered FastAPI routes for the built-in OpenAI provider. Export a deterministic example deployment without starting the proxy or contacting a provider, and generate the reference during documentation builds, previews, publishing, and historical snapshot preparation.

The new Chat Completions and Responses pages describe the proxy's guard boundary separately from upstream provider requirements. Policy labels distinguish guarded, constrained, disabled, and opaque fields; generated guard-contract pages retain request, response, and stream declarations. The reference includes examples, documented errors, deployment-specific URLs, and links to the existing proxy guides. Existing guide and API reference routes are preserved.

The hooks-server portion is separate in #2541. Both changes touch shared documentation generation code; whichever merges second will need to reconcile that integration. The proxy API Explorer (Try it) is hidden with x-fern-explorer: false until connection setup, CORS, and credential input are ready in the separate Try it follow-up (#2492).

Related Issue(s)

SDR-1839: Implement automated API reference generation for Guardrails hooks server and proxy, assigned to Miyoung Choi. The directing human confirmed SDR-1839 as the tracking issue for this contribution and explicitly authorized implementation and PR creation. This PR covers the proxy portion of that ticket.

Verification

Latest local validation for the Try it change:

• Pre-commit on fern/proxy-openapi-overlay.yml and git diff --check: passed.
• make docs-fern: 0 errors and 566 warnings. The warnings have not been compared with a fresh base build.
• Local Fern preview: both proxy endpoint pages returned HTTP 200 with no Try it button, retaining examples and guard-contract links. The main Guardrails API retained its existing Try it control.
• Structured review: no actionable findings.

Earlier validation on the initial implementation commit (c89b88a2e) passed 4 focused exporter tests and all 21 documentation-script tests, including Fern conversion, existing reference routes/examples, historical generation, and publish failure handling. That script-test run used a temporary file-descriptor limit of 4096 for the preview watcher.

CI has started again on the latest commit; current results are in the PR checks.

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change (tool: Codex).

Codex assisted with implementation, tests, documentation, rendered-output checks, and review. Human sign-off is pending.

Checklist

• I've read the CONTRIBUTING guidelines.
• This PR links to a triaged issue assigned to me.
• My PR title follows the project commit convention.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• I've noted any verification beyond CI and any checks I couldn't run.
• I did not update generated changelog files manually.
• I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed.
• @mentions of the person or team responsible for reviewing proposed changes.

Summary by CodeRabbit

• New Features

  • Added an Experimental Proxy API reference covering guarded chat-completion and Responses endpoints, with request and response examples.
  • Documented provider-native responses, possible upstream errors, and configuration-dependent inspection.

• Documentation

  • Added the proxy API to the API reference navigation, including displayed error information.

[github-actions]

Staged Fern docs preview: https://nvidia-preview-pr-2542.docs.buildwithfern.com/nemo/guardrails

[greptile-apps]

Confidence Score: 5/5

[Low impact] The latest changes appear safe to merge; no actionable new issue was found.

Summary

This PR generates the experimental proxy API reference and guard-contract pages from the bound Python declarations.

• The built-in OpenAI proxy routes have generated API and guard-contract reference pages.
• Docs generation now includes the proxy reference across builds, publishing, and snapshots.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Bound Python declarations] --> B[Proxy reference exporter]
  B --> C[OpenAPI specification]
  B --> D[Guard-contract pages]
  C --> E[Proxy documentation overlay]
  E --> F[Fern reference pages]
  D --> F

Loading

_{Reviews (4) · Last reviewed commit: "docs(proxy): hide Try it in generated re..." · Reviewed by Greptile}

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA-NeMo/Guardrails
• Branch: miyoungc/sdr-1839-proxy-api-reference
• File: .coderabbit.yaml
• Commit: c89b88a
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: b9bce9f0-0b78-4118-a272-06df1ef64882

Commits

Reviewing files that changed from the base of the PR and between 8d027fd and c89b88a.

Files selected for processing: 13

• .github/workflows/docs-build.yaml
• .github/workflows/guardrails-api-spec.yml
• .gitignore
• Makefile
• docs/index.yml
• fern/proxy-openapi-overlay.yml
• scripts/cache-fern-ref-sdk.mjs
• scripts/export_proxy_openapi.py
• scripts/tests/cache-fern-ref-sdk.test.mjs
• scripts/tests/docs-publish.test.mjs
• scripts/tests/proxy-openapi-reference.test.mjs
• scripts/watch-fern-preview.mjs
• tests/server/test_export_proxy_openapi.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

This change adds a script to export the built-in proxy’s OpenAPI specification, connects the export to the Fern generation and publishing workflows, and adds an experimental proxy API reference for chat completions and Responses.

Changes: Proxy OpenAPI reference

Layer / File(s)	Summary
Generate and validate the proxy specification scripts/export_proxy_openapi.py, tests/server/test_export_proxy_openapi.py	The new script generates the proxy OpenAPI schema, writes it to the default or specified path, and checks existing output for changes. Tests cover schema content, determinism, check mode, route prefixes, and example validation.
Integrate export into the Fern pipeline Makefile, scripts/cache-fern-ref-sdk.mjs, scripts/tests/cache-fern-ref-sdk.test.mjs, scripts/tests/docs-publish.test.mjs, .github/workflows/docs-build.yaml, .github/workflows/guardrails-api-spec.yml, .gitignore, scripts/watch-fern-preview.mjs	The build and publishing scripts run the proxy exporter. Workflow filters include proxy-related files, the API-spec workflow runs the exporter tests, and preview triggers ignore the generated specification.
Document the proxy API reference docs/index.yml, fern/proxy-openapi-overlay.yml, scripts/tests/proxy-openapi-reference.test.mjs, tests/server/test_export_proxy_openapi.py	The API navigation links the generated specification and overlay. The overlay documents chat-completions and Responses operations, with examples and route, streaming, and inspection details. Tests check generated reference content and validate overlay examples.

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

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant Makefile
  participant Exporter as export_proxy_openapi.py
  participant Spec as fern/proxy-openapi.yml
  participant Fern as Fern IR generation
  Makefile->>Exporter: run proxy OpenAPI export
  Exporter->>Spec: write generated specification
  Fern->>Spec: read specification for IR generation

Loading

Possibly related PRs

• NVIDIA-NeMo/Guardrails#2475: Adds the existing deterministic OpenAPI exporter and Fern generation and publishing pipeline extended here.
• NVIDIA-NeMo/Guardrails#2508: Documents the same experimental proxy routes and provider behavior.
• NVIDIA-NeMo/Guardrails#2467: Adds create_proxy_application, which this exporter uses to generate the proxy OpenAPI document.

Suggested labels: documentation, temp: guardrails-proxy

Suggested reviewers: pouyanpi, tgasser-nv, m-misiura

Merge Risk: Minimal · up to c89b8

The proxy reference is regenerated during documentation builds. No merge-blocking issue was identified; normal CI checks remain appropriate.

Pre-merge checks: 5 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…	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 describes the main change: generating experimental proxy API reference documentation.
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 a substantial documentation-generation feature and adds exporter and integration tests. The description documents test results for tests/server/test_export_proxy_openapi.py (4 passed…

Full details: Test Results For Major Changes

Explanation

The PR contains a substantial documentation-generation feature and adds exporter and integration tests. The description documents test results for tests/server/test_export_proxy_openapi.py (4 passed), make test-docs-scripts (21 passed), make docs-fern (0 errors), preview checks, pre-commit, and git diff --check. The change does not affect numerics, convergence, or runtime performance, so no performance comparison is required.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 6 functions across 7 files. (6 skipped: 6 unsupported.)

Resolution

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

Finishing Touches: 💡 2

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

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

[Pouyanpi]

thanks @miyoungc for putting this together, this is GREAT 🚀 having the reference generated from the proxy routes is really helpful.

I pushed some improvements for policy labels, disabled-field visibility, links to the guard contracts, and table readability. please feel free to adjust or drop anything that feels out of scope.

the main thing i’d like to preserve is the distinction between the proxy’s guard boundary and the upstream provider API. guarded, constrained, disabled, and opaque fields have different guarantees, so the reference should make those clear and point to the guard contract for details.

We could also hide "Try it" for now and handle connection setup, CORS, and credential input separately, following #2492. curious to hear your thoughts. I'll merge if you're ok with these changes or after you've done another iteration 👍🏻

[miyoungc]

Thanks, @Pouyanpi! Your improvements look good, and I agree with keeping the proxy’s guard boundary distinct from the upstream provider API.

I’ve hidden Try it for the proxy reference with x-fern-explorer: false in 31266fb. I verified locally that both proxy pages retain their examples and guard-contract links without the Try it control. Connection setup, CORS, and credential input can stay in the separate follow-up to #2492.

Ready to merge from my side once the remaining CI checks pass. Thanks for the improvements!

[Pouyanpi]

looks good, thanks @miyoungc ! hiding Try it for now makes sense, i'll merge this