ElizaOS Character Generator

A Python tool that generates ElizaOS-compatible character JSON files using OpenRouter API with structured output, automatic context loading, and flexible prompt templates.

Quick Start

1. Install dependencies:

   pip install -r requirements.txt

2. Set your OpenRouter API key:

   export OPENROUTER_API_KEY="your_api_key_here"

3. Generate a character:

   python generate_character.py \
     -p prompts/council_member_v1.txt \
     -i "avatars/optimism.md,episode.json" \
     -o characters/optimism.json

4. Test with ElizaOS:

   elizaos dev --character characters/optimism.json

Usage Examples

Generate Council Members

# Generate optimism character using template v1
python generate_character.py \
  -p prompts/council_member_v1.txt \
  -i "avatars/optimism.md,episode.json,packages/cli/src/characters/eliza.ts" \
  -o characters/optimism.json

# Generate peepo with relationship context (template v2)  
python generate_character.py \
  -p prompts/council_member_v2.txt \
  -i "avatars/peepo.md,characters/optimism.json,episode.json" \
  -o characters/peepo.json

# Generate using jintern as reference
python generate_character.py \
  -p prompts/council_member_v1.txt \
  -i "jintern/src/index.ts,knowledge/the-council/" \
  -o characters/tech_support.json

Validation and Testing

# Validate existing character file
python generate_character.py --validate-only -o characters/optimism.json

# Dry run to see the generated prompt
python generate_character.py --dry-run \
  -p prompts/council_member_v1.txt \
  -i "avatars/optimism.md"

# Use different model
python generate_character.py \
  -p prompts/council_member_v1.txt \
  -i "avatars/optimism.md" \
  -o characters/optimism.json \
  --model "openai/gpt-4o"

Run Multiple Council Members

# Start entire council
elizaos start --character characters/optimism.json,characters/peepo.json,characters/tech_support.json

# Development mode with hot reload
elizaos dev --character characters/optimism.json

Command Line Options

• -p, --prompt <file>: Path to prompt template file (required for generation)
• -i, --include <sources>: Comma-separated list of files/directories to include as context
• -o, --output <file>: Output JSON file path (required)
• --model <model>: OpenRouter model to use (default: "anthropic/claude-3-5-sonnet")
• --api-key <key>: OpenRouter API key (or use OPENROUTER_API_KEY env var)
• --validate-only: Only validate an existing character file, don't generate
• --dry-run: Show what the prompt would look like without making API calls

Prompt Templates

Template V1: Direct Character Generation

• File: prompts/council_member_v1.txt
• Focus: Individual character traits and personality
• Best for: Creating standalone characters with strong individual identity

Template V2: Relationship-Aware Generation

• File: prompts/council_member_v2.txt
• Focus: Integration with existing council ecosystem
• Best for: Creating characters that complement existing council members

Context Sources

The tool automatically loads core ElizaOS schemas and can include additional context:

Auto-loaded ElizaOS Context

• packages/core/src/schemas/character.ts - Character schema
• packages/core/src/types/agent.ts - Type definitions
• packages/docs/docs/core/characters.md - Character documentation
• packages/cli/src/characters/eliza.ts - Reference example

Common User Context Sources

• Avatar profiles: avatars/optimism.md, avatars/peepo.md
• Character examples: jintern/src/index.ts
• Episode data: episode.json
• Council briefings: knowledge/the-council/
• Documentation: packages/docs/docs/
• Existing characters: characters/optimism.json

File Structure

eliza/
├── generate_character.py     # Main generator script
├── requirements.txt          # Python dependencies
├── prompts/                  # Prompt templates
│   ├── council_member_v1.txt
│   └── council_member_v2.txt
├── characters/               # Generated characters (create as needed)
│   ├── optimism.json
│   ├── peepo.json
│   └── ...
└── council-plans/           # Planning documents
    ├── 00-overview.md
    ├── 01-character-archetypes.md
    ├── 03-python-script-design.md
    └── 04-generation-tool-spec.md

Troubleshooting

Common Issues

1. "Could not find ElizaOS root directory"

   • Run the script from within the eliza repository
   • The script looks for packages/core/src/schemas/character.ts to find the root

2. OpenRouter API errors

   • Check your API key is set correctly
   • Verify you have credits in your OpenRouter account
   • Try a different model if the current one is unavailable

3. Validation errors

   • Check the validation output for specific issues
   • Ensure messageExamples follow the nested array structure
   • Verify all required fields are present

4. Context loading warnings

   • Missing files in include sources are warned but not fatal
   • Check file paths are relative to eliza root or absolute

Getting Help

# Show all available options
python generate_character.py --help

# Validate a character file
python generate_character.py --validate-only -o your_character.json

# See what prompt will be generated
python generate_character.py --dry-run -p your_prompt.txt -i "your_context.md"

Advanced Usage

Custom Prompt Templates

Create your own prompt templates using these variables:

• {context} - Automatically loaded context data
• Add custom variables and pass them as kwargs

Multiple Models

Test different models for character generation:

• anthropic/claude-3-5-sonnet (default)
• openai/gpt-4o
• meta-llama/llama-3.1-70b-instruct

Iterative Character Development

Build characters that reference each other:

1. Generate first character with template v1
2. Include first character's JSON in context for second character
3. Use template v2 for relationship-aware generation
4. Continue building the council ecosystem

This tool enables rapid, iterative development of rich AI personalities that work seamlessly within the ElizaOS ecosystem.