gmarth/LivingAgents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

too much

Browse Source
This commit is contained in:
Alexander Thiess
2025-09-02 04:41:06 +02:00
parent 45eb2b8bc5
commit 793213a834
19 changed files with 955 additions and 805 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/README.md Normal file
View File

@@ -0,0 +1,53 @@
# Living Agents - Character Development System
A sophisticated AI-powered character development system featuring memory-based agents with dynamic personality evolution
based on Stanford's "Generative Agents" research.
## 🎯 Project Goals
- Create believable AI characters that remember past interactions
- Implement dynamic personality development based on experiences
- Build characters that evolve naturally through their experiences
- Provide an interactive CLI tool for testing and developing characters
## 🏗️ System Architecture
The system consists of several interconnected components:
1. **Character Agents** - AI entities with memory and personality
2. **Memory Stream** - Stanford-inspired memory architecture
3. **Prompt Management** - Centralized, templated prompt system
4. **Character Explorer** - CLI tool for testing character development
5. **Trait System** - Dynamic personality development
6. **LLM Connector** - Flexible backend supporting any OpenAI-compatible API
## 🚀 Quick Start
1. Set up environment variables in `.env`
2. Create character templates in YAML format
3. Run the character explorer CLI to interact with agents
4. Observe personality development over time
## 📁 Project Structure
```
character_templates/ # YAML character definition files
living_agents/ # Core agent system
├── character_agent.py # Main character agent implementation
├── memory_stream.py # Memory architecture
├── prompts/ # LLM prompt templates and JSON schemas
├── datatypes.py # Data structures and models
├── prompt_manager.py # Template management system
└── llmagent.py # LLM integration wrapper
llm_connector/ # LLM backend abstraction
character_explorer.py # CLI tool for testing characters
```
## 🎭 Key Features
- **Memory-Based Conversations**: Characters remember and reference past interactions
- **Dynamic Traits**: Personality develops incrementally from experiences
- **Structured Outputs**: JSON schemas for reliable LLM responses
- **Template System**: Easy character creation from YAML files
- **Flexible LLM Backend**: Support for any OpenAI-compatible API endpoint
- **CLI Testing Tool**: Interactive character exploration and development

117
docs/character-agents.md Normal file
View File

@@ -0,0 +1,117 @@
# Character Agent System
Character agents are the core AI entities that combine memory, personality, and conversational ability into believable
characters that evolve through their experiences.
## 🎭 Agent Architecture
### Core Components
1. **Memory Stream**: Stanford-inspired memory architecture
2. **Character Data**: Structured personality and relationship info
3. **LLM Integration**: Natural language processing and generation
4. **Trait System**: Dynamic personality development
5. **Response Generation**: Context-aware conversation handling
### Character Creation Process
1. **Template Loading**: YAML files define initial memories
2. **Memory Initialization**: Observations, reflections, and plans loaded
3. **Importance Scoring**: All memories rated for significance
4. **Character Extraction**: LLM generates structured character data
5. **Agent Ready**: Fully functional roleplay partner
## 📝 Character Templates
### YAML Structure
```yaml
observations:
- "My name is Alice and I am 23 years old"
- "I study Victorian literature at university"
- "I spilled coffee yesterday and felt embarrassed"
reflections:
- "I have romantic feelings for Emma (evidence: daily visits, heart racing)"
- "I am naturally shy in social situations (evidence: nervous with strangers)"
plans:
- "I want to work up courage to talk to Emma"
- "I need to finish my thesis chapter this week"
```
### Memory Types in Templates
**Observations**: Factual experiences and basic information
- Identity facts (name, age, occupation)
- Recent experiences and events
- Relationship interactions
- Physical descriptions and traits
**Reflections**: Character insights and self-understanding
- Personality trait recognition
- Relationship feelings and dynamics
- Behavioral pattern awareness
- Values and belief formation
**Plans**: Future intentions and goals
- Short-term objectives
- Long-term dreams and aspirations
- Relationship goals
- Personal development aims
## 🎯 Response Generation
### Context Building Process
1. **Query Analysis**: Understand what user is asking
2. **Memory Retrieval**: Find relevant memories using smart scoring
3. **Context Assembly**: Combine character info + relevant memories
4. **Prompt Construction**: Use template system for consistency
5. **LLM Generation**: Natural language response in character
6. **Memory Update**: Store new experience from interaction
### Response Style
- **First Person Past Tense**: "I looked up and smiled nervously..."
- **Character Consistency**: Responses match established personality
- **Memory Integration**: References past experiences naturally
- **Emotional Authenticity**: Shows appropriate feelings and reactions
## 🔄 Character Development
### Dynamic Personality Growth
Characters evolve through experience:
1. **New Experiences**: Each interaction creates memories
2. **Trait Analysis**: System evaluates personality impact
3. **Trait Updates**: Strengths/weaknesses adjust over time
4. **Reflection Generation**: Insights emerge from patterns
5. **Behavioral Consistency**: Future responses reflect growth
### Trait System
- **Incremental Development**: Traits strengthen/weaken with evidence
- **Evidence-Based**: Every trait change linked to specific experiences
- **Single-Word Names**: Simple, clear personality descriptors
- **Strength Ratings**: 1-10 scale for trait intensity
- **Dynamic Descriptions**: How traits manifest in behavior
## 🔮 Future Vision: Multi-Agent Interactions
### Planned Features
The system is designed with future multi-agent capabilities in mind:
- Characters will be able to interact with each other
- Conversations will create memories for all participants
- Relationship dynamics will develop naturally
- Information will spread through character networks
- Emergent social behaviors will arise from interactions
Currently, the focus is on perfecting single-agent character development and ensuring each character becomes genuinely
complex and believable through their individual growth.

