behaviorsim-rs 0.7.0

//! Behavioral Pathways
//!
//! Domain-agnostic library for modeling individual psychology and social dynamics.
//!
//! This library provides tools for simulating how entities (humans, animals)
//! think, feel, relate, and change over time using established psychological
//! frameworks.
//!
//! # Core Concepts
//!
//! - **Entity**: A living individual with psychological state
//! - **StateValue**: A dimension with base value, delta, and decay behavior
//! - **Species**: Determines lifespan and psychological time scaling
//! - **LifeStage**: Developmental stage affecting plasticity and event impact
//! - **IndividualState**: Aggregate container for all psychological state
//!
//! # Psychological Frameworks
//!
//! - **PAD Model**: Pleasure-Arousal-Dominance for affect representation
//! - **HEXACO**: Six-factor personality model
//! - **ITS**: Joiner's Interpersonal Theory of Suicide for mental health
//! - **PPCT**: Bronfenbrenner's Person-Process-Context-Time model
//!
//! # Example
//!
//! ```
//! use behaviorsim_rs::entity::EntityBuilder;
//! use behaviorsim_rs::enums::{Species, MoodPath, StatePath};
//!
//! // Create an entity with the builder
//! let entity = EntityBuilder::new()
//!     .species(Species::Human)
//!     .age(behaviorsim_rs::Duration::years(30))
//!     .build()
//!     .unwrap();
//!
//! assert_eq!(entity.species(), &Species::Human);
//!
//! // Access state via typed paths
//! let valence = entity.get_effective(StatePath::Mood(MoodPath::Valence));
//! ```
//!
//! # Consumer API Model
//!
//! The consumer API is timestamp-based:
//! - Create a `Simulation` with a reference date
//! - Add entities with an anchor timestamp (their known state at a point in time)
//! - Query state at any timestamp via `state_at(timestamp)`
//! - Each query computes fresh from declared data (no persistence)
//!
//! Internal methods like `advance()`, `regress_by()`, `apply_decay()`, and
//! `reverse_decay()` are implementation details used by `state_at()` and
//! should not be called directly by consumers.

pub mod context;
pub mod entity;
pub mod enums;
pub mod event;
pub mod memory;
pub(crate) mod processor;
pub mod relationship;
pub mod simulation;
pub mod state;
pub mod types;

// Re-export entity types at crate root
pub use entity::{AffectiveState, Entity, EntityBuildError, EntityBuilder, PhysiologicalState};

// Re-export commonly used enums at crate root
pub use enums::{
    ActionStakes, AlertSeverity, AlertTrigger, ApparentGender, ApparentRace, Attribution,
    AttributionStability, BirthEra, ChronosystemPath, ContextPath, Direction, DirectionalPath,
    DispositionPath,
    EducationPath, Emotion, EventPayload, EventType, ExosystemPath, FamilyPath, HealthcarePath,
    HexacoPath, HistoricalEventType, HistoricalScope, InteractionTopic, LifeDomain, LifeStage,
    LossType, MacrosystemPath, MentalHealthPath, MicrosystemPath, MoodPath, NeedsPath,
    NeighborhoodPath, PersonCharacteristicsPath, PersonalityProfile, PolicyArea, RealizationType,
    RelPath, RelationshipSchema, ReligiousPath, ReversibilityError, ReversibilityResult, SharedPath,
    SocialCognitionPath, SocialPath, Species, SpiralType, StatePath, SupportType, TraumaType,
    TrustPath, VisibleTrait, WeaponType, WorkPath,
};

// Re-export context types at crate root
pub use context::{
    passes_proximal_process_gate, ChronosystemContext, CohortEffects, CriticalPeriod,
    CulturalOrientation, EcologicalContext, EducationContext, ExosystemContext, FamilyContext,
    FamilyRole, HealthcareContext, HistoricalPeriod, InstitutionalStructure, InteractionProfile,
    MacrosystemConstraintSet, MacrosystemContext, MesosystemCache, MesosystemLinkage, Microsystem,
    MicrosystemType, NeighborhoodContext, NonNormativeEvent, NormativeTransition,
    ParentWorkQuality, ProximalProcessGateError, ReligiousContext, SocialContext, TurningPoint,
    TurningPointDomain, WorkContext, CulturalShift, INTERACTION_COMPLEXITY_THRESHOLD,
    INTERACTION_FREQUENCY_THRESHOLD, INTERACTION_RECIPROCITY_THRESHOLD,
};

// NOTE: Processor module contains internal implementation details.
// Consumers should use the Simulation API (state_at) instead of calling
// processor functions directly.

// Re-export simulation types at crate root
pub use simulation::{
    AnchoredEntity, ComputedState, EntityQueryHandle, RegressionQuality, Simulation,
    SimulationBuildError, SimulationBuilder, TimestampedEvent, TimestampedRelationship,
};

// Re-export commonly used state types at crate root
pub use state::{
    age_plasticity, apply_formative_modifiers, combined_plasticity, cumulative_in_direction,
    effective_base_at, saturation_factor, sensitive_period_modifier, species_plasticity_modifier,
    stability_coefficient, trait_modifier, BaseShiftRecord, Disposition, EntityModelConfig, Hexaco,
    is_ac_present, DemandCharacteristics, IndividualState, ITSRiskLevel, MentalHealth, Mood, Needs,
    PersonCharacteristics, SocialCognition, StateValue, AC_PRESENCE_THRESHOLD, CUMULATIVE_CAP,
    HOPELESSNESS_THRESHOLD, MAX_SINGLE_EVENT_SHIFT, PB_PRESENT_THRESHOLD, SATURATION_CONSTANT,
    SETTLING_DAYS, SEVERE_SHIFT_RETENTION, SEVERE_SHIFT_THRESHOLD, TB_PRESENT_THRESHOLD,
};

// Re-export relationship types at crate root
pub use relationship::{
    AntecedentDirection, AntecedentType, DirectionalDimensions, InteractionPattern, PerceivedRisk,
    Relationship, RelationshipError, RelationshipStage, SharedDimensions, TrustAntecedent,
    TrustContext, TrustDecision, TrustworthinessFactors,
};

// Re-export event types at crate root
pub use event::{
    arousal_weight_for_species, compute_arousal_modulated_salience, Event, EventBuildError,
    EventBuilder, AROUSAL_CEILING, AROUSAL_THRESHOLD, AROUSAL_WEIGHT_ANIMAL, AROUSAL_WEIGHT_HUMAN,
    AROUSAL_WEIGHT_ROBOTIC, EXTREME_AROUSAL_IMPAIRMENT, NEGATIVITY_BIAS_MULTIPLIER,
};

// Re-export commonly used types at crate root
pub use types::{
    duration_to_timestamp, timestamp_to_duration, Alert, Duration, EntityId, EventId, GroupId,
    MemoryId, MicrosystemId, RelationshipId, RelationshipSlot, Timestamp, TimestampParseError,
};