Skip to content

Commit da9df25

Browse files
ckhordiasmackhordiasma
committed
Merge remote-tracking branch 'upstream/stable'
2 parents ad92087 + c4fa3ac commit da9df25

461 files changed

Lines changed: 44657 additions & 34404 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/guardrails-developer-create-guardrails/SKILL.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
name: "guardrails-developer-create-guardrails"
3+
description: "Helps developers create a NeMo Guardrails configuration for an LLM application. Use when users want to build, scaffold, configure, test, or iterate on input, output, retrieval, dialog, execution, Colang, or catalog-based guardrails. Trigger keywords - create guardrails, build guardrails, scaffold config, write rails, create config.yml, add input rails, add output rails, Colang flow, guardrails config, test guardrails."
4+
license: "Apache-2.0"
5+
---
6+
7+
# Create Guardrails
8+
9+
Use this skill when a developer wants help creating a guardrails configuration, not just reading documentation.
10+
The goal is to produce a small, working configuration first, then iterate based on the user's risk, model, app, and test cases.
11+
12+
Use `guardrails-developer-guide` to look up canonical docs when needed.
13+
Do not duplicate full docs in this skill.
14+
15+
## Documentation Source Rule
16+
17+
When using NVIDIA NeMo Guardrails library documentation, use the Markdown documentation under `https://docs.nvidia.com/nemo/guardrails/`.
18+
Use `llms.txt` and page URLs ending in `.md` when loading documentation for agent context.
19+
When presenting references or citations to users, use the canonical human-readable docs links without `.md`.
20+
21+
## First Questions
22+
23+
Ask only what you need to choose a starting path:
24+
25+
1. What kind of application are you guarding?
26+
2. Which model/provider or framework are you using?
27+
3. Which risk do you want to handle first?
28+
4. Do you want a quick catalog-based guardrail, a Colang flow, or a Python integration?
29+
30+
If the user is unsure, recommend starting with the smallest working input/output rail and one concrete test prompt.
31+
32+
## Choose The Starting Pattern
33+
34+
| User goal | Starting pattern |
35+
| --- | --- |
36+
| Block harmful content | Content safety input/output rails |
37+
| Restrict topics | Topic control or topical rails |
38+
| Detect jailbreaks | Jailbreak protection or heuristics |
39+
| Mask or detect sensitive data | PII detection rails |
40+
| Reduce hallucinations in RAG | Retrieval/output fact-checking rails |
41+
| Control conversation flow | Colang dialog flows |
42+
| Guard tool calls or actions | Execution rails and action validation |
43+
| Integrate with LangChain or LangGraph | RunnableRails, middleware, or documented integration path |
44+
45+
Route to the relevant docs page through `guardrails-developer-guide` before filling in details that depend on the current docs.
46+
47+
## Create A Minimal Config
48+
49+
Prefer a standard config folder layout:
50+
51+
```text
52+
config/
53+
config.yml
54+
prompts.yml
55+
rails.co
56+
actions.py
57+
```
58+
59+
Only create files that are needed:
60+
61+
- Use `config.yml` for models, rails, streaming, tracing, and configuration.
62+
- Use `prompts.yml` when the selected rail needs custom prompt templates.
63+
- Use `.co` files when the solution needs Colang flows.
64+
- Use `actions.py` only when Python actions are required.
65+
66+
When editing an existing app, preserve the user's project layout and avoid moving unrelated files.
67+
68+
## Build Iteratively
69+
70+
1. Start with one guardrail objective.
71+
2. Write the smallest config that exercises that objective.
72+
3. Add two or three test prompts:
73+
- a request that should pass,
74+
- a request that should be blocked or modified,
75+
- an edge case if the user has one.
76+
4. Run the config through the documented Python API, CLI chat, or server path that matches the user's setup.
77+
5. Inspect the result and adjust the rail, prompt, flow, or model configuration.
78+
79+
Do not silently introduce live provider calls.
80+
Ask before running commands that require network access, credentials, paid APIs, Docker, or long-running services.
81+
82+
## Testing And Verification
83+
84+
For product users, verify with the smallest runnable example:
85+
86+
- `nemoguardrails chat --config <config-path>` when using the CLI.
87+
- A short Python script with `RailsConfig.from_path(...)` and `LLMRails(...)` when embedding in an app.
88+
- The documented server endpoints when using the Guardrails API server.
89+
90+
For repository contributors, unit tests must not call live LLM or provider services.
91+
Use repository test doubles and mocks according to `nemoguardrails/AGENTS.md`.
92+
93+
## Security And Credentials
94+
95+
- Never ask users to paste real API keys, tokens, or provider credentials into chat.
96+
- Use placeholders such as `<NVIDIA_API_KEY>`, `<OPENAI_API_KEY>`, and `<YOUR_ENDPOINT>`.
97+
- Explain where secrets should be set locally.
98+
- Do not write secrets into committed config examples.
99+
100+
## Output Format
101+
102+
When helping create guardrails, return:
103+
104+
1. The chosen starting pattern and why.
105+
2. The files to create or edit.
106+
3. The proposed config or code snippets.
107+
4. The verification command or script.
108+
5. The test prompts and expected behavior.
109+
6. Follow-up improvements after the first working version.
110+
111+
## Related Skills
112+
113+
- Use `guardrails-developer-guide` for documentation lookup and product-usage questions.
114+
When editing this repository, follow `AGENTS.md` and any subtree `AGENTS.md` files that apply.

