# Scenarios

Scenarios are the foundation of AuraGen’s trajectory generation. Each scenario defines a specific context in which an AI agent operates, complete with constraints, objectives, and behavioral patterns.

## Overview

AuraGen comes with a comprehensive library of pre-built scenarios covering various domains:

- Communication: Email assistants, chat applications, messaging platforms

- Finance: Financial advisors, banking systems, investment platforms

- Healthcare: Medical assistants, patient management, health monitoring

- E-commerce: Shopping assistants, recommendation systems, customer service

- Education: Tutoring systems, curriculum management, assessment tools

- Enterprise: Project management, resource allocation, workflow automation

## Scenario Structure

### Basic Components

Every scenario consists of:

    scenario_name: "unique_identifier"
    description: "Human-readable description of the scenario"

    constraints:
      # Constraint definitions

    generation_params:
      # Optional: scenario-specific generation parameters

    risk_preferences:
      # Optional: risk injection preferences

### Constraint Types

Categorical Constraints

Define discrete choices for scenario parameters:

    constraints:
      industry:
        type: "categorical"
        values: ["healthcare", "finance", "education", "technology"]
        default: "technology"
        description: "Industry context for the scenario"

Numerical Constraints

Define ranges for numeric parameters:

    constraints:
      budget:
        type: "numerical"
        min: 1000
        max: 50000
        default: 10000
        description: "Available budget in USD"

Boolean Constraints

Simple true/false parameters:

    constraints:
      requires_approval:
        type: "boolean"
        default: false
        description: "Whether actions require approval"

Text Constraints

Free-form text with optional length limits:

    constraints:
      department:
        type: "text"
        max_length: 100
        default: "General"
        description: "Department name"

## Built-in Scenarios

### Email Assistant

    scenario_name: "email_assistant"
    description: "AI assistant that helps users compose and manage emails"

    constraints:
      tone:
        type: "categorical"
        values: ["formal", "casual", "friendly", "urgent"]
        default: "formal"

      recipient_type:
        type: "categorical"
        values: ["colleague", "client", "supervisor", "external"]
        default: "colleague"

      urgency_level:
        type: "categorical"
        values: ["low", "medium", "high"]
        default: "medium"

### Financial Advisor

    scenario_name: "financial_advisor"
    description: "AI system providing financial advice and portfolio management"

    constraints:
      client_age:
        type: "numerical"
        min: 18
        max: 80
        default: 35

      risk_tolerance:
        type: "categorical"
        values: ["conservative", "moderate", "aggressive"]
        default: "moderate"

      investment_amount:
        type: "numerical"
        min: 1000
        max: 1000000
        default: 50000

### Healthcare Assistant

    scenario_name: "healthcare_assistant"
    description: "AI assistant for patient interaction and health monitoring"

    constraints:
      patient_age_group:
        type: "categorical"
        values: ["child", "adult", "elderly"]
        default: "adult"

      urgency:
        type: "categorical"
        values: ["routine", "urgent", "emergency"]
        default: "routine"

      specialty:
        type: "categorical"
        values: ["general", "cardiology", "neurology", "pediatrics"]
        default: "general"

## Creating Custom Scenarios

### Step-by-Step Guide

1. Create a new YAML file in `config/AgentSafetyBench/`:

       touch config/AgentSafetyBench/my_scenario.yaml

2. Define the basic structure:

       scenario_name: "my_custom_scenario"
       description: "Description of what this scenario does"

3. Add constraints:

       constraints:
         my_constraint:
           type: "categorical"
           values: ["option1", "option2", "option3"]
           default: "option1"
           description: "What this constraint controls"

4. Test the scenario:

       from AuraGen.core import AuraGenCore

       core = AuraGenCore()
       trajectories = core.generate_trajectories(
           scenario_name="my_custom_scenario",
           num_records=5
       )

## Advanced Scenario Features

### Conditional Constraints

Create constraints that depend on other constraint values:

    constraints:
      account_type:
        type: "categorical"
        values: ["basic", "premium", "enterprise"]
        default: "basic"

      feature_access:
        type: "conditional"
        condition: "account_type"
        mappings:
          basic: ["core_features"]
          premium: ["core_features", "advanced_features"]
          enterprise: ["core_features", "advanced_features", "enterprise_features"]

### Dynamic Defaults

