Skip to content

Commit 7d6d264

Browse files
PouyanpiPouyanpi
authored
docs: add GuardrailsAI integration user guide and example (#1357)
1 parent 2d0af79 commit 7d6d264

File tree

3 files changed

+294
-0
lines changed

3 files changed

+294
-0
lines changed

‎docs/user-guides/community/guardrails-ai.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# GuardrailsAI Integration
2+
3+
NeMo Guardrails provides out-of-the-box support for [GuardrailsAI](https://github.com/guardrails-ai/guardrails) validators, enabling comprehensive input and output validation using a rich ecosystem of community-built validators. GuardrailsAI offers validators for content safety, PII detection, toxic language filtering, jailbreak detection, topic restriction, and much more.
4+
5+
The integration provides access to both built-in validators and the entire [Guardrails Hub](https://hub.guardrailsai.com/) ecosystem, allowing you to dynamically load and configure validators for your specific use cases.
6+
7+
## Setup
8+
9+
To use GuardrailsAI validators, you need to install the `guardrails-ai` package:
10+
11+
```bash
12+
pip install guardrails-ai
13+
```
14+
15+
You may also need to install specific validators from the Guardrails Hub:
16+
17+
```bash
18+
guardrails hub install guardrails/toxic_language
19+
guardrails hub install guardrails/detect_jailbreak
20+
guardrails hub install guardrails/guardrails_pii
21+
```
22+
23+
## Usage
24+
25+
The GuardrailsAI integration uses a flexible configuration system that allows you to define validators with their parameters and metadata, then reference them in your input and output rails.
26+
27+
### Configuration Structure
28+
29+
Add GuardrailsAI validators to your `config.yml`:
30+
31+
```yaml
32+
rails:
33+
config:
34+
guardrails_ai:
35+
validators:
36+
- name: toxic_language
37+
parameters:
38+
threshold: 0.5
39+
validation_method: "sentence"
40+
metadata: {}
41+
- name: guardrails_pii
42+
parameters:
43+
entities: ["phone_number", "email", "ssn"]
44+
metadata: {}
45+
- name: competitor_check
46+
parameters:
47+
competitors: ["Apple", "Google", "Microsoft"]
48+
metadata: {}
49+
```
50+
51+
### Input Rails
52+
53+
To use GuardrailsAI validators for input validation:
54+
55+
```yaml
56+
rails:
57+
input:
58+
flows:
59+
- guardrailsai check input $validator="guardrails_pii"
60+
- guardrailsai check input $validator="competitor_check"
61+
```
62+
63+
### Output Rails
64+
65+
To use GuardrailsAI validators for output validation:
66+
67+
```yaml
68+
rails:
69+
output:
70+
flows:
71+
- guardrailsai check output $validator="toxic_language"
72+
- guardrailsai check output $validator="restricttotopic"
73+
```
74+
75+
## Built-in Validators
76+
77+
The integration includes support for the following validators that are pre-registered in the NeMo Guardrails validator registry. For detailed parameter specifications and usage examples, refer to the official [GuardrailsAI Hub](https://hub.guardrailsai.com/) documentation for each validator:
78+
79+
- `competitor_check` - `hub://guardrails/competitor_check`
80+
- `detect_jailbreak` - `hub://guardrails/detect_jailbreak`
81+
- `guardrails_pii` - `hub://guardrails/guardrails_pii`
82+
- `one_line` - `hub://guardrails/one_line`
83+
- `provenance_llm` - `hub://guardrails/provenance_llm`
84+
- `regex_match` - `hub://guardrails/regex_match`
85+
- `restricttotopic` - `hub://tryolabs/restricttotopic`
86+
- `toxic_language` - `hub://guardrails/toxic_language`
87+
- `valid_json` - `hub://guardrails/valid_json`
88+
- `valid_length` - `hub://guardrails/valid_length`
89+
90+
## Complete Example
91+
92+
Here's a comprehensive example configuration:
93+
94+
```yaml
95+
models:
96+
- type: main
97+
engine: openai
98+
model: gpt-4
99+
100+
rails:
101+
config:
102+
guardrails_ai:
103+
validators:
104+
- name: toxic_language
105+
parameters:
106+
threshold: 0.5
107+
validation_method: "sentence"
108+
metadata: {}
109+
- name: guardrails_pii
110+
parameters:
111+
entities: ["phone_number", "email", "ssn", "credit_card"]
112+
metadata: {}
113+
- name: competitor_check
114+
parameters:
115+
competitors: ["Apple", "Google", "Microsoft", "Amazon"]
116+
metadata: {}
117+
- name: restricttotopic
118+
parameters:
119+
valid_topics: ["technology", "science", "education"]
120+
metadata: {}
121+
- name: valid_length
122+
parameters:
123+
min: 10
124+
max: 500
125+
metadata: {}
126+
127+
input:
128+
flows:
129+
- guardrailsai check input $validator="guardrails_pii"
130+
- guardrailsai check input $validator="competitor_check"
131+
132+
output:
133+
flows:
134+
- guardrailsai check output $validator="toxic_language"
135+
- guardrailsai check output $validator="restricttotopic"
136+
- guardrailsai check output $validator="valid_length"
137+
```
138+
139+
## Custom Validators from Guardrails Hub
140+
141+
You can use any validator from the [Guardrails Hub](https://hub.guardrailsai.com/) by specifying its hub path:
142+
143+
```yaml
144+
rails:
145+
config:
146+
guardrails_ai:
147+
validators:
148+
- name: custom_validator_name
149+
parameters:
150+
# Custom parameters specific to the validator
151+
metadata: {}
152+
```
153+
154+
The integration will automatically fetch validator information from the hub if it's not in the built-in registry.
155+
156+
## Performance Considerations
157+
158+
- Validators are cached to improve performance on repeated use
159+
- Guard instances are reused when the same validator is called with identical parameters
160+
- Consider the latency impact when chaining multiple validators
161+
162+
For a complete working example, see the [GuardrailsAI example configuration](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples/configs/guardrails_ai/).

‎docs/user-guides/guardrails-library.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ NeMo Guardrails comes with a library of built-in guardrails that you can easily
2222
- [Clavata.ai](#clavata)
2323
- [Cleanlab Trustworthiness Score](#cleanlab)
2424
- [GCP Text Moderation](#gcp-text-moderation)
25+
- [GuardrailsAI Integration](#guardrailsai-integration)
2526
- [Private AI PII detection](#private-ai-pii-detection)
2627
- [Fiddler Guardrails for Safety and Hallucination Detection](#fiddler-guardrails-for-safety-and-hallucination-detection)
2728
- [Prompt Security Protection](#prompt-security-protection)
@@ -772,6 +773,33 @@ rails:
772773

773774
For more details, check out the [GCP Text Moderation](https://github.com/NVIDIA/NeMo-Guardrails/blob/develop/docs/user-guides/community/gcp-text-moderations.md) page.
774775

776+
### GuardrailsAI Integration
777+
778+
NeMo Guardrails supports using [GuardrailsAI validators](https://github.com/guardrails-ai/guardrails) for comprehensive input and output validation. GuardrailsAI provides a wide range of validators for content safety, PII detection, toxic language filtering, jailbreak detection, and more.
779+
780+
#### Example usage
781+
782+
```yaml
783+
rails:
784+
config:
785+
guardrails_ai:
786+
validators:
787+
- name: toxic_language
788+
parameters:
789+
threshold: 0.5
790+
- name: guardrails_pii
791+
parameters:
792+
entities: ["phone_number", "email", "ssn"]
793+
input:
794+
flows:
795+
- guardrailsai check input $validator="guardrails_pii"
796+
output:
797+
flows:
798+
- guardrailsai check output $validator="toxic_language"
799+
```
800+
801+
For more details, check out the [GuardrailsAI Integration](./community/guardrails-ai.md) page.
802+
775803
### Private AI PII Detection
776804

777805
NeMo Guardrails supports using [Private AI API](https://docs.private-ai.com/?utm_medium=github&utm_campaign=nemo-guardrails) for PII detection and masking input, output and retrieval flows.

‎examples/configs/guardrails_ai/README.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# GuardrailsAI Integration Example
2+
3+
This example demonstrates how to use GuardrailsAI validators with NeMo Guardrails for comprehensive input and output validation.
4+
5+
## Overview
6+
7+
The configuration showcases multiple GuardrailsAI validators working together to provide:
8+
9+
- **PII Detection**: Prevents personally identifiable information in inputs
10+
- **Competitor Checking**: Blocks mentions of competitor companies
11+
- **Topic Restriction**: Ensures outputs stay within allowed topics
12+
- **Toxic Language Detection**: Filters harmful or inappropriate content
13+
14+
## Setup
15+
16+
1. **Install GuardrailsAI**:
17+
18+
```bash
19+
pip install guardrails-ai
20+
```
21+
22+
2. **Install required validators**:
23+
24+
```bash
25+
guardrails hub install hub://guardrails/guardrails_pii
26+
guardrails hub install hub://guardrails/competitor_check
27+
guardrails hub install hub://tryolabs/restricttotopic
28+
```
29+
30+
## Configuration Explanation
31+
32+
### Validator Definitions
33+
34+
The `config.yml` defines four validators under `rails.config.guardrails_ai.validators`:
35+
36+
```yaml
37+
38+
- name: guardrails_pii
39+
parameters:
40+
entities: ["phone_number", "email", "ssn"] # PII types to detect
41+
metadata: {}
42+
43+
- name: competitor_check
44+
parameters:
45+
competitors: ["Apple", "Google", "Microsoft"] # Competitor names
46+
metadata: {}
47+
48+
- name: restricttotopic
49+
parameters:
50+
valid_topics: ["technology", "science", "education"] # Allowed topics
51+
metadata: {}
52+
```
53+
54+
### Rail Configuration
55+
56+
**Input Rails** (check user messages):
57+
58+
```yaml
59+
input:
60+
flows:
61+
- guardrailsai check input $validator="guardrails_pii" # Block PII
62+
- guardrailsai check input $validator="competitor_check" # Block competitors
63+
```
64+
65+
**Output Rails** (check bot responses):
66+
67+
```yaml
68+
output:
69+
flows:
70+
- guardrailsai check output $validator="restricttotopic" # Ensure on-topic
71+
```
72+
73+
## Running the Example
74+
75+
### Using Python API
76+
77+
```python
78+
from nemoguardrails import RailsConfig, LLMRails
79+
80+
# Load the configuration
81+
config = RailsConfig.from_path(".")
82+
rails = LLMRails(config)
83+
84+
# Test input validation (should be blocked - contains email)
85+
response = rails.generate(messages=[{
86+
"role": "user",
87+
"content": "My email is john.doe@example.com, can you help me?"
88+
}])
89+
print(response) # Should refuse to respond
90+
91+
# Test competitor mention (should be blocked)
92+
response = rails.generate(messages=[{
93+
"role": "user",
94+
"content": "What do you think about Apple's latest iPhone?"
95+
}])
96+
print(response) # Should refuse to respond
97+
98+
# Test valid input
99+
response = rails.generate(messages=[{
100+
"role": "user",
101+
"content": "Can you explain how machine learning works?"
102+
}])
103+
print(response) # Should provide a response about ML
104+
```

0 commit comments

Comments
 (0)