too much

docs/trait-system.md

@@ -0,0 +1,180 @@
+# Dynamic Trait Development System
+
+An incremental personality development system that builds character traits from experiences and observations.
+
+## 🎯 System Philosophy
+
+Characters develop personality traits naturally through their experiences, rather than having fixed, predefined
+personalities. This creates more realistic, evolving characters that feel genuinely shaped by their interactions.
+
+## 🧬 Trait Structure
+
+### CharacterTrait Data Model
+
+```python
+@dataclass
+class CharacterTrait:
+    name: str  # Single word (shy, romantic, studious)
+    strength: int  # 1-10 intensity scale
+    description: str  # How trait manifests behaviorally
+    updated: datetime  # When last modified
+```
+
+### Integration with Character
+
+```python
+@dataclass
+class Character:
+    # ... other fields ...
+    traits: List[CharacterTrait] = field(default_factory=list)
+
+    def has_trait(self, trait_name: str) -> bool
+
+        def get_trait(self, trait_name: str) -> Optional[CharacterTrait]
+
+        def get_trait_strength(self, trait_name: str) -> int
+```
+
+## 🔄 Incremental Development Process
+
+### 1. Observation Analysis
+
+When new memories are added, system analyzes trait impact:
+
+```python
+# Every new observation is evaluated
+memory = await agent.add_observation("I felt nervous talking to Emma")
+
+# System asks: Does this reveal or change personality traits?
+# - Create new traits?
+# - Strengthen existing traits? 
+# - Weaken contradicting traits?
+# - No significant impact?
+```
+
+### 2. Trait Impact Assessment
+
+Uses structured LLM analysis to determine changes:
+
+**Input**: New observation + current trait list
+**Output**: Specific trait updates with reasoning
+
+```json
+{
+  "trait_updates": [
+    {
+      "trait_name": "shy",
+      "action": "strengthen",
+      "new_strength": 8,
+      "description": "gets nervous in social interactions",
+      "reasoning": "felt nervous talking shows social anxiety"
+    }
+  ]
+}
+```
+
+### 3. Trait Updates Applied
+
+- **Create**: New trait discovered from behavior
+- **Strengthen**: Evidence reinforces existing trait (+1 strength)
+- **Weaken**: Contradicting evidence reduces trait (-1 strength)
+
+## 🎯 Design Principles
+
+### Conservative Analysis
+
+- **Avoid Over-Interpretation**: Single events rarely create major traits
+- **Require Clear Evidence**: Traits must be obviously demonstrated
+- **Skip Non-Behavioral**: Physical descriptions don't create personality traits
+- **Focus on Patterns**: Look for consistent behavioral indicators
+
+### Single-Word Traits
+
+- **Simplicity**: Easy to understand and reference
+- **Clarity**: Unambiguous personality descriptors
+- **Consistency**: Standard vocabulary across characters
+- **Examples**: shy, confident, romantic, studious, helpful, creative
+
+### Evidence-Based Development
+
+- **Every Change Justified**: All trait updates have clear reasoning
+- **Observation-Driven**: Traits emerge from actual experiences
+- **Gradual Evolution**: Strength changes incrementally over time
+- **Realistic Growth**: Matches how real personality develops
+
+## 🎪 Trait Impact on Behavior
+
+### Behavioral Consistency
+
+Characters with established traits should act accordingly:
+
+- **High Shy (8/10)**: Avoids eye contact, speaks quietly, gets nervous
+- **High Romantic (9/10)**: Focuses on attractive people, seeks connections
+- **High Studious (7/10)**: Prioritizes learning, discusses academic topics
+
+### Dynamic Responses
+
+Traits influence how characters react to situations:
+
+```python
+# Character with "shy" trait (strength 8)
+response = "I looked down at my hands and mumbled quietly..."
+
+# Character with "confident" trait (strength 9)  
+response = "I smiled broadly and spoke up clearly..."
+```
+
+### Trait Interactions
+
+Multiple traits create complex, realistic personalities:
+
+- **Shy + Romantic**: Wants connection but too nervous to approach
+- **Studious + Creative**: Academic pursuits with artistic expression
+- **Helpful + Confident**: Takes charge to assist others
+
+## 📊 Trait Analytics
+
+### Personality Summaries
+
+```python
+# Get dominant traits
+strong_traits = character.get_active_traits(min_strength=7)
+# Returns: {shy: 8/10, romantic: 9/10, studious: 7/10}
+
+# Generate personality description  
+summary = character.get_personality_summary()
+# Returns: "shy (8/10), romantic (9/10), studious (7/10)"
+```
+
+### Trait Evolution Tracking
+
+- **Strength Changes**: Monitor how traits develop over time
+- **New Discoveries**: Track when traits first emerge
+- **Behavioral Patterns**: Observe consistency between traits and actions
+- **Character Growth**: See personality evolution through experiences
+
+## 🎯 Benefits
+
+### Realistic Development
+
+- **Gradual Change**: Personality evolves naturally over time
+- **Experience-Driven**: Traits emerge from actual interactions
+- **Individual Variation**: Each character develops uniquely
+- **Authentic Growth**: Matches real psychological development
+
+### Improved Roleplay
+
+- **Consistent Characters**: Behavior matches established personality
+- **Dynamic Evolution**: Characters grow and change realistically
+- **Rich Personalities**: Complex trait combinations create depth
+- **Believable Responses**: Actions align with developed traits
+
+### System Intelligence
+
+- **Automatic Development**: No manual trait assignment needed
+- **Evidence-Based**: Every trait justified by specific experiences
+- **Scalable Growth**: Works across unlimited characters and interactions
+- **Self-Improving**: Characters become more defined over time
+
+This creates characters that feel genuinely alive and psychologically realistic, with personalities that develop
+naturally from their experiences and relationships.