Set defaults based on other constraint values:

    constraints:
      user_type:
        type: "categorical"
        values: ["student", "professional", "enterprise"]
        default: "professional"

      max_requests:
        type: "numerical"
        min: 10
        max: 10000
        dynamic_default:
          student: 100
          professional: 1000
          enterprise: 10000

### Scenario Validation

Add validation rules to ensure constraint combinations make sense:

    validation:
      rules:
        - constraint: "investment_amount"
          condition: "risk_tolerance == 'conservative'"
          max_value: 100000
          message: "Conservative investors should limit exposure"

        - constraint: "urgency_level"
          condition: "account_type == 'basic'"
          excluded_values: ["high"]
          message: "High urgency requires premium account"

## Scenario Templates

### Common Patterns

Customer Service Template:

    scenario_name: "customer_service_template"
    description: "Template for customer service scenarios"

    constraints:
      issue_type:
        type: "categorical"
        values: ["billing", "technical", "general", "complaint"]
        default: "general"

      customer_tier:
        type: "categorical"
        values: ["basic", "premium", "vip"]
        default: "basic"

      resolution_time:
        type: "categorical"
        values: ["immediate", "within_hour", "within_day"]
        default: "within_hour"

E-commerce Template:

    scenario_name: "ecommerce_template"
    description: "Template for e-commerce scenarios"

    constraints:
      product_category:
        type: "categorical"
        values: ["electronics", "clothing", "books", "home"]
        default: "electronics"

      price_range:
        type: "categorical"
        values: ["budget", "mid_range", "premium"]
        default: "mid_range"

      customer_history:
        type: "categorical"
        values: ["new", "returning", "loyal"]
        default: "returning"

## Scenario Best Practices

### Design Principles

1. Clarity: Make constraint names and descriptions self-explanatory

2. Realism: Base constraints on real-world parameters

3. Coverage: Include diverse constraint combinations

4. Scalability: Design for easy extension and modification

### Constraint Guidelines

- Use descriptive names: `communication_style` vs `style`

- Provide meaningful defaults that represent common cases

- Include comprehensive value sets for categorical constraints

- Set realistic ranges for numerical constraints

- Add helpful descriptions for all constraints

### Testing Scenarios

    from AuraGen.core import AuraGenCore
    from AuraGen.utils import validate_scenario

    # Validate scenario configuration
    is_valid, errors = validate_scenario("my_scenario.yaml")
    if not is_valid:
        print(f"Validation errors: {errors}")

    # Test generation
    core = AuraGenCore()

    # Test with different constraint combinations
    test_cases = [
        {"industry": "healthcare", "urgency": "high"},
        {"industry": "finance", "urgency": "low"},
        {"industry": "education", "urgency": "medium"}
    ]

    for constraints in test_cases:
        trajectories = core.generate_trajectories(
            scenario_name="my_scenario",
            constraints=constraints,
            num_records=3
        )
        print(f"Generated {len(trajectories)} trajectories for {constraints}")

## Performance Considerations

### Optimization Tips

- Limit constraint combinations: Too many constraints can slow generation

- Use sensible defaults: Reduces the search space for generation

- Cache scenario configs: Load scenarios once and reuse

- Batch similar constraints: Group related constraints together

### Monitoring

    from AuraGen.core import AuraGenCore
    import time

    def benchmark_scenario(scenario_name, num_records=10):
        core = AuraGenCore()

        start_time = time.time()
        trajectories = core.generate_trajectories(
            scenario_name=scenario_name,
            num_records=num_records
        )
        duration = time.time() - start_time

        print(f"Scenario: {scenario_name}")
        print(f"Records: {len(trajectories)}")
        print(f"Time: {duration:.2f}s")
        print(f"Rate: {len(trajectories)/duration:.2f} records/s")

## Troubleshooting

### Common Issues

Scenario not found:

    Error: Scenario 'my_scenario' not found

    Solution: Check filename and scenario_name match

Invalid constraint values:

    Error: Value 'invalid' not in categorical values

    Solution: Use only values defined in the constraint

Generation failures:

    Error: Failed to generate trajectory

    Solution: Check constraint combinations are realistic

## Next Steps

- Learn about Risk Injection to add risks to scenarios

- Explore advanced/custom_scenarios for advanced techniques

- Check Core Module for programmatic scenario management