[miyoungc]

Description

Position the GitHub overview around programmable safeguards for agents, with concise use cases for conversations, RAG, and model-provider APIs. Explain policy configuration, workflow checks, and application enforcement in three bullets. Consolidate capabilities into “Why NeMo Guardrails” and provide twelve linked catalog entries, named Nemotron Safety models, and garak evaluation guidance.

Keep the complete, package-based refund quickstart and all three historical community-usage charts in expandable sections. The quickstart prints the blocking rail and reason; the community snapshot retains its release/date scope, estimated counts, aggregate data, and methodology. Link detailed model, integration, and deployment instructions to the documentation.

Align Python requirements with the launch package (3.11–3.13), add security/release navigation, and remove the hard-coded release marker and its dependent workflow updater. The PR changes only README.md and .github/workflows/release.yml.

Preview: https://github.com/NVIDIA-NeMo/Guardrails/blob/miyoungc/ngr-1020-guardrails-github-overview-update/README.md

Related Issue(s)

• Closes NGR-1088 — sheet row 4: README entry point.
• Related to NGR-1090 — sheet row 9: README and non-README examples. This row requires both PR docs: position the GitHub overview for agent workflows #2522 and PR docs: correct guardrail examples and server guidance #2585; neither PR alone closes it.
• NGR-1020: Guardrails Github Overview update
• NGUARD-1015

The tracking issue is in Linear; there is no linked triaged GitHub issue.

Verification

• Built 0.25.0rc1 from the updated branch and installed its [cel] extra with all runtime dependencies in a fresh Python 3.13 environment. Ran the exact README script outside the checkout with network connections prohibited. Output, blocking rail/reason, and seven additional policy/schema cases passed.
• 154 focused checks-API and per-tool CEL tests passed. No live model/provider calls were made.
• Verified 44 local links, image targets, and heading anchors, plus four published NVIDIA documentation URLs. Checked the community count, release scope, dates, and charts against the existing aggregate dataset and methodology.
• uv run --locked pre-commit run --files README.md .github/workflows/release.yml and git diff --check passed.
• make docs-fern generated 440 SDK reference pages and passed with 0 errors and 566 warnings. Used the existing cached SDK parser image after its remote image pull stalled; the cache override was local only.
• GitHub Markdown rendering confirmed the two expandable sections, catalog table, and image links. The release action version comment was corrected to v8.1.1, matching its unchanged pinned hash.
• Completed a source-backed editorial review for product positioning, supported use cases, activation/engine boundaries, execution ownership, package requirements, privacy, and metric provenance.

The package install flow targets publication with the 0.25.0 launch. Validation used the current release-candidate wheel, not a published GA package.

Source references

• Launch Python and CEL requirements
• Checks without main-model generation and tool-rail selection
• Declared-tool and argument validation
• Tool-result validation
• Shared checks and guarded generation endpoints
• Proxy request coverage
• Coding-agent hook adapters
• Community aggregate dataset
• Community metrics methodology
• Telemetry schema and opt-out

AI Assistance

Codex helped prepare the README and perform local verification. Human review is pending.

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

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. The exact README example was checked in a fresh wheel installation, with policy/schema boundaries verified.
• I've noted verification 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

• Documentation
  • Reworked the README to explain how applications can apply programmable safeguards for AI agents, including workflow checks and verdict enforcement.
  • Added a refund-tool example, deployment options, supported checks, limitations, and telemetry information.
  • Updated installation, contribution, and license references. The release process no longer updates the README’s release link.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge for its intended 0.25.0 launch.

Summary

Reworks the README around agent workflows and removes the release workflow's README updater.

• The README points agent builders to the checks that fit their apps.
• The quickstart shows how an app checks a proposed refund before execution.
• The README links guardrail choices to model and evaluation guides.
• Community figures and support details move into shorter, easier-to-scan sections.
• Release preparation stops rewriting the README's version link.

_{Reviews (6) · Last reviewed commit: "ci: correct the pinned release action ve..." · Reviewed by Greptile}

[greptile-apps]

Promised privacy guidance is missing

