Generation Engine Overview

How Simulator executes the simulation loop and generates sequence traces.

The Simulator class orchestrates state progression, feature sampling, and trace aggregation.

Execution Loop Mechanics

At each interaction step t in a sequence:

Evaluate dynamic transition rules against recent interaction history.
Sample the next state s_t based on transition probabilities.
For the active state, sample configured feature distributions.
Evaluate outcome labels or anomaly flags.
Record the interaction record with sequence and step identifiers.

Multi-Sequence Generation

Pass num_sequences to generate multiple independent agent cohorts:

multi_seq.py

from behaviorsim import Simulator

# Load built-in education preset
sim = Simulator.from_preset("education")

# Generates 100 sequences of 50 interactions each (total 5,000 interaction rows)
df = sim.generate(num_interactions=50, num_sequences=100, seed=123)
print(f"Generated {len(df)} total rows across {df['sequence_id'].nunique()} sequences.")

Export Options

Since generate() returns a pandas DataFrame, you can immediately export traces using standard pandas methods:

export.py

from behaviorsim import Simulator

sim = Simulator.from_preset("education")
df = sim.generate(num_interactions=50, num_sequences=2, seed=42)

# Export generated traces to CSV and JSON
df.to_csv("traces.csv", index=False)
df.to_json("traces.json", orient="records")

# Apache Parquet export (requires: pip install pyarrow)
try:
    df.to_parquet("traces.parquet", index=False)
except ImportError:
    pass

PreviousTransitions & Dynamics

NextDomain Presets