‎.agents/skills/guardrails-developer-guide/SKILL.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
name: "guardrails-developer-guide"
3+
description: "Routes NVIDIA NeMo Guardrails library product-usage questions to the canonical documentation. Use when users ask how to install, configure, integrate, evaluate, observe, deploy, troubleshoot, or use the NVIDIA NeMo Guardrails library. Trigger keywords - install guardrails, configure rails, guardrail catalog, Colang, Python API, LangChain, LangGraph, server, evaluate guardrails, tracing, metrics, Docker, troubleshooting."
4+
license: "Apache-2.0"
5+
---
6+
7+
# Guardrails Developer Guide
8+
9+
Use this skill for product-usage questions about the NVIDIA NeMo Guardrails library.
10+
Do not restate full product documentation in this skill.
11+
Route the agent to the canonical docs and summarize the relevant guidance for the user's task.
12+
13+
## Documentation Source Rule
14+
15+
Always use the Markdown documentation under `https://docs.nvidia.com/nemo/guardrails/`.
16+
Use `llms.txt` and page URLs ending in `.md` when loading documentation for agent context.
17+
When presenting references or citations to users, use the canonical human-readable docs links without `.md`.
18+
19+
## Retrieval Order
20+
21+
1. Prefer the docs MCP server when the client supports MCP.
22+
Use the NVIDIA NeMo Guardrails library docs MCP server documented on the published docs site.
23+
2. If MCP is not available, fetch the docs index:
24+
25+
```text
26+
https://docs.nvidia.com/nemo/guardrails/llms.txt
27+
```
28+
29+
3. Use the index to locate the relevant page, then fetch the clean Markdown form of that page by using the page URL with `.md`.
30+
4. If the user is working in a cloned repository and remote docs are unavailable, fall back to local `docs/**/*.mdx`.
31+
5. If the user has the package installed, align docs to the installed `nemoguardrails` version when versioned docs are available.
32+
If the version cannot be determined, ask whether to use the latest docs.
33+
34+
## Do Not Hardcode Staging
35+
36+
Use production docs as the canonical source.
37+
Use staging URLs only when the user explicitly asks to inspect staging or when validating migration behavior.
38+
39+
## Intent Routing
40+
41+
Use this table to find the right docs area quickly.
42+
43+
| User intent | Docs area |
44+
| --- | --- |
45+
| Install or verify environment | Get Started → Installation |
46+
| Add harmful-content, jailbreak, topic, PII, self-check, fact-check, or agentic security rails | Configure Guardrails → Guardrail Catalog |
47+
| Configure `config.yml`, models, prompts, tracing, streaming, or exceptions | Configure Guardrails → YAML schema and configuration reference |
48+
| Write or debug Colang flows | Configure Guardrails → Colang |
49+
| Use Python APIs | Run Guardrailed Inference → Python API |
50+
| Run the Guardrails API server or actions server | Run Guardrailed Inference → Guardrails API Server |
51+
| Integrate with LangChain, LangGraph, RunnableRails, or tools | Integration with Third-Party Libraries |
52+
| Evaluate guardrails or run vulnerability scanning | Evaluation |
53+
| Configure tracing, metrics, or logging | Observability |
54+
| Deploy with Docker or NeMo microservice | More Deployment Options |
55+
| Troubleshoot errors | Troubleshooting |
56+
| Understand telemetry and privacy | Resources → Telemetry and Privacy |
57+
58+
## Security And Credential Handling
59+
60+
- Never ask users to paste real API keys, tokens, passwords, or provider credentials into chat.
61+
- Use placeholders such as `<NVIDIA_API_KEY>`, `<OPENAI_API_KEY>`, or `<YOUR_ENDPOINT>` in examples.
62+
- Explain where users should set secrets locally, such as shell environment variables, secret managers, local config, or provider dashboards.
63+
- Do not print, store, or echo secrets in generated commands or summaries.
64+
65+
## Response Style
66+
67+
- Start with the user's immediate task and the relevant doc source.
68+
- Give the smallest working path first.
69+
- Add production hardening, optional extras, or alternative integrations only when they are relevant.
70+
- When examples use live providers, remind contributors that tests must mock LLM and provider calls.
71+
72+
## Related Skills
73+
74+
- Use `guardrails-developer-create-guardrails` when creating or modifying a guardrails configuration.
75+
When editing this repository, follow `AGENTS.md` and any subtree `AGENTS.md` files that apply.