87
docs/memory-system.md Normal file
View File

@@ -0,0 +1,87 @@
# Memory Architecture
The memory system is inspired by Stanford's "Generative Agents" research, implementing a sophisticated memory model that
enables realistic long-term character development.
## 🧠 Memory Types
### Observations
- **What**: Direct experiences and perceptions
- **Examples**: "I spilled coffee", "Emma smiled at me", "It's raining outside"
- **Importance**: Usually 1-5 for mundane events, 8-10 for significant experiences
- **Purpose**: Raw building blocks of character experience
### Reflections
- **What**: Higher-level insights generated from observation patterns
- **Examples**: "I have romantic feelings for Emma", "I'm naturally shy in social situations"
- **Importance**: Usually 6-10 (insights are more valuable than raw observations)
- **Purpose**: Character self-understanding and behavioral consistency
### Plans
- **What**: Future intentions and goals
- **Examples**: "I want to ask Emma about her art", "I should finish my thesis chapter"
- **Importance**: 3-10 depending on goal significance
- **Purpose**: Drive future behavior and maintain character consistency
## 🔍 Memory Retrieval
### Smart Retrieval Algorithm
Memories are scored using three factors:
1. **Recency** - Recent memories are more accessible
```python
recency = 0.995 ** hours_since_last_accessed
```
2. **Importance** - Significant events stay memorable longer
```python
importance = memory.importance_score / 10.0
```
3. **Relevance** - Contextually similar memories surface together
```python
relevance = cosine_similarity(query_embedding, memory_embedding)
```
### Final Score
```python
score = recency + importance + relevance
```
## 🎯 Automatic Reflection Generation
When accumulated importance of recent memories exceeds threshold (150):
1. **Analyze Recent Experiences**: Get last 20 observations
2. **Generate Insights**: Use LLM to identify patterns and higher-level understanding
3. **Create Reflections**: Store insights as new reflection memories
4. **Link Evidence**: Connect reflections to supporting observations
## 💾 Memory Storage
Each memory contains:
- `description`: Natural language content
- `creation_time`: When the memory was formed
- `last_accessed`: When it was last retrieved (affects recency)
- `importance_score`: 1-10 significance rating
- `embedding`: Vector representation for similarity matching
- `memory_type`: observation/reflection/plan
- `related_memories`: Links to supporting evidence
## 🔄 Memory Lifecycle
1. **Creation**: New experience becomes observation
2. **Scoring**: LLM rates importance 1-10
3. **Storage**: Added to memory stream with embedding
4. **Retrieval**: Accessed during relevant conversations
5. **Reflection**: Patterns trigger insight generation
6. **Evolution**: Older memories naturally fade unless repeatedly accessed
This creates realistic, human-like memory behavior where important experiences remain accessible while mundane details
naturally fade over time.

191
docs/prompt-system.md Normal file
View File

