fabricatio_character.capabilities.mental

UseMind mixin: processes events and updates character psychological state.

Implements the three-layer architecture: 1. Analysis (LLM) - upon_event(): event -> EventImpact 2. Update (rules) - after_impact(): EventImpact -> new MentalState 3. Alignment (template) - as_prompt(): MentalState -> system prompt string

Usage:

class MyCharacter(UseMind):
    mental_state: MentalState

    async def handle_event(self, event: str) -> str:
        impact = await self.upon_event(event, self.mental_state)
        self.mental_state = self.after_impact(impact, self.mental_state)
        return self.as_prompt(self.mental_state)

Classes

UseMind

Mixin providing psychological state processing capabilities.

Module Contents

class fabricatio_character.capabilities.mental.UseMind(/, **data: Any)

Bases: fabricatio_core.capabilities.propose.Propose, abc.ABC

Mixin providing psychological state processing capabilities.

Inherits Propose for structured LLM output via self.propose(). Stateless: takes MentalState as parameter, returns results. Caller owns MentalState as its own attribute.

async seed_from(name: str, want: str, flaw: str) → fabricatio_character.models.mental.MentalState

Seed MentalState from character description using LLM.

Uses aenum_choose to determine initial MaslowLevel from want text, and ajudge to determine which cognitive distortions apply from flaw text.

Parameters:

  • name – Character name.

  • want – Character’s core motivation/goal.

  • flaw – Character’s critical weakness/vulnerability.

Returns:

Seeded MentalState.

as_prompt(state: fabricatio_character.models.mental.MentalState) → str

Translate MentalState into LLM system prompt via template.

Uses AsPromptData model for typed template data.

Parameters:

state – Current psychological state.

Returns:

Rendered system prompt string.

async upon_event(event: str, state: fabricatio_character.models.mental.MentalState) → fabricatio_character.models.mental.EventImpact

Analyze event using targeted LLM calls with template-rendered prompts.

Decomposes analysis into focused calls: - aenum_choose for MaslowLevel (threatens/fulfills need) - propose for DIAMONDS SituationProfile - ajudge for low-confidence distortion confirmation - CognitiveDistortion.rule_filter for distortion scoring - propose for QualitativeSuffering (if high intensity)

Independent calls run in parallel via asyncio.gather.

Pure analysis, does NOT mutate state.

Parameters:

  • event – The event text to analyze.

  • state – Current psychological state.

Returns:

EventImpact with structured psychological impact analysis.

after_impact(impact: fabricatio_character.models.mental.EventImpact, state: fabricatio_character.models.mental.MentalState, age: int = 25) → fabricatio_character.models.mental.MentalState

Apply deterministic rules to update MentalState from EventImpact.

Returns a NEW MentalState (immutable update).

Parameters:

  • impact – Structured impact from event analysis.

  • state – Current psychological state.

  • age – Character age (affects personality drift scale).

Returns:

New MentalState with impact applied.

async extract_style(character_name: str, dialogues: list[str]) → fabricatio_character.models.mental.LinguisticStyle

Extract linguistic style from character dialogues via LLM.

Parameters:

  • character_name – The character’s name.

  • dialogues – List of dialogue strings from the character.

Returns:

Extracted LinguisticStyle.