behaviorsim_rs/
lib.rs

1//! Behavioral Pathways
2//!
3//! Domain-agnostic library for modeling individual psychology and social dynamics.
4//!
5//! This library provides tools for simulating how entities (humans, animals)
6//! think, feel, relate, and change over time using established psychological
7//! frameworks.
8//!
9//! # Core Concepts
10//!
11//! - **Entity**: A living individual with psychological state
12//! - **StateValue**: A dimension with base value, delta, and decay behavior
13//! - **Species**: Determines lifespan and psychological time scaling
14//! - **LifeStage**: Developmental stage affecting plasticity and event impact
15//! - **IndividualState**: Aggregate container for all psychological state
16//!
17//! # Psychological Frameworks
18//!
19//! - **PAD Model**: Pleasure-Arousal-Dominance for affect representation
20//! - **HEXACO**: Six-factor personality model
21//! - **ITS**: Joiner's Interpersonal Theory of Suicide for mental health
22//! - **PPCT**: Bronfenbrenner's Person-Process-Context-Time model
23//!
24//! # Example
25//!
26//! ```
27//! use behaviorsim_rs::entity::EntityBuilder;
28//! use behaviorsim_rs::enums::{Species, MoodPath, StatePath};
29//!
30//! // Create an entity with the builder
31//! let entity = EntityBuilder::new()
32//!     .species(Species::Human)
33//!     .age(behaviorsim_rs::Duration::years(30))
34//!     .build()
35//!     .unwrap();
36//!
37//! assert_eq!(entity.species(), &Species::Human);
38//!
39//! // Access state via typed paths
40//! let valence = entity.get_effective(StatePath::Mood(MoodPath::Valence));
41//! ```
42//!
43//! # Consumer API Model
44//!
45//! The consumer API is timestamp-based:
46//! - Create a `Simulation` with a reference date
47//! - Add entities with an anchor timestamp (their known state at a point in time)
48//! - Query state at any timestamp via `state_at(timestamp)`
49//! - Each query computes fresh from declared data (no persistence)
50//!
51//! Internal methods like `advance()`, `regress_by()`, `apply_decay()`, and
52//! `reverse_decay()` are implementation details used by `state_at()` and
53//! should not be called directly by consumers.
54
55pub mod context;
56pub mod entity;
57pub mod enums;
58pub mod event;
59pub mod memory;
60pub(crate) mod processor;
61pub mod relationship;
62pub mod simulation;
63pub mod state;
64pub mod types;
65
66// Re-export entity types at crate root
67pub use entity::{AffectiveState, Entity, EntityBuildError, EntityBuilder, PhysiologicalState};
68
69// Re-export commonly used enums at crate root
70pub use enums::{
71    ActionStakes, AlertSeverity, AlertTrigger, ApparentGender, ApparentRace, Attribution,
72    AttributionStability, BirthEra, ChronosystemPath, ContextPath, Direction, DirectionalPath,
73    DispositionPath,
74    EducationPath, Emotion, EventPayload, EventType, ExosystemPath, FamilyPath, HealthcarePath,
75    HexacoPath, HistoricalEventType, HistoricalScope, InteractionTopic, LifeDomain, LifeStage,
76    LossType, MacrosystemPath, MentalHealthPath, MicrosystemPath, MoodPath, NeedsPath,
77    NeighborhoodPath, PersonCharacteristicsPath, PersonalityProfile, PolicyArea, RealizationType,
78    RelPath, RelationshipSchema, ReligiousPath, ReversibilityError, ReversibilityResult, SharedPath,
79    SocialCognitionPath, SocialPath, Species, SpiralType, StatePath, SupportType, TraumaType,
80    TrustPath, VisibleTrait, WeaponType, WorkPath,
81};
82
83// Re-export context types at crate root
84pub use context::{
85    passes_proximal_process_gate, ChronosystemContext, CohortEffects, CriticalPeriod,
86    CulturalOrientation, EcologicalContext, EducationContext, ExosystemContext, FamilyContext,
87    FamilyRole, HealthcareContext, HistoricalPeriod, InstitutionalStructure, InteractionProfile,
88    MacrosystemConstraintSet, MacrosystemContext, MesosystemCache, MesosystemLinkage, Microsystem,
89    MicrosystemType, NeighborhoodContext, NonNormativeEvent, NormativeTransition,
90    ParentWorkQuality, ProximalProcessGateError, ReligiousContext, SocialContext, TurningPoint,
91    TurningPointDomain, WorkContext, CulturalShift, INTERACTION_COMPLEXITY_THRESHOLD,
92    INTERACTION_FREQUENCY_THRESHOLD, INTERACTION_RECIPROCITY_THRESHOLD,
93};
94
95// NOTE: Processor module contains internal implementation details.
96// Consumers should use the Simulation API (state_at) instead of calling
97// processor functions directly.
98
99// Re-export simulation types at crate root
100pub use simulation::{
101    AnchoredEntity, ComputedState, EntityQueryHandle, RegressionQuality, Simulation,
102    SimulationBuildError, SimulationBuilder, TimestampedEvent, TimestampedRelationship,
103};
104
105// Re-export commonly used state types at crate root
106pub use state::{
107    age_plasticity, apply_formative_modifiers, combined_plasticity, cumulative_in_direction,
108    effective_base_at, saturation_factor, sensitive_period_modifier, species_plasticity_modifier,
109    stability_coefficient, trait_modifier, BaseShiftRecord, Disposition, EntityModelConfig, Hexaco,
110    is_ac_present, DemandCharacteristics, IndividualState, ITSRiskLevel, MentalHealth, Mood, Needs,
111    PersonCharacteristics, SocialCognition, StateValue, AC_PRESENCE_THRESHOLD, CUMULATIVE_CAP,
112    HOPELESSNESS_THRESHOLD, MAX_SINGLE_EVENT_SHIFT, PB_PRESENT_THRESHOLD, SATURATION_CONSTANT,
113    SETTLING_DAYS, SEVERE_SHIFT_RETENTION, SEVERE_SHIFT_THRESHOLD, TB_PRESENT_THRESHOLD,
114};
115
116// Re-export relationship types at crate root
117pub use relationship::{
118    AntecedentDirection, AntecedentType, DirectionalDimensions, InteractionPattern, PerceivedRisk,
119    Relationship, RelationshipError, RelationshipStage, SharedDimensions, TrustAntecedent,
120    TrustContext, TrustDecision, TrustworthinessFactors,
121};
122
123// Re-export event types at crate root
124pub use event::{
125    arousal_weight_for_species, compute_arousal_modulated_salience, Event, EventBuildError,
126    EventBuilder, AROUSAL_CEILING, AROUSAL_THRESHOLD, AROUSAL_WEIGHT_ANIMAL, AROUSAL_WEIGHT_HUMAN,
127    AROUSAL_WEIGHT_ROBOTIC, EXTREME_AROUSAL_IMPAIRMENT, NEGATIVITY_BIAS_MULTIPLIER,
128};
129
130// Re-export commonly used types at crate root
131pub use types::{
132    duration_to_timestamp, timestamp_to_duration, Alert, Duration, EntityId, EventId, GroupId,
133    MemoryId, MicrosystemId, RelationshipId, RelationshipSlot, Timestamp, TimestampParseError,
134};
behaviorsim_rs/lib.rs

behaviorsim_rs/
lib.rs
