# Rules Management Guide

The Rules Management API enables you to create, manage, and apply reusable behavior rules across your AI assistants, users, models, and other entities in the Freddy platform.

## What are Rules?

Rules are reusable instructions or guidelines that define how AI models should behave, respond, or process information. They can be attached to multiple entities and applied with configurable priority and character limits.

## Key Use Cases

### 1. Consistent Behavior Across Assistants

Apply the same professional communication standards to all customer-facing assistants in your organization.

### 2. Safety and Compliance

Enforce safety guidelines and compliance requirements across all AI interactions.

### 3. Brand Voice and Style

Maintain consistent brand voice, tone, and formatting across different AI applications.

### 4. Context-Specific Rules

Apply different rules based on the entity type (assistant, user, model) with priority-based ordering.

### 5. Collaborative Rule Management

Share rules with team members using three-tier access control (owner, edit, view).

## Rule Categories

- **Safety**: Safety and compliance rules
- **Professional**: Professional conduct and tone
- **Creative**: Creative writing and style
- **Technical**: Technical guidelines and constraints
- **Custom**: Organization-specific rules


## Rule Types

- **Behavior**: Behavioral guidelines
- **Guardrails**: Safety and boundary rules
- **Formatting**: Formatting and style rules
- **Context**: Context-specific rules
- **Content Policy**: Content policy rules
- **Constraint**: Constraint rules


## How Rules Work

### Entity Attachments

Rules can be attached to multiple entity types:

- **assistant** - Apply rules to specific AI assistants
- **vector_store** - Apply rules to vector stores for RAG contexts
- **user** - Apply rules to individual users
- **model** - Apply rules to specific AI models
- **organization** - Apply rules organization-wide


Each attachment is independent and can have its own priority and character limit settings.

### Priority System

Rules are applied in priority order (1-100 scale, higher first):

- **90-100**: Critical safety rules (applied first)
- **70-89**: High priority (compliance, security)
- **50-69**: Standard priority (default range)
- **30-49**: Low priority
- **1-29**: Optional/supplementary rules


When multiple rules have the same priority, they are ordered by attachment timestamp.

### Character Limits

Each attachment can have a character limit (100-50,000) to control how much rule content is included in the context. This helps manage:

- Token usage and costs
- Context window size
- Performance optimization


### Active/Inactive Status

Rules and attachments can be toggled active/inactive without deletion:

- Temporarily disable rules for testing
- Seasonal or conditional rule activation
- A/B testing different rule configurations


## Access Control

### Three-Tier System

**Owner**

- Full control including delete
- Manage access rights
- Modify content and settings


**Edit**

- View and modify rule content
- Update rule settings
- Cannot delete or manage access


**View**

- Read-only access
- Cannot modify or delete


## Public vs Private Rules

### Private Rules

- Organization-specific
- Only accessible to organization members
- Default setting


### Public Rules

- Discoverable by all authenticated users
- Can be used across organizations
- Great for sharing best practices


## Getting Started

### Quick Start: Create Rule with Attachments

The fastest way to deploy a rule is to create it with attachments in a single request:


```bash
curl -X POST https://api.aitronos.com/v1/organizations/org_123/rules \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Communication",
    "content": "Always maintain a professional and courteous tone in all communications. Use formal language and avoid slang.",
    "description": "Ensures professional communication standards",
    "category": "professional",
    "rule_type": "behavior",
    "scope": "organization",
    "is_active": true,
    "attachments": [
      {
        "entity_type": "assistant",
        "entity_id": "asst_abc123",
        "priority": 80,
        "character_limit": 1000
      },
      {
        "entity_type": "vector_store",
        "entity_id": "vs_def456",
        "priority": 70
      }
    ]
  }'
```

This creates the rule and attaches it to multiple entities atomically in a single transaction.

### Step-by-Step Workflow

#### 1. Create a Basic Rule


