TraitDefinition

A composable modifier that can be applied to any persona.

Usage

TraitDefinition()

Traits act as mixins — they add constraints, expertise, tools, avoid topics, or tags to an existing PersonaDefinition without replacing its core identity. Multiple traits can be stacked.

Parameters

name: str: Machine-readable identifier (e.g., "security_focused").
display_name: str = "": Human-readable label (e.g., "Security-Focused").
category: str = "general": Grouping category (e.g., "tone", "compliance").
description: str = "": One-line summary of what this trait adds.
constraints: list[str] = list(): Constraints appended to the persona’s constraints list.
critical_constraints: list[str] = list(): Critical constraints appended to the persona’s list.
expertise_extra: str = "": Text appended to the persona’s expertise field.
avoid_topics: list[str] = list(): Topics appended to the persona’s avoid_topics list.
tools: list[str] = list(): Tools appended to the persona’s tools list.
tags: list[str] = list(): Tags appended to the persona’s tags list.
temperature: float | None = None: If set, overrides the persona’s temperature.
task_context_extra: str = "": Text appended to the persona’s task_context.
output_format: list[str] = list(): Output format directives appended to the persona’s list.
final_emphasis: str = "": If set, replaces the persona’s final_emphasis.
metadata: dict[str, Any] = dict(): Arbitrary metadata for the trait.

Examples

Create a trait programmatically:

import talk_box as tb

sec = tb.create_trait(
    "security_focused",
    description="Adds security-related constraints.",
    constraints=["Flag potential security issues"],
    critical_constraints=["Never suggest insecure patterns"],
)

Apply a trait to a persona:

persona = tb.get_persona("code_reviewer")
secure_reviewer = tb.apply_trait(persona, sec)
secure_reviewer.constraints  # includes the security constraint