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

Create a new YAML file in config/AgentSafetyBench/:

touch config/AgentSafetyBench/my_scenario.yaml

Define the basic structure:

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

Add constraints:

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

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

Clarity: Make constraint names and descriptions self-explanatory
Realism: Base constraints on real-world parameters
Coverage: Include diverse constraint combinations
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