‎.claude/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.agents/skills

‎.coderabbit.yaml‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,13 @@ reviews:
4646
# Default: true
4747
review_status: false # current: true
4848
path_instructions:
49+
- path: "fern/docs.yml"
50+
instructions: |
51+
Redirect destinations for documentation pages must use the rendered Fern route from docs/index.yml, not the source file path.
52+
In docs/index.yml, the rendered URL comes from the section/page `slug` hierarchy; the `path` field only points to the source MDX file.
53+
For example, the source path docs/configure-rails/colang/colang-2/language-reference/introduction.mdx renders under /configure-guardrails/colang/colang-2/language-reference/introduction because the top-level Configure Guardrails section has slug `configure-guardrails`.
54+
Do not suggest replacing valid rendered routes such as /configure-guardrails/... with source-path-derived routes such as /configure-rails/....
55+
Before flagging a redirect destination as wrong, verify the route by tracing the relevant entries in docs/index.yml.
4956
- path: "docs/**/*.mdx"
5057
instructions: |
5158
Internal absolute documentation links in Fern MDX pages must use the rendered Fern route, not the source file path.
@@ -54,7 +61,7 @@ reviews:
5461
- docs/configure-rails/colang/index.mdx renders at /configure-guardrails/colang, not /configure-rails/colang.
5562
- docs/run-rails/index.mdx renders at /run-guardrailed-inference/run-rails, not /run-rails.
5663
- docs/getting-started/installation-guide.mdx renders at /get-started/installation-guide, not /getting-started/installation-guide.
57-
Before flagging or suggesting fixes for internal docs links, verify them with scripts/check-docs-links.sh or docs/index.yml.
64+
Before flagging or suggesting fixes for internal docs links, verify them with docs/index.yml.
5865
Do not suggest changing valid Fern routes back to source-path-style links.
5966
- path: "docs/**/*.ipynb"
6067
instructions: |
@@ -83,4 +90,9 @@ reviews:
8390
# Review draft PRs/MRs.
8491
# Default: false
8592
drafts: false
93+
# Only auto-review PRs labeled `status: triaged` (auto-applied for maintainers
94+
# / NVIDIA-NeMo org members; a maintainer adds it after triage for external
95+
# contributors). Gates review noise on agent/external PRs.
96+
labels:
97+
- "status: triaged"
8698
# Base branches (other than the default branch) to review. Accepts regex patterns. Use '.*' to match all branches.

‎.dockerignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
.git
22
.idea
33
venv*
4+
.venv
45
env*
56
temp
67
__pycache__

