Avatar System

System Overview

The Avatar System manages agent visual representation, voice configuration, and personality characteristics through a modular architecture built around three core components: Models, Manager, and Events.

Core Components

Models (core/avatar/models.py)

Avatar Class

Main configuration container for avatar properties:

@dataclass
class Avatar:
    id: str                    # Unique identifier
    name: str                  # Display name
    image_path: Path           # Static image asset path
    video_path: Optional[Path] # Optional video asset path
    voice_id: str             # ElevenLabs voice identifier
    accent_color: str         # UI theme color
    prompts: AvatarPrompts    # Personality configuration

AvatarPrompts Class

Container for different prompt types:

@dataclass
class AvatarPrompts:
    personality: str  # Base personality traits
    analysis: str    # Analysis approach
    narrative: str   # Communication style

Manager (core/avatar/manager.py)

The AvatarManager class handles avatar state and transitions:

Key Methods:

• _load_avatars(): Initializes avatars from configuration

• set_current_avatar(avatar_id): Changes active avatar

• get_current_avatar(): Returns active avatar instance

• get_next_avatar_id(): Handles avatar rotation

• get_prompt(prompt_type): Retrieves specific prompts

Properties:

• current_voice_id: Active avatar's voice configuration

• current_accent_color: Active avatar's UI theme color

Events (core/avatar/events.py)

Observer pattern implementation for avatar state changes:

class AvatarObserver(Protocol):
    def on_avatar_changed(self, avatar: Avatar) -> None:
        """Handle avatar change event"""
        pass

class AvatarEventDispatcher:
    def add_observer(self, observer: AvatarObserver) -> None
    def remove_observer(self, observer: AvatarObserver) -> None
    def notify_all(self, avatar: Avatar) -> None

Configuration (config/avatar_config.py)

Avatar definitions are stored in AVATAR_CONFIGS dictionary:

pythonCopyAVATAR_CONFIGS = {
    "avatar_id": {
        "name": str,
        "image_path": str,
        "video_path": Optional[str],
        "voice_id": str,
        "accent_color": str,
        "prompts": {
            "personality": str,
            "analysis": str,
            "narrative": str
        }
    }
}

Integration Points

Voice System

• Links to voice_id for audio generation

• Manages voice characteristic changes during avatar switches

UI Integration

• Provides accent_color for theming

• Manages avatar visual assets

• Handles transitions between avatars

Event Handling

• Notifies system components of avatar changes

• Manages state synchronization across the application

Usage Example

# Initialize avatar system
avatar_manager = AvatarManager()

# Register for avatar changes
class UIComponent(AvatarObserver):
    def on_avatar_changed(self, avatar):
        self.update_theme(avatar.accent_color)
        self.load_avatar_image(avatar.image_path)

ui = UIComponent()
avatar_manager.add_observer(ui)

# Change avatars
avatar_manager.set_current_avatar("gennifer")

Error Handling

The system includes comprehensive error handling:

• Configuration loading failures

• Missing avatar assets

• Observer notification errors

• Invalid avatar ID handling