fabricatio_character.models.mental

Mental model data models for dynamic character psychological state.

Complete psychological state model covering: - BigFiveProfile: 5-dimensional personality (Costa & McCrae, 1992) - CognitiveDistortion: CBT distortion tendency weights (Beck, 1976) - SomaticState: embodied perception (EFT-CoT, Du et al., 2026) - QualitativeSuffering: irreversible trauma (Emotional Cost Functions) - LinguisticStyle: decoupled expression patterns (TTM, Zhan et al., 2025) - CharacterMind: stable identity (personality + cognition + language) - EmotionalState: volatile per-event state (emotion + body + active distortion) - NeedState: Maslow hierarchy tracking (Maslow, 1943) - MentalState: composite of all layers - EventImpact: LLM-generated impact from event analysis

Classes

`Emotion`	Recognized emotion types.
`Distortion`	Cognitive distortion types from CBT framework.
`PersonalityFlag`	Personality trait condition flags for prompt injection.
`MaslowLevel`	Maslow's hierarchy of needs. Higher value = higher need.
`BigFiveDimension`	Big Five personality dimension names.
`SituationDimension`	DIAMONDS situational dimensions (Rauthmann et al., 2014).
`SituationProfile`	8-dimensional situational classification per event.
`BigFiveProfile`	Big Five personality traits. Each dimension 0-100.
`CognitiveDistortion`	CBT cognitive distortion tendency weights for a character.
`LinguisticStyle`	Decoupled language expression patterns. Extracted from character dialogues.
`HeartRate`	Heart rate states.
`Breathing`	Breathing patterns.
`MuscleTension`	Muscle tension levels.
`FacialExpression`	Facial expression states.
`VoiceQuality`	Voice quality states.
`SomaticState`	Body sensations derived from emotion type and intensity.
`QualitativeSuffering`	Irreversible trauma that permanently reshapes character.
`CharacterMind`	Stable psychological identity. Seeded once from CharacterCard, drifts slowly.
`EmotionalState`	Volatile per-event emotional and physical state.
`NeedState`	Maslow need hierarchy tracking. Accumulated over time.
`MentalState`	Complete psychological state. All theories represented.
`EventImpact`	LLM-generated impact from event analysis.
`DistortionAnalysis`	CBT distortion analysis output — used by LLM distortion judgment path.
`EventContext`	Typed context for event analysis template rendering.
`SufferingSummary`	Suffering entry for template rendering.
`AsPromptData`	Typed data for system prompt template rendering.

Module Contents

class fabricatio_character.models.mental.Emotion

Bases: enum.StrEnum

Recognized emotion types.

NEUTRAL

FEAR

ANXIETY

ANGER

RAGE

SADNESS

GRIEF

JOY

HAPPINESS

DISGUST

CONTEMPT

class fabricatio_character.models.mental.Distortion

Bases: enum.StrEnum

Cognitive distortion types from CBT framework.

CATASTROPHIZING

BLACK_AND_WHITE

PERSONALIZATION

EMOTIONAL_REASONING

SHOULD_THINKING

class fabricatio_character.models.mental.PersonalityFlag

Bases: enum.StrEnum

Personality trait condition flags for prompt injection.

HIGH_NEUROTICISM

LOW_AGREEABLENESS

HIGH_EXTRAVERSION

LOW_EXTRAVERSION

HIGH_CONSCIENTIOUSNESS

HIGH_OPENNESS

class fabricatio_character.models.mental.MaslowLevel

Bases: enum.IntEnum

Maslow’s hierarchy of needs. Higher value = higher need.

PHYSIOLOGICAL

SAFETY

BELONGING

ESTEEM

SELF_ACTUALIZATION

class fabricatio_character.models.mental.BigFiveDimension

Bases: enum.StrEnum

Big Five personality dimension names.

OPENNESS

CONSCIENTIOUSNESS

EXTRAVERSION

AGREEABLENESS

NEUROTICISM

class fabricatio_character.models.mental.SituationDimension

Bases: enum.StrEnum

DIAMONDS situational dimensions (Rauthmann et al., 2014).

DUTY

INTELLECT

ADVERSITY

MATING

POSITIVITY

NEGATIVITY

DECEPTION

SOCIALITY

class fabricatio_character.models.mental.SituationProfile(/, **data: Any)

Bases: fabricatio_core.models.generic.ProposedAble

8-dimensional situational classification per event.

Each dimension scored 0.0-1.0 by LLM extraction.

duty: float = None

intellect: float = None

adversity: float = None

