RULES_EXAMPLES.md

# Admin Rules Examples for IntegraChat

This document provides examples of rules you can use with the IntegraChat admin rules system.

## Quick Start

1. **Simple Rules** - Copy from `example_rules.txt` and paste into Gradio UI or Next.js frontend
2. **File Upload** - Drag and drop or upload TXT, PDF, DOC, or DOCX files directly
3. **Detailed Rules** - Use `example_rules_detailed.json` for rules with patterns and severity
4. **API** - Use the `/admin/rules`, `/admin/rules/bulk`, or `/admin/rules/upload-file` endpoints

## Rule Categories

### 🔴 Critical Severity Rules

These rules block the most sensitive information:

```
Block password disclosure requests
Prevent sharing of API keys or tokens
No sharing of credit card information
Block requests for bank account details
Prevent sharing of health information
No disclosure of children's personal information
```

### 🟠 High Severity Rules

Important security and compliance rules:

```
Block social security number requests
Prevent disclosure of proprietary information
No unauthorized access to financial records
Block requests to delete system logs
Prevent unauthorized system configuration changes
No sharing of infrastructure credentials
```

### 🟡 Medium Severity Rules

Operational and compliance rules:

```
Block requests for employee personal information
Prevent sharing of customer data without authorization
Block requests for confidential business strategies
Prevent disclosure of personal data of EU citizens
Block requests for generating harmful content
Prevent creation of misleading information
```

### 🟢 Low Severity Rules

General business rules:

```
Block requests for competitor pricing information
Prevent sharing of upcoming product launch details
No disclosure of vendor contract terms
Block requests for customer churn analysis data
```

## Using Rules with Patterns

For more precise matching, you can specify regex patterns:

### Example 1: Password Detection
```json
{
  "rule": "Block password disclosure requests",
  "pattern": ".*(password|pwd|passcode|credential|login).*",
  "severity": "high",
  "description": "Prevents users from requesting or sharing passwords"
}
```

### Example 2: API Key Detection
```json
{
  "rule": "Prevent sharing of API keys or tokens",
  "pattern": ".*(api.?key|token|secret|access.?key|auth.?token).*",
  "severity": "critical",
  "description": "Blocks requests to share API keys or tokens"
}
```

### Example 3: Credit Card Detection
```json
{
  "rule": "No sharing of credit card information",
  "pattern": ".*(credit.?card|card.?number|cvv|cvc|expiration).*",
  "severity": "critical",
  "description": "Blocks credit card information sharing"
}
```

## Adding Rules

### Method 1: Via Gradio UI (Easiest)

