> For the complete documentation index, see [llms.txt](https://gdplabs.gitbook.io/glchat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gdplabs.gitbook.io/glchat/organization-admin/how-to-guides/guardrail.md).

# Guardrail

#### Guardrail Modes

The system supports four different operational modes:

| Mode          | Description                       | Use Case                                   |
| ------------- | --------------------------------- | ------------------------------------------ |
| `disabled`    | No guardrail checks performed     | Development/testing environments           |
| `input_only`  | Only user input is checked        | Basic safety with minimal overhead         |
| `output_only` | Only AI responses are checked     | When input filtering is handled elsewhere  |
| `both`        | Both input and output are checked | Maximum safety for production environments |

### Configuration

#### Basic Configuration

Guardrails can be configured through the admin interface using preset configurations. The main configuration fields are:

**Core Settings**

* **`enable_guardrails`** (boolean): Master switch to enable/disable the entire guardrail system
* **`guardrail_mode`** (string): Controls which content is checked (`disabled`, `input_only`, `output_only`, `both`)

**Topic Safety Configuration**

* **`topic_safety_mode`** (string): Defines how topic filtering works
  * `allowlist`: Only specified topics are allowed
  * `denylist`: Only specified topics are blocked
  * `hybrid`: Combines both allowlist and denylist approaches
  * `disabled`: No topic-based filtering
* **`allowed_topics`** (JSON string): List of topics that are explicitly allowed

**`banned_phrases`** (JSON string): List of specific phrases that should be blocked

#### Database Configuration

The guardrail configuration is stored in the `config_fields` table and can be managed through the admin interface:

```sql
-- Example configuration field
INSERT INTO config_fields (
    name, type, constraints, default_value, ui_type, level
) VALUES (
    'guardrail_mode', 
    'str', 
    '["disabled", "input_only", "output_only", "both"]', 
    'input_only', 
    'dropdown', 
    'PRESET'
);
```

#### Advanced Configuration

**Custom Colang Configuration**

For advanced users, the system supports custom Colang configurations that define the exact business logic for content filtering:

```colang
# Example: Block competitor discussions
define user ask about competitor products
  "How does your product compare to [competitor]?"
  "Should I choose [competitor] instead?"
  "What are the advantages of [competitor]?"

define bot refuse competitor products
  "I can only provide information about our company's products and services."

define flow competitor products
  user ask about competitor products
  bot refuse competitor products
```

**Security Features**

The guardrail system includes several security measures:

1. **Circuit Breaker Pattern**: Prevents system failures from causing widespread issues
2. **Rate Limiting**: Prevents abuse through excessive requests (60 requests/minute by default)
3. **Input Sanitization**: Removes malicious characters and limits content length
4. **Error Handling**: Conservative approach - marks content as unsafe on errors

### Setting Up Guardrails

#### Step 1: Enable Guardrails

1. Navigate to your pipeline preset configuration in the admin interface
2. Set `enable_guardrails` to `true`
3. Choose your desired `guardrail_mode`

#### Step 2: Configure Topic Safety

1. Set `topic_safety_mode` to your preferred approach:
   * **Hybrid** (recommended): Combines allowlist and denylist for maximum flexibility
   * **Allowlist**: Only allow specific business topics
   * **Denylist**: Block specific off-topic areas
   * **Disabled**: No topic-based filtering
2. Configure your topic lists:

```json
// Example allowed topics
[
  "company products and services",
  "technical support", 
  "product documentation",
  "company policies",
  "general information about the company"
]

// Example denied topics  
[
  "competitor products",
  "political discussions",
  "weather information",
  "sports discussions",
  "entertainment topics"
]
```

#### Step 3: Set Up API Keys

Ensure your OpenAI API key is configured for the guardrail system:

```bash
export OPENAI_API_KEY="your-api-key-here"
```

### Core Safety Categories

The guardrail system includes comprehensive protection against:

#### 1. Child Safety and Protection

* Child exploitation content
* Age-inappropriate content access
* COPPA/FERPA violations

#### 2. Violence and Physical Harm

* Explicit violence promotion
* Weapons development instructions
* Self-harm and suicide content
* Threats and intimidation

#### 3. Hate Speech and Discrimination

* Protected characteristic targeting
* Harassment and bullying
* Extremist ideologies

#### 4. Privacy and Personal Information

* Personal data extraction
* Surveillance and stalking
* Identity theft facilitation

#### 5. Professional Services and Liability

* Unauthorized medical advice
* Legal advice and representation
* Financial/investment advice

#### 6. Misinformation and Deception

* Factual misinformation
* Election interference
* Deepfakes and synthetic media

#### 7. Regulated Industries and Compliance

* HIPAA-protected medical information
* Financial services/SOX compliance
* Educational/FERPA protected content

#### 8. Intellectual Property and Copyright

* Copyright infringement
* Trademark and brand misuse

#### 9. System Manipulation and Security

* Jailbreaking and prompt injection
* Model extraction and reverse engineering

### Best Practices

#### Configuration Recommendations

1. **Start with Hybrid Mode**: Use `topic_safety_mode: hybrid` for maximum flexibility
2. **Define Clear Business Topics**: Be specific about what your chatbot should handle
3. **Regular Testing**: Use the evaluation tools to test your configuration
4. **Monitor Performance**: Watch for false positives that block legitimate queries

#### Security Considerations

1. **API Key Management**: Store API keys securely and rotate them regularly
2. **Rate Limiting**: Adjust rate limits based on your expected traffic
3. **Error Handling**: Monitor guardrail failures and adjust configuration as needed
4. **Regular Updates**: Keep the guardrail rules updated with new threats and requirements

#### Performance Optimization

1. **SpaCy Integration**: Enable SpaCy for faster phrase matching (optional)
2. **Caching**: Use appropriate caching strategies for repeated queries
3. **Concurrent Processing**: Adjust concurrency limits based on your system capacity

### Troubleshooting

#### Common Issues

**Guardrails Not Working**

* Check that `enable_guardrails` is set to `true`
* Verify your OpenAI API key is configured
* Ensure the guardrail mode is not set to `disabled`

**False Positives**

* Review your allowed topics list
* Check for overly restrictive banned phrases
* Consider adjusting the topic safety mode

**Performance Issues**

* Monitor rate limiting settings
* Check for circuit breaker activations
* Review input sanitization settings

**Configuration Errors**

* Validate JSON format for topic lists
* Check Colang syntax for custom configurations
* Verify database migration status

### Migration and Updates

#### Configuration Migration

For existing installations:

1. Default configuration will be set to `input_only` mode for backward compatibility
2. Review and update your topic lists based on your business requirements
3. Test the new configuration in a staging environment before deploying to production

### Evaluation and Monitoring

#### Built-in Evaluation Tools

The system includes comprehensive evaluation tools:

* **Local Evaluation**: Test against predefined datasets
* **Langfuse Integration**: Track evaluation results and performance
* **Custom Metrics**: Add your own evaluation criteria

#### Monitoring Recommendations

1. **Track Block Rates**: Monitor how often content is blocked
2. **False Positive Analysis**: Review blocked content for legitimate queries
3. **Performance Metrics**: Monitor response times and system load
4. **Security Alerts**: Set up alerts for suspicious activity patterns

### API Reference

#### GuardrailManager Methods

```python
# Check user input
result = await guardrail_manager.check_content(user_query)

# Check AI output  
result = await guardrail_manager.check_system_output(ai_response)

# Reconfigure guardrails
guardrail_manager.reconfigure(config_dict, colang_config)
```

### Support and Resources

#### Documentation

* [NeMo Guardrails Documentation](https://github.com/NVIDIA/NeMo-Guardrails)
* [Colang Language Reference](https://github.com/NVIDIA/NeMo-Guardrails/blob/main/docs/user_guide/colang-language-reference.md)

#### Community

* [NeMo Guardrails GitHub](https://github.com/NVIDIA/NeMo-Guardrails)