‎.github/ISSUE_TEMPLATE/refactor_proposal.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Refactor Proposal
2+
description: Propose a maintainer-led refactor for discussion
3+
title: "refactor: "
4+
labels: ["refactoring", "status: needs triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Refactors are maintainer-led and are not accepted as unsolicited pull requests.
10+
11+
Use this form to explain the problem and proposed direction. Maintainers decide whether the refactor should happen, what plan is acceptable, and who, if anyone, should be assigned to implement it.
12+
- type: checkboxes
13+
attributes:
14+
label: Required checks
15+
description: Confirm before submitting this proposal.
16+
options:
17+
- label: I searched existing issues and pull requests for related refactor proposals.
18+
required: true
19+
- label: I understand that opening this issue does not mean a refactor PR will be accepted.
20+
required: true
21+
- label: I understand that a refactor PR should not be opened unless a maintainer approves the plan and assigns the work.
22+
required: true
23+
- type: textarea
24+
attributes:
25+
label: Problem
26+
description: What is hard to maintain, unsafe, confusing, or blocking today?
27+
placeholder: Describe the current design problem and why it matters.
28+
validations:
29+
required: true
30+
- type: textarea
31+
attributes:
32+
label: Proposed direction
33+
description: What structural direction do you think maintainers should consider?
34+
placeholder: Keep this high level unless maintainers have asked for detailed design.
35+
validations:
36+
required: true
37+
- type: textarea
38+
attributes:
39+
label: Migration and compatibility notes
40+
description: What public APIs, config formats, docs, or user workflows could be affected?
41+
validations:
42+
required: true
43+
- type: textarea
44+
attributes:
45+
label: Validation plan
46+
description: What tests, docs checks, or compatibility checks would be needed?
47+
validations:
48+
required: true
49+
- type: textarea
50+
attributes:
51+
label: Risks
52+
description: List known risks, open questions, and possible alternatives.
53+
validations:
54+
required: true
55+
- type: textarea
56+
attributes:
57+
label: Relevant branch or files
58+
description: Optional. Share a WIP branch, affected files, or investigation notes if useful.
59+
validations:
60+
required: false
61+
- type: dropdown
62+
attributes:
63+
label: Are you interested in helping after maintainer approval?
64+
description: This does not assign you to the work. Maintainers decide ownership after triage.
65+
options:
66+
- I am only proposing this for maintainer consideration.
67+
- I can help with investigation if maintainers ask.
68+
- I can help implement after maintainers approve a plan and assign the work.
69+
validations:
70+
required: true

‎.github/PULL-REQUEST-TEMPLATE.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,36 @@
11
## Description
22

33
<!-- Describe the big picture of your changes to communicate to the maintainers
4-
why we should accept this pull request. -->
4+
why we should accept this pull request. Include any areas that need careful
5+
review. -->
56

67
## Related Issue(s)
78

89
<!--
9-
If this PR fixes any issues, please link to the issue here.
10+
Every PR must link to a triaged issue assigned to the PR author.
1011
- Fixes #<issue_number>
12+
- Issue assignee: @<username>
1113
-->
1214

15+
## Verification
16+
17+
<!-- CI runs the automated test suite. Note any verification beyond CI (manual
18+
checks, live/credentialed paths, docs build) and any relevant check you could
19+
not run, with residual risk. -->
20+
21+
## AI Assistance
22+
23+
- [ ] No AI tools were used.
24+
- [ ] AI tools were used; a human reviewed and can explain every change (tool: ___).
25+
1326
## Checklist
1427

1528
- [ ] I've read the [CONTRIBUTING](https://github.com/NVIDIA-NeMo/Guardrails/blob/develop/CONTRIBUTING.md) guidelines.
29+
- [ ] This PR links to a triaged issue assigned to me.
30+
- [ ] My PR title follows the project commit convention.
1631
- [ ] I've updated the documentation if applicable.
1732
- [ ] I've added tests if applicable.
33+
- [ ] I've noted any verification beyond CI and any checks I couldn't run.
34+
- [ ] I did not update generated changelog files manually.
35+
- [ ] I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed.
1836
- [ ] @mentions of the person or team responsible for reviewing proposed changes.

‎.github/actions/setup-uv/action.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Set up uv
2+
description: Install the canonical uv version used by GitHub Actions
3+
4+
inputs:
5+
version:
6+
description: uv version to install
7+
required: false
8+
default: "0.11.26"
9+
enable-cache:
10+
description: Enable the uv cache
11+
required: false
12+
default: "true"
13+
cache-suffix:
14+
description: Additional cache key suffix
15+
required: false
16+
default: ""
17+
18+
runs:
19+
using: composite
20+
steps:
21+
- uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
22+
with:
23+
version: ${{ inputs.version }}
24+
enable-cache: ${{ inputs.enable-cache }}
25+
cache-dependency-glob: uv.lock
26+
cache-suffix: ${{ inputs.cache-suffix }}

‎.github/codecov.yml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@ coverage:
22
status:
33
project:
44
default:
5-
informational: true
5+
target: auto
6+
threshold: 0.25%
7+
informational: false
68
patch:
79
default:
10+
target: 90%
11+
threshold: 0%
812
informational: true
913

1014
comment:
1115
layout: " diff, flags, files"
1216
behavior: default
13-
require_changes: false # if true: only post the comment if coverage changes
17+
require_changes: "coverage_drop OR uncovered_patch"
1418
require_base: false # [true :: must have a base report to post]
1519
require_head: true # [true :: must have a head report to post]
1620
hide_project_coverage: false # [true :: only show coverage on the git diff aka patch coverage]

0 commit comments

Comments
 (0)