```bash
curl -X POST https://api.aitronos.com/v1/organizations/org_123/rules \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Safety Guidelines",
    "content": "Never share customer personal information. Always verify identity before discussing account details.",
    "category": "safety",
    "rule_type": "guardrails"
  }'
```

#### 2. Attach to Entities Later


```bash
curl -X POST https://api.aitronos.com/v1/rules/rule_abc/attachments \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "assistant",
    "entity_id": "asst_123",
    "priority": 80,
    "character_limit": 2000
  }'
```

#### 3. Grant Access to Team Members


```bash
curl -X POST https://api.aitronos.com/v1/rules/rule_abc/access \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_teammate",
    "access_level": "edit"
  }'
```

#### 4. List Rules for an Entity


```bash
curl https://api.aitronos.com/v1/rules/entities/assistant/asst_123/rules \
  -H "X-API-Key: $FREDDY_API_KEY"
```

## Common Workflows

### Workflow 1: Deploy Rule to Multiple Assistants

Create a rule and attach it to multiple assistants in one request:


```bash
curl -X POST https://api.aitronos.com/v1/organizations/org_123/rules \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Service Standards",
    "content": "Be empathetic, professional, and solution-focused...",
    "category": "professional",
    "attachments": [
      {"entity_type": "assistant", "entity_id": "asst_support", "priority": 80},
      {"entity_type": "assistant", "entity_id": "asst_sales", "priority": 75},
      {"entity_type": "assistant", "entity_id": "asst_billing", "priority": 80}
    ]
  }'
```

### Workflow 2: Update Rule Content

Update rule content (increments version automatically):


```bash
curl -X PUT https://api.aitronos.com/v1/organizations/org_123/rules/rule_abc \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated rule content with new guidelines..."
  }'
```

### Workflow 3: Temporarily Disable a Rule

Disable without deleting:


```bash
curl -X PUT https://api.aitronos.com/v1/organizations/org_123/rules/rule_abc \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

### Workflow 4: Find All Rules for an Assistant


```bash
curl https://api.aitronos.com/v1/rules/entities/assistant/asst_123/rules \
  -H "X-API-Key: $FREDDY_API_KEY"
```

### Workflow 5: Search Rules by Category


```bash
curl "https://api.aitronos.com/v1/organizations/org_123/rules?category=safety&is_active=true" \
  -H "X-API-Key: $FREDDY_API_KEY"
```

## Best Practices

### Rule Design

- Keep rules focused and specific (single responsibility)
- Use descriptive names that indicate purpose
- Add detailed descriptions for team collaboration
- Set appropriate categories and types for filtering
- Keep content under 10,000 characters for optimal performance


### Priority Management

- **90-100**: Critical safety and compliance rules
- **70-89**: High priority behavior and guardrails
- **50-69**: Standard guidelines and formatting
- **30-49**: Optional style preferences
- **1-29**: Supplementary context


### Attachment Strategy

- Use character limits to control token usage
- Attach rules during creation for atomic deployment
- Use entity-specific priorities for fine-grained control
- Toggle inactive for temporary changes


### Access Management

- Grant minimum necessary access level
- Maintain at least one owner per rule
- Use edit access for content collaborators
- Use view access for stakeholders
- Regularly audit access rights


### Performance Optimization

- Use character limits to manage context size
- Filter by category/type to reduce list sizes
- Use pagination for large rule sets
- Toggle inactive instead of deleting
- Monitor usage statistics


### Version Control

- Document changes in description field
- Test updates in staging before production
- Use duplicate feature for major changes
- Monitor version numbers for tracking


## API Reference

For detailed API documentation, see:

- [Rules API Reference](/docs/api-reference/rules/introduction)
- [Rule Object](/docs/api-reference/objects/rule-object)


## Rate Limits

- 100 requests per minute per user
- 1000 requests per hour per organization


## Support

For questions or issues with Rules Management:

- Visit [Freddy Hub](https://freddy-hub.aitronos.com)
- Check the [API Reference](/docs/api-reference/rules/introduction)