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

```python
@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:

```python
@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:

```python
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:

```python
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

```python
# 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