The linked page only covers library telemetry; it does not contain the promised third-party endpoint terms. This PR also removes the README's explanation that third-party services have separate privacy terms and that the library's opt-out does not cover them. Readers following this link cannot find that guidance. Move it into the linked page or link to a page that contains it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: README.md
Line: 253

Comment:
**Promised privacy guidance is missing**

The linked page only covers library telemetry; it does not contain the promised third-party endpoint terms. This PR also removes the README's explanation that third-party services have separate privacy terms and that the library's opt-out does not cover them. Readers following this link cannot find that guidance. Move it into the linked page or link to a page that contains it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[miyoungc]

This finding is outdated at the current PR head. The original wording was corrected in c88c161 and the relevant disclosure is retained in the current Telemetry and Privacy section.

The README no longer promises that the telemetry page contains third-party endpoint terms. It also explicitly states that the usage-telemetry opt-out does not disable configured model or guardrail service calls, and that those calls can send content to their endpoints.

The linked telemetry guide is now offered for telemetry details and opt-out options. The current README therefore addresses the missing disclosure and removes the inaccurate link promise. Please remove this already-addressed finding from the review summary.

[greptile-apps]

Agreed. The current README has corrected the link’s scope and explicitly discloses that configured model or guardrail service calls can send content to their endpoints, regardless of the usage-telemetry opt-out. This finding is addressed and should be removed from the review summary.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA-NeMo/Guardrails
• Branch: miyoungc/ngr-1020-guardrails-github-overview-update
• File: .coderabbit.yaml
• Commit: bec712d
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: a3e69471-0703-48fe-8184-0cf2dbaa32af

Commits

Reviewing files that changed from the base of the PR and between 731f6d0 and bec712d.

Files selected for processing: 2

• .github/workflows/release.yml
• README.md

Files with no reviewable changes: 1

• .github/workflows/release.yml

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

The README is rewritten around programmable safeguards for AI agents, with a new quickstart and updated deployment, check, telemetry, and project information. The release workflow no longer updates README release references; version, changelog, and lockfile updates remain.

Changes: Agent safeguards documentation

Layer / File(s)	Summary
Project framing and release updates README.md, .github/workflows/release.yml	The README introduces configurable checks for agent workflows and updates project links. The release workflow stops editing the README and removes the related pull request text and path entry.
Check workflow and quickstart README.md	The README explains check verdicts and tool execution boundaries, then adds a refund-tool example using a CEL rule, check_async(), and IORails.
Deployment and check coverage README.md	The README describes the HTTP proxy, coding-agent hooks, framework integration, check coverage, and supported engines.
Telemetry and project policies README.md	The README shortens its telemetry description and updates contribution, license, and citation links.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested labels: documentation

Suggested reviewers: pouyanpi

Merge Risk: Minimal · up to bec71

No actionable merge-blocking risk remains.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the main change: repositioning the GitHub README around agent workflows. The release workflow update is secondary.
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 makes a substantial README and release-workflow documentation change. Its description includes testing information: a network-disabled quickstart run, seven policy and schema boundary checks, t…

Full details: Test Results For Major Changes

Explanation

The PR makes a substantial README and release-workflow documentation change. Its description includes testing information: a network-disabled quickstart run, seven policy and schema boundary checks, target and URL validation, pre-commit, diff, and documentation checks. No numeric, convergence, or performance change is introduced.

Finishing Touches

🧪 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]

Thanks for the PR @miyoungc. This has good coverage of agentic use-cases, but is missing all the other capabilities of Guardrails. We still support a range of rails for conversational, RAG, etc. We need to add these into the README as well.

Recommend adding a section at the top with all the use-cases we support including conversational application with input and output rails, RAG, etc. Then each of these can link to a more detailed section below with further information. The PR as it is will be good for agentic / tool-calling usecases

[Pouyanpi]

shall we add ?
guardrailing/securing model provider API's through the serveror the experimental guardrails proxy

[Pouyanpi]

I’m not sure whether the requirements have changed, but the original decision was to include these telemetry metrics in the README as a way of giving back to the community.