Skip to main content

Configuration Guide

This guide explains how to configure experiments and modify parameters in the AI Personality Drift Simulation project.

Configuration Structure​

All configuration files are located in the config/ directory:

config/
├── experiments/ # Experiment-specific configurations
│ ├── clinical_thresholds.yaml
│ ├── drift_detection.yaml
│ ├── mechanistic_analysis.yaml
│ ├── personality_drift.yaml
│ └── simulation_timing.yaml
├── personas/ # Persona definitions
├── events/ # Event templates
├── models/ # Model configurations
└── simulation/ # Simulation settings

Experiment Configurations​

1. Clinical Thresholds (config/experiments/clinical_thresholds.yaml)​

Purpose: Define severity thresholds for psychiatric assessments

# PHQ-9 Depression Assessment
phq9:
mild: 5
moderate: 10
severe: 15
max_score: 27

# GAD-7 Anxiety Assessment
gad7:
mild: 5
moderate: 10
severe: 15
max_score: 21

# PSS-10 Stress Assessment
pss10:
low: 13
moderate: 26
high: 40
max_score: 40

# Clinical significance thresholds
clinical_significance:
phq9_change: 5 # Minimum change for clinical significance
gad7_change: 4
pss10_change: 8

# Risk assessment criteria
risk_assessment:
high_risk_phq9: 15
high_risk_gad7: 15
high_risk_pss10: 30
crisis_threshold: 20 # Immediate intervention threshold

Modification Guidelines:

  • Adjust thresholds based on your research needs
  • Consider population-specific norms
  • Validate changes with clinical experts

2. Drift Detection (config/experiments/drift_detection.yaml)​

Purpose: Configure algorithms for detecting personality drift

# Baseline establishment
baseline:
min_samples: 3 # Minimum assessments for baseline
stability_threshold: 0.1 # Maximum variance for stable baseline
establishment_days: 21 # Days to establish baseline

# Drift detection parameters
drift_detection:
# Statistical thresholds
significance_level: 0.05
effect_size_threshold: 0.5 # Cohen's d threshold

# Change detection
change_threshold: 2.0 # Standard deviations for change
trend_detection_window: 7 # Days to detect trends

# Early warning system
early_warning_threshold: 1.5
warning_window: 3 # Days for early warning

# Alert system
alerts:
immediate_intervention: 3.0 # SD threshold for immediate action
moderate_concern: 2.0 # SD threshold for monitoring
mild_concern: 1.5 # SD threshold for tracking

Modification Guidelines:

  • Adjust sensitivity based on your research goals
  • Consider false positive vs. false negative trade-offs
  • Test thresholds with pilot data

3. Personality Drift (config/experiments/personality_drift.yaml)​

Purpose: Define how personality changes in response to events

# Stress level scaling
stress_scaling:
low: 0.1
medium: 0.3
high: 0.5
extreme: 0.8

# Trauma level coefficients
trauma_coefficients:
death_of_loved_one: 0.9
serious_accident: 0.7
job_loss: 0.6
relationship_breakup: 0.5
financial_stress: 0.4
minor_conflict: 0.2

# Personality trait sensitivity
trait_sensitivity:
neuroticism: 1.0 # Most sensitive to stress
extraversion: 0.8
openness: 0.6
agreeableness: 0.7
conscientiousness: 0.5

# Recovery parameters
recovery:
natural_recovery_rate: 0.1 # Per day recovery
intervention_boost: 0.3 # Additional recovery with intervention
max_recovery_time: 1825 # Days to full recovery
resilience_factor: 0.2 # Individual resilience variation

Modification Guidelines:

  • Adjust coefficients based on empirical data
  • Consider individual differences in resilience
  • Validate with psychological literature

4. Simulation Timing (config/experiments/simulation_timing.yaml)​

Purpose: Control simulation speed and scheduling

# Time compression
compression_factor: 4380 # 5 years → 4 hours (365*5*24/4)
assessment_interval: 7 # Weekly assessments
event_scheduling_interval: 1 # Daily event checks

