LivingAgents/docs/prompt-system.md

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:

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):

{
  "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

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

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

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