@@ -0,0 +1,191 @@
# Prompt Management System
A centralized system for managing LLM prompts with templating, structured outputs, and easy editing capabilities.
## 🎯 System Goals
- **Centralized Management**: All prompts in one organized location
- **Easy Editing**: Modify prompts without touching code
- **Template Support**: Dynamic variable substitution
- **Structured Outputs**: JSON schemas for reliable responses
- **Type Safety**: Validation of required variables
## 📁 File Organization
```
living_agents/prompts/
├── react_to_situation.md # Character response generation
├── score_observation_importance.md # Observation memory scoring
├── score_reflection_importance.md # Reflection memory scoring
├── score_plan_importance.md # Plan memory scoring
├── extract_character_from_memories.md # Character data extraction
├── extract_character_from_memories.json # Character data schema
├── generate_reflection.md # Reflection generation prompt
├── generate_reflection.json # Reflection schema
├── assess_trait_impact.md # Trait analysis prompt
├── assess_trait_impact.json # Trait update schema
└── character_summary.md # Character summary generation
```
## 📝 Prompt Templates
### Template Syntax
Use `{{variable_name}}` for dynamic substitution:
```markdown
You are {{character_name}}.
Age: {{character_age}}
Personality: {{character_personality}}
Relevant memories:
{{memory_context}}
Current situation: {{situation}}
Respond as {{character_name}} in first person past tense.
```
### Variable Extraction
System automatically detects required variables:
- Parses `{{variable}}` patterns
- Validates all variables are provided
- Warns about missing or extra variables
- Ensures template completeness
## 🏗️ JSON Schemas
### Structured Output Support
Pair `.md` prompts with `.json` schemas for reliable structured responses:
**Example Schema** (assess_trait_impact.json):
```json
{
"type": "object",
"properties": {
"trait_updates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"trait_name": {
"type": "string",
"pattern": "^[a-zA-Z]+$"
},
"action": {
"type": "string",
"enum": ["create", "strengthen", "weaken"]
},
"new_strength": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"description": {
"type": "string"
},
"reasoning": {
"type": "string"
}
}
}
}
}
}
```
### Schema Benefits
- **Guaranteed Structure**: Always get expected JSON format
- **Type Validation**: Ensures correct data types
- **Field Requirements**: Specify required vs optional fields
- **Value Constraints**: Set min/max values, string lengths
- **Consistent Parsing**: No more JSON parsing errors
## 🔧 API Usage
### Basic Prompt Retrieval
```python
from living_agents.prompt_manager import PromptManager
# Simple template substitution
prompt = PromptManager.get_prompt('react_to_situation', {
'character_name': 'Alice',
'character_age': 23,
'situation': 'Someone asks how you are feeling'
})
```
### Structured Output
```python
from living_agents.prompt_manager import PromptManager
# Get both prompt and schema
prompt, schema = PromptManager.get_prompt_with_schema('assess_trait_impact', {
'observation': 'I felt nervous talking to Emma',
'traits_summary': 'shy (8/10), romantic (7/10)'
})
# Use with LLM structured output
if schema:
response = await llm.get_structured_response(messages, schema)
else:
response = await llm.chat(messages)
```
### Development Helpers
```python
# List all available prompts
prompts = PromptManager.list_prompts()
print(prompts) # Shows prompt names and required variables
# Get prompt details
info = PromptManager.get_prompt_info('react_to_situation')
print(f"Variables needed: {info['variables']}")
# Reload during development
PromptManager.reload_prompts() # Refresh from files
```
## 🎯 Prompt Design Guidelines
### Template Best Practices
- **Clear Instructions**: Specify exactly what you want
- **Consistent Formatting**: Use standard variable naming
- **Context Provision**: Give LLM necessary background
- **Output Specification**: Define expected response format
- **Example Inclusion**: Show desired output style
### Schema Design
- **Minimal Required Fields**: Only require truly essential data
- **Reasonable Constraints**: Set realistic min/max values
- **Clear Descriptions**: Help LLM understand field purposes
- **Flexible Structure**: Allow for natural language variation
- **Error Prevention**: Design to minimize parsing failures
## 🔄 System Benefits
### For Developers
- **Easy Maintenance**: Edit prompts without code changes
- **Type Safety**: Automatic variable validation
- **Consistent Structure**: Standardized prompt format
- **Debugging Support**: Clear error messages for missing variables
### For LLM Performance
- **Structured Outputs**: Eliminates JSON parsing errors
- **Consistent Prompting**: Reduces response variance
- **Context Optimization**: Templates ensure complete context
- **Schema Guidance**: Helps LLM generate correct format
This system makes prompt management scalable, maintainable, and reliable across the entire roleplay system.

180
docs/trait-system.md Normal file
View File

@@ -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.