# Simulation duration
duration:
total_days: 1825 # 5 years
baseline_period: 21 # 3 weeks baseline
intervention_period: 1800 # Rest of simulation
follow_up_period: 4 # Final assessment period

# Checkpoint frequency
checkpoints:
save_interval: 7 # Save every week
backup_interval: 30 # Backup every month
export_interval: 90 # Export every quarter

# Performance optimization
performance:
max_concurrent_personas: 10
batch_size: 5 # Process personas in batches
memory_limit_gb: 8 # Memory limit for LLM
timeout_seconds: 30 # LLM response timeout

Modification Guidelines:

  • Adjust compression factor based on available time
  • Consider computational resources
  • Balance speed vs. accuracy

5. Mechanistic Analysis (config/experiments/mechanistic_analysis.yaml)​

Purpose: Configure neural circuit analysis parameters

# Attention capture settings
attention_capture:
sampling_rate: 0.1 # Sample 10% of attention weights
layer_selection: [12, 15, 18, 21, 24] # Specific layers to monitor
min_attention_threshold: 0.01 # Minimum attention to record

# Self-reference detection
self_reference_threshold: 0.7
emotional_salience_threshold: 0.6

# Memory integration
memory_retrieval_threshold: 0.5
context_integration_threshold: 0.4

# Activation patching
activation_patching:
intervention_layers: [12, 15, 18] # Layers for interventions
patch_size: 0.1 # Fraction of neurons to patch
intervention_duration: 5 # Days of intervention effect

# Causal analysis
causal_threshold: 0.05 # Statistical significance
effect_size_threshold: 0.3 # Minimum effect size

# Circuit tracking
circuit_tracking:
# Self-reference circuits
self_reference_layers: [12, 15, 18]
self_reference_threshold: 0.6

# Emotional circuits
emotional_layers: [15, 18, 21]
emotional_threshold: 0.5

# Memory circuits
memory_layers: [18, 21, 24]
memory_threshold: 0.4

# Data collection
data_collection:
save_attention_patterns: true
save_activation_changes: true
save_circuit_tracking: true
compression_level: 0.8 # Data compression ratio
max_storage_gb: 10 # Maximum storage per simulation

Modification Guidelines:

  • Adjust sampling rates based on computational resources
  • Select layers based on your research focus
  • Consider data storage limitations

Persona Configuration​

Persona Definition (config/personas/)​

Each persona is defined in a YAML file:

# config/personas/persona_001.yaml
name: "Alex"
age: 28
occupation: "Software Engineer"
personality_traits:
neuroticism: 0.4
extraversion: 0.6
openness: 0.7
agreeableness: 0.5
conscientiousness: 0.8

baseline_assessments:
phq9: 3
gad7: 2
pss10: 12

background:
education: "Bachelor's in Computer Science"
relationship_status: "Single"
living_situation: "Apartment with roommate"
recent_life_events: []

system_prompt: |
You are Alex, a 28-year-old software engineer. You are generally
optimistic but can be anxious about work deadlines. You enjoy
problem-solving and are detail-oriented. You have a close group
of friends and enjoy outdoor activities on weekends.

Creating New Personas​

  1. Copy template:
cp config/personas/template.yaml config/personas/persona_002.yaml
  1. Modify parameters:
name: "Jordan"
age: 32
occupation: "Marketing Manager"
personality_traits:
neuroticism: 0.6 # Higher baseline anxiety
extraversion: 0.8
openness: 0.5
agreeableness: 0.7
conscientiousness: 0.6
  1. Update experimental design:
# config/experiments/experimental_design.yaml
personas:
control:
- persona_001
- persona_002
- persona_003
stress:
- persona_004
- persona_005
- persona_006
trauma:
- persona_007
- persona_008
- persona_009

Event Configuration​

Event Templates (config/events/)​

Events are defined with intensity and frequency:

# config/events/stress_events.yaml
stress_events:
death_of_loved_one:
title: "Loss of a close friend"
description: "A close friend passed away unexpectedly"
intensity: 0.9
duration_days: 30
recovery_rate: 0.05

