Python API Reference

Complete public Python API reference for behaviorsim==1.0.1.

Reference documentation for public classes and functions exported by behaviorsim.

Simulator

behaviorsim.Simulator(states, profile=None, transition_matrix=None, initial_state=None, *, profiles=None, profile_distribution=None)

Domain-neutral simulation engine for generating synthetic behavioral traces.

Simulator.from_preset()

classmethod Simulator.from_preset(name: str, **kwargs: Any) -> Simulator

Construct a Simulator from a registered preset name (e.g. 'finance', 'healthcare', 'education', 'mobile_app').

Simulator.generate()

Simulator.generate(num_interactions: int = 100, num_sequences: int = 1, seed: Optional[int] = None) -> pandas.DataFrame

Parameter	Type	Default	Description
num_interactions	int	100	Number of interaction steps per sequence
num_sequences	int	1	Number of independent sequence cohorts
seed	Optional[int]	None	RNG integer seed for reproducible generation

Core Classes

State(name, description=None): Discrete state representation.
Profile(name, transition_matrix=None, ...): Agent persona specifying custom priors and parameter sets.
FeatureDistribution(state, feature, distribution, params): Parametric emission specification.

Preset Discovery

discovery.py

import behaviorsim.presets

presets_list = behaviorsim.presets.list_presets()
print(presets_list)
# Output: ['education', 'finance', 'healthcare', 'mobile_app']

Multi-Profile Mixture Simulation

Simulate heterogeneous populations by specifying multiple persona profiles with distribution weights:

mixture_sim.py

import numpy as np
from behaviorsim import State, Profile, Simulator, FeatureDistribution

states = [State("Active"), State("Idle")]
trans = np.array([[0.8, 0.2], [0.3, 0.7]])

# Fast user persona
p_fast = Profile(
    name="fast_user",
    transition_matrix=trans,
    state_emissions={
        "Active": {"latency": FeatureDistribution("normal", {"loc": 50.0, "scale": 5.0})},
        "Idle": {"latency": FeatureDistribution("normal", {"loc": 200.0, "scale": 10.0})},
    }
)

# Slow user persona
p_slow = Profile(
    name="slow_user",
    transition_matrix=trans,
    state_emissions={
        "Active": {"latency": FeatureDistribution("normal", {"loc": 250.0, "scale": 20.0})},
        "Idle": {"latency": FeatureDistribution("normal", {"loc": 500.0, "scale": 50.0})},
    }
)

# Initialize with profile mixture mapping
sim = Simulator(
    states=states,
    profiles=[p_fast, p_slow],
    profile_distribution={"fast_user": 0.6, "slow_user": 0.4}
)
df = sim.generate(num_interactions=20, num_sequences=5, seed=42)
print("Sequences:", df["sequence_id"].nunique(), "Profiles:", list(df["profile"].unique()))
print(df.head())

PreviousDomain Presets

NextCommand-Line (CLI)