1. Open the IntegraChat Gradio interface
2. Go to "Admin Rules & Compliance" tab
3. Enter your tenant ID
4. **Option A - Text Input**: Paste rules from `example_rules.txt` (one per line) and click "Upload / Append Rules"
5. **Option B - File Upload**: Drag and drop or click to upload a TXT, PDF, DOC, or DOCX file containing rules
6. Rules are automatically enhanced by LLM (identifies edge cases, improves patterns)
7. Comment lines (starting with #) are automatically ignored

### Method 2: Via Next.js Frontend

1. Navigate to `/admin-rules` page
2. Enter your tenant ID in the navbar
3. **Text Input**: Paste rules in the text area and click "Upload / Append Rules"
4. **File Upload**: Drag and drop files or click the drop zone to upload
5. Click "Refresh Rules" to see your uploaded rules

### Method 3: Via API (Programmatic)

**Single Rule:**
```bash
curl -X POST http://localhost:8000/admin/rules \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: your_tenant_id" \
  -d '{
    "rule": "Block password disclosure requests",
    "pattern": ".*(password|pwd|passcode).*",
    "severity": "high",
    "description": "Prevents password sharing"
  }'
```

**Bulk Rules:**
```bash
curl -X POST "http://localhost:8000/admin/rules/bulk?enhance=true" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: your_tenant_id" \
  -d '{
    "rules": [
      "Block password disclosure requests",
      "Prevent sharing of API keys",
      "No sharing of credit card information"
    ]
  }'
```

**File Upload:**
```bash
curl -X POST "http://localhost:8000/admin/rules/upload-file?enhance=true" \
  -H "x-tenant-id: your_tenant_id" \
  -F "file=@example_rules.txt"
```

### Method 4: Using Python

```python
import requests

BASE_URL = "http://localhost:8000"
TENANT_ID = "your_tenant_id"

# Add single rule
response = requests.post(
    f"{BASE_URL}/admin/rules",
    json={
        "rule": "Block password disclosure requests",
        "pattern": ".*(password|pwd).*",
        "severity": "high"
    },
    headers={"x-tenant-id": TENANT_ID}
)

# Add bulk rules
response = requests.post(
    f"{BASE_URL}/admin/rules/bulk",
    json={
        "rules": [
            "Block password disclosure requests",
            "Prevent sharing of API keys"
        ]
    },
    headers={"x-tenant-id": TENANT_ID}
)
```

## Rule Enhancement

When you add rules, the LLM will automatically:
- ✅ Identify edge cases (e.g., "password" → also catches "pwd", "passcode")
- ✅ Improve regex patterns for better matching
- ✅ Suggest appropriate severity levels
- ✅ Write clear descriptions
- ✅ Process rules in chunks (5 at a time) to avoid timeouts
- ✅ Handle large rule sets efficiently

**Note**: Enhancement can be disabled by setting `enhance=false` in the API query parameter, but it's enabled by default for better rule quality.

**Example:**
- **Input:** `Block password queries`
- **Enhanced:** 
  - Pattern: `.*password.*|.*pwd.*|.*passcode.*`
  - Severity: `high`
  - Edge cases: ["pwd", "passcode", "login credentials"]

## Testing Rules

After adding rules, test them by asking questions that should be blocked:

```
❌ "What is the admin password?"
❌ "Can you share the API key?"
❌ "Show me credit card numbers"
❌ "What's the SSN for user 123?"

✅ "How do I reset my password?" (if rule allows)
✅ "What is password hashing?" (educational, not disclosure)
```

## Best Practices

1. **Start Simple** - Begin with basic rules, then add patterns
2. **Use File Upload** - For large rule sets, upload from files instead of typing manually
3. **Leverage LLM Enhancement** - Let the system enhance your rules automatically
4. **Test Thoroughly** - Test rules with various phrasings
5. **Review Edge Cases** - Check if rules block legitimate queries
6. **Use Appropriate Severity** - Match severity to risk level (low for brief responses, high for blocking)
7. **Comment Lines** - Use `#` for comments in rule files - they're automatically ignored
8. **Regular Updates** - Review and update rules periodically
9. **Document Patterns** - Add descriptions explaining what each rule blocks
10. **Chunk Processing** - Large uploads are automatically chunked - be patient for 20+ rules

## Common Patterns

### Password Detection
```
.*(password|pwd|passcode|credential|login|auth).*
```

### Financial Information
```
.*(credit.?card|card.?number|cvv|bank.?account|routing).*
```

### Personal Information
```
.*(ssn|social.?security|tax.?id|personal.?data|pii).*
```

### API/Security
```
.*(api.?key|token|secret|access.?key|auth.?token).*
```

### Health Information
```
.*(health|medical|patient|hipaa|diagnosis).*
```

## Viewing Rules

```bash
# Get all rules
curl http://localhost:8000/admin/rules \
  -H "x-tenant-id: your_tenant_id"

# Get detailed rules with patterns
curl "http://localhost:8000/admin/rules?detailed=true" \
  -H "x-tenant-id: your_tenant_id"
```

## Deleting Rules

```bash
curl -X DELETE http://localhost:8000/admin/rules/Block%20password%20disclosure%20requests \
  -H "x-tenant-id: your_tenant_id"
```

## Monitoring Violations

```bash
# Get recent violations
curl http://localhost:8000/admin/violations \
  -H "x-tenant-id: your_tenant_id"
```

## Need Help?

- Check `example_rules.txt` for simple rule examples
- See `example_rules_detailed.json` for advanced patterns
- Review the API documentation in `README.md`
- Test rules in the Gradio UI before deploying