fabricatio-character

MIT

Character profile generation for the Fabricatio LLM agent framework — structured persona cards with AI-driven composition and template-based rendering.

Installation

pip install fabricatio[character]
# or
uv pip install fabricatio[character]

For the full Fabricatio suite:

pip install fabricatio[full]

Overview

fabricatio-character provides a CharacterCard model capturing a character as they currently are: stable identity (name, roles list, activated role, motivation) plus the mutable state of the moment (appearance, behavior, vulnerability, location, physical condition, mood) — ten required fields that together define a complete narrative persona and its present situation, plus a required, possibly empty metric map of tracked numerical stats (hp, energy, reputation, ...). The CharacterCompose capability plugs into Fabricatio's Propose pipeline to generate cards via LLM from natural-language requirements, with built-in Pydantic validation.

Generated cards are renderable through the Fabricatio template system (as_prompt()) and persistable (PersistentAble) for checkpoint/restore workflows.

Models

CharacterCard

A character as they currently are. The identity fields (name, roles, activated_role, want) change slowly; the state fields describe how the character is right now and evolve as the story progresses. The ten text fields are required and non-empty; metric is required but may be empty when no stats are tracked. roles must contain at least one entry and activated_role must be one of the entries in roles.

• SketchedAble — instantiation from natural-language descriptions via LLM
• Named — equality by name field
• AsPrompt — renders as a prompt string via the configured template (render_character_card_template)
• PersistentAble — save/load to disk for workflow checkpointing

Capabilities

CharacterCompose

Mixin that extends Propose to generate CharacterCard instances from requirement strings.

from fabricatio_character.capabilities.character import CharacterCompose

class StoryAgent(CharacterCompose, ...):
    pass

compose_characters(requirements, **kwargs)

• Accepts a single str or a list[str] of requirements
• Returns a single CharacterCard (or None) for a string, or a list[CharacterCard | None] for multiple requirements
• Passes **kwargs through to Fabricatio's validation layer (ValidateKwargs), enabling strict validation, retry policies, and custom post-processing
• Delegates to Propose.propose() for LLM-driven composition

Utilities

dump_card(*card: CharacterCard) -> str

Joins one or more CharacterCard objects as prompt strings, separated by newlines. Convenience wrapper around CharacterCard.as_prompt().

from fabricatio_character.utils import dump_card

prompt = dump_card(hero, villain)

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.character] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.character] in pyproject.toml, or via FABRICATIO_EXT__CHARACTER__<FIELD_UPPER> environment variables.

[ext.character]
mind_personality_high = 70.0

Access at runtime: from fabricatio_character.config import character_config.

Dependencies

• fabricatio-core — Propose, SketchedAble, Named, CONFIG
• fabricatio-capabilities — AsPrompt, PersistentAble, ValidateKwargs

Usage

Generating a Single Character

from fabricatio_character.capabilities.character import CharacterCompose

class Agent(CharacterCompose, ...):
    pass

agent = Agent()
card = await agent.compose_characters(
    "a grizzled detective haunted by an old case"
)
if card:
    print(card.as_prompt())

Batch Generation with Validation

cards = await agent.compose_characters(
    [
        "a brilliant but arrogant surgeon",
        "a quiet archivist who notices everything",
        "a cheerful smuggler with a heart of gold",
    ]
)
for c in cards:
    print(c.name, "-", c.activated_role)

Rendering and Persistence

from fabricatio_character.utils import dump_card

# Render all cards as prompts
prompt_text = dump_card(*cards)

# Persist individual cards (via PersistentAble)
card.persist("checkpoints/characters/")

Mental Engine

MentalState models how a character changes: a stable identity layer (Big Five personality, CBT distortion tendencies, linguistic style, age), a volatile per-event emotional layer (emotion, somatic response, active distortion, DIAMONDS situation), an accumulated Maslow need layer, and irreversible traumas.

The state object is self-sufficient and mirrors the CharacterCard conventions:

Usage

from fabricatio_character.capabilities.character import CharacterCompose
from fabricatio_character.capabilities.mental import UseMind
from fabricatio_character.utils import dump_card


class StoryTeller(CharacterCompose, UseMind, ...):
    """Writes in-character; keeps psychology evolving per event."""


agent = StoryTeller("storyteller")
card = await agent.compose_characters("Hamlet, prince of Denmark")
mind = await agent.seed_from(card, age=30)

mind = await agent.react("The ghost of your father accuses your uncle.", mind)
prompt = dump_card(card) + "\n\n" + mind.as_prompt()
reply = await agent.aask("What do you say to your mother?", system_prompt=prompt)

mind.persist("checkpoints/minds/")

age lives on the state (CharacterMind.age) and scales personality drift: child 3.0×, adolescent 1.5×, young adult 0.5×, adult 0.2× (mind_age_brackets).

Research Foundations

License

MIT — see LICENSE