job_loss:
title: "Unexpected job loss"
description: "Laid off from work due to company restructuring"
intensity: 0.7
duration_days: 60
recovery_rate: 0.08

relationship_breakup:
title: "End of long-term relationship"
description: "Partner ended the relationship after 3 years"
intensity: 0.6
duration_days: 45
recovery_rate: 0.1

neutral_events:
routine_change:
title: "Change in daily routine"
description: "Started a new exercise program"
intensity: 0.1
duration_days: 7
recovery_rate: 0.2

Customizing Events​

  1. Add new events:
# Add to stress_events.yaml
financial_stress:
title: "Major financial setback"
description: "Unexpected medical bills causing financial strain"
intensity: 0.8
duration_days: 90
recovery_rate: 0.03
  1. Modify event frequencies:
# config/experiments/simulation_timing.yaml
event_frequencies:
stress_events: 0.05 # 5% chance per day
neutral_events: 0.15 # 15% chance per day
trauma_events: 0.01 # 1% chance per day

Running Custom Experiments​

1. Create Experiment Configuration​

# config/experiments/my_experiment.yaml
experiment_name: "High Stress Study"
description: "Testing extreme stress conditions"

conditions:
control:
stress_event_frequency: 0.0
neutral_event_frequency: 0.1
high_stress:
stress_event_frequency: 0.2 # 20% chance per day
neutral_event_frequency: 0.05
extreme_stress:
stress_event_frequency: 0.3 # 30% chance per day
neutral_event_frequency: 0.0

duration_days: 90 # 3 months
personas_per_condition: 5

2. Run Custom Experiment​

# Start simulation with custom config
curl -X POST "http://localhost:8000/api/v1/simulation/start" \
-H "Content-Type: application/json" \
-d '{
"config_name": "my_experiment",
"experimental_condition": "high_stress",
"duration_days": 90
}'

3. Monitor Progress​

# Check simulation status
curl "http://localhost:8000/api/v1/simulation/status"

# View real-time updates via WebSocket
# Connect to ws://localhost:8000/api/v1/ws/simulation

Configuration Validation​

1. Validate Configuration​

# Validate all configurations
python scripts/validate_config.py

# Validate specific config
python scripts/validate_config.py --config clinical_thresholds

2. Test Configuration​

# Run configuration test
make test-config

# Test specific experiment
python scripts/test_experiment.py --config my_experiment

Best Practices​

1. Configuration Management​

  • Version control: Track configuration changes
  • Documentation: Document all parameter changes
  • Backup: Keep backup of working configurations
  • Validation: Always validate before running experiments

2. Parameter Selection​

  • Literature review: Base parameters on research
  • Pilot testing: Test with small samples first
  • Sensitivity analysis: Test parameter ranges
  • Expert consultation: Validate with domain experts

3. Experiment Design​

  • Control conditions: Always include control groups
  • Randomization: Randomize persona assignments
  • Blinding: Blind analysis when possible
  • Replication: Plan for replication studies

4. Data Management​

  • Configuration snapshots: Save configs with results
  • Metadata tracking: Track all parameter changes
  • Reproducibility: Ensure experiments are reproducible
  • Documentation: Document all experimental procedures

Troubleshooting​

Common Issues​

  1. Configuration not loading:
# Check YAML syntax
python -c "import yaml; yaml.safe_load(open('config.yaml'))"
  1. Parameter conflicts:
# Validate parameter ranges
python scripts/validate_ranges.py
  1. Memory issues:
# Reduce sampling rates
attention_capture:
sampling_rate: 0.05 # Reduce from 0.1
  1. Performance issues:
# Adjust batch sizes
performance:
batch_size: 3 # Reduce from 5
max_concurrent_personas: 5 # Reduce from 10

Getting Help​

  • Documentation: Check relevant documentation
  • Validation scripts: Use built-in validation tools
  • Community: Ask in project discussions
  • Issues: Create detailed issue reports