mating: float = None

positivity: float = None

negativity: float = None

deception: float = None

sociality: float = None

as_vector() → list[float]

top_dimension() → SituationDimension

class fabricatio_character.models.mental.BigFiveProfile(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Big Five personality traits. Each dimension 0-100.

openness: float = None: Curiosity vs practicality.

conscientiousness: float = None: Self-discipline vs flexibility.

extraversion: float = None: Outgoing vs reserved.

agreeableness: float = None: Cooperative vs competitive.

neuroticism: float = None: Anxious vs emotionally stable.

as_vector() → list[float]: Return personality as a 5D vector [O, C, E, A, N].

distance_to(other: BigFiveProfile) → float: Euclidean distance between two personality profiles.

personality_flag(flag: PersonalityFlag) → bool: Check a personality condition flag against this profile.

class fabricatio_character.models.mental.CognitiveDistortion(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

CBT cognitive distortion tendency weights for a character.

catastrophizing: float = None: Amplify threat.

black_and_white: float = None: No middle ground.

personalization: float = None: Self-blame.

emotional_reasoning: float = None: Feelings = facts.

should_thinking: float = None: Rigid expectations.

top(n: int = 1) → list[Distortion]: Return top-N most likely distortion types.

rule_filter(situation: SituationProfile) → dict[str, float]

Compute distortion scores boosted by DIAMONDS situational dimensions.

Base = character tendency weight. Boost = dim_score * boost_value from config. Returns dict with Distortion enum value strings as keys.

class fabricatio_character.models.mental.LinguisticStyle(/, **data: Any)

Bases: fabricatio_core.models.generic.ProposedAble

Decoupled language expression patterns. Extracted from character dialogues.

preferences: str = '': Natural language description of style tendencies.

common_pronouns: List[str] = None: Preferred pronouns.

common_modals: List[str] = None: Preferred modal verbs.

common_adjectives: List[str] = None: Preferred adjectives and descriptors.

style_references: List[str] = None: Exemplary utterances from the character for style reference.

class fabricatio_character.models.mental.HeartRate

Bases: enum.StrEnum

Heart rate states.

NORMAL

ELEVATED

RACING

class fabricatio_character.models.mental.Breathing

Bases: enum.StrEnum

Breathing patterns.

NORMAL

SLOW

SHALLOW

RAPID

class fabricatio_character.models.mental.MuscleTension

Bases: enum.StrEnum

Muscle tension levels.

RELAXED

TENSE

RIGID

TREMBLING

class fabricatio_character.models.mental.FacialExpression

Bases: enum.StrEnum

Facial expression states.

NEUTRAL

FROWN

WIDE_EYES

BLUSH

class fabricatio_character.models.mental.VoiceQuality

Bases: enum.StrEnum

Voice quality states.

STEADY

TREMBLING

FAST

QUIET

class fabricatio_character.models.mental.SomaticState(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Body sensations derived from emotion type and intensity.

heart_rate: HeartRate: Heart rate state.

breathing: Breathing: Breathing pattern.

muscle_tension: MuscleTension: Muscle tension level.

facial_expression: FacialExpression: Facial expression.

voice: VoiceQuality: Voice quality.

classmethod from_emotion(emotion: Emotion, intensity: float) → SomaticState: Create SomaticState from emotion type and intensity via config mapping.

class fabricatio_character.models.mental.QualitativeSuffering(/, **data: Any)

Bases: fabricatio_core.models.generic.ProposedAble

Irreversible trauma that permanently reshapes character.

what_was_lost: str: What was taken from the character.

the_void: str: The gap it created.

how_it_changed_me: str: How it reshaped the character.

anticipatory_dread: float = None: Fear of similar situations (0-100).

class fabricatio_character.models.mental.CharacterMind(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Stable psychological identity. Seeded once from CharacterCard, drifts slowly.

Contains personality, cognitive tendencies, and linguistic style. Changes only through slow drift over many events.

character_name: str: Name of the character this mind belongs to.

personality: BigFiveProfile = None: Stable personality traits.

cognitive_tendencies: CognitiveDistortion = None: Character’s cognitive distortion tendency weights.

linguistic_style: LinguisticStyle = None: Decoupled language expression patterns.

class fabricatio_character.models.mental.EmotionalState(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Volatile per-event emotional and physical state.

Replaced (not mutated) every event. Contains the current emotion, its physical manifestation, and which cognitive distortion is active.

emotion: Emotion: Current dominant emotion.

intensity: float = None: Emotion intensity 0-100.

somatic: SomaticState = None: Current body sensations.

active_distortion: Distortion | None = None: Currently activated cognitive distortion (per-event, volatile).

latest_situation: SituationProfile | None = None: DIAMONDS profile from the latest event (volatile, for prompt injection).

class fabricatio_character.models.mental.NeedState(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Maslow need hierarchy tracking. Accumulated over time.

current_level: MaslowLevel: Current dominant need level.

satisfied: List[MaslowLevel] = None: Already satisfied need levels.

counters: dict[MaslowLevel, int] = None: Accumulated satisfaction events per level.

class fabricatio_character.models.mental.MentalState(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Complete psychological state. All theories represented.

Three layers: - mind: stable identity (personality, cognition, language) - emotion: volatile per-event state (emotion, body, active distortion) - needs: accumulated Maslow hierarchy Plus sufferings (permanent trauma history).

mind: CharacterMind: Stable psychological identity.

emotion: EmotionalState = None: Volatile per-event emotional state.

needs: NeedState = None: Maslow need hierarchy tracking.

sufferings: List[QualitativeSuffering] = None: Accumulated irreversible traumas.

classmethod from_card(card: fabricatio_character.models.character.CharacterCard) → MentalState

Seed MentalState from a CharacterCard with minimal defaults.

Sets character name and default values. For intelligent seeding with LLM-driven need/distortion classification, use UseMind.seed_from().

drop_level(threatened: MaslowLevel) → MentalState: Drop to or below the threatened need level.

accumulate_satisfaction(fulfilled: MaslowLevel) → MentalState: Accumulate satisfaction count; rise level when threshold met.

class fabricatio_character.models.mental.EventImpact(/, **data: Any)

Bases: fabricatio_core.models.generic.ProposedAble

LLM-generated impact from event analysis.

Contains all fields the LLM determines: emotion, personality drift, distortion activation, and need transitions.

emotion: Emotion | None = None: Triggered emotion name.

emotion_intensity: float = None: Emotion intensity 0-100.

personality_shift: dict[BigFiveDimension, float] = None

5.0}).

Type:: BigFive dimension deltas (e.g. {BigFiveDimension.NEUROTICISM

triggers_distortion: Distortion | None = None: Triggered cognitive distortion type.

threatens_need: MaslowLevel | None = None: Need level threatened by the event.

fulfills_need: MaslowLevel | None = None: Need level fulfilled by the event.

created_suffering: QualitativeSuffering | None = None: Suffering created from high-intensity emotional events.

situation: SituationProfile | None = None: DIAMONDS situation profile from event analysis.

class fabricatio_character.models.mental.DistortionAnalysis(/, **data: Any)

Bases: fabricatio_core.models.generic.ProposedAble

CBT distortion analysis output — used by LLM distortion judgment path.

triggered_distortion: Distortion | None = None

internal_monologue: str = ''

reasoning: str = ''

class fabricatio_character.models.mental.EventContext(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Typed context for event analysis template rendering.

event: str: The event text to analyze.

emotion: Emotion: Current emotion.

emotion_intensity: float = 0.0: Emotion intensity 0-100.

current_need: MaslowLevel: Current MaslowLevel.

as_template_data() → dict[str, str | float | bool | int]: Convert to dict with string values for template rendering.

class fabricatio_character.models.mental.SufferingSummary(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Suffering entry for template rendering.

what_was_lost: str

the_void: str

how_it_changed_me: str

class fabricatio_character.models.mental.AsPromptData(/, **data: Any)

Bases: fabricatio_core.models.generic.Base

Typed data for system prompt template rendering.

personality_rules: list[str]

need_description: str

emotion: str

emotion_intensity: str

emotion_high: bool

emotion_mid: bool

cognitive_bias: str | None = None

bias_example: str = ''

has_somatic: bool = False

somatic_heart_rate: str = 'normal'

somatic_breathing: str = 'normal'

somatic_muscle_tension: str = 'relaxed'

somatic_facial_expression: str = 'neutral'

somatic_voice: str = 'steady'

has_sufferings: bool = False

sufferings: list[SufferingSummary] = None

has_linguistic: bool = False

linguistic_preferences: str = ''

linguistic_pronouns: list[str] | None = None

linguistic_modals: list[str] | None = None

has_situation: bool = False

top_situation_dimension: str = ''

situation_adversity: float = 0.0

situation_negativity: float = 0.0

as_template_data() → dict[str, str | float | bool | int | list | None]: Convert to dict for TEMPLATE_MANAGER.render_template().