Deploy new version

reachys_brain/app_tools.py

@@ -22,34 +22,30 @@ logger = logging.getLogger(__name__)
 
 
 # Tool definitions for OpenAI Realtime API
+# Note: Quick tools don't need announcements, others should use "Let me..." prefix
 APP_TOOLS = [
     {
         "type": "function",
         "name": "create_custom_app",
         "description": (
-            "Create a new custom assistant app with a specific personality. "
-            "IMPORTANT: Always ask the user for confirmation before calling this tool. "
-            "After confirmation, this creates the app and automatically activates it. "
-            "The app will have a detailed AI-generated personality based on the description."
+            "Create a custom app with a specific personality. "
+            "Ask for confirmation first. Say 'Let me create that for you' before using."
         ),
         "parameters": {
             "type": "object",
             "properties": {
                 "name": {
                     "type": "string",
-                    "description": "A short, catchy name for the app (e.g., 'English Tutor', 'Cooking Helper')"
+                    "description": "Short app name (e.g., 'English Tutor')"
                 },
                 "description": {
                     "type": "string",
-                    "description": (
-                        "A brief description of what the app should do and its personality "
-                        "(e.g., 'A patient English tutor that helps with grammar and vocabulary')"
-                    )
+                    "description": "Brief description of app personality/purpose"
                 },
                 "icon_color": {
                     "type": "string",
                     "enum": ["blue", "purple", "pink", "red", "orange", "yellow", "green", "teal", "indigo"],
-                    "description": "The color for the app's icon"
+                    "description": "Icon color"
                 }
             },
             "required": ["name", "description"]
@@ -59,17 +55,15 @@ APP_TOOLS = [
         "type": "function",
         "name": "activate_custom_app",
         "description": (
-            "Activate an existing custom app by name. "
-            "IMPORTANT: Always ask the user for confirmation before calling this tool. "
-            "Use list_custom_apps first if you're not sure which apps are available. "
-            "Fuzzy matching is used - you don't need the exact name."
+            "Activate a custom app by name. Ask for confirmation first. "
+            "Fuzzy matching supported."
         ),
         "parameters": {
             "type": "object",
             "properties": {
                 "app_name": {
                     "type": "string",
-                    "description": "The name (or partial name) of the app to activate"
+                    "description": "App name or partial name"
                 }
             },
             "required": ["app_name"]
@@ -78,11 +72,7 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "deactivate_app",
-        "description": (
-            "Deactivate the current custom app and return to the default Reachy personality. "
-            "IMPORTANT: Always ask the user for confirmation before calling this tool. "
-            "Call this when the user wants to stop using a custom app."
-        ),
+        "description": "Deactivate current app, return to default. Ask for confirmation first.",
         "parameters": {
             "type": "object",
             "properties": {},
@@ -92,11 +82,7 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "list_custom_apps",
-        "description": (
-            "List all available custom apps. "
-            "Use this to show the user what apps they have created. "
-            "No confirmation needed for this tool."
-        ),
+        "description": "List available custom apps. Quick tool - no announcement needed.",
         "parameters": {
             "type": "object",
             "properties": {},
@@ -106,11 +92,7 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "wake_up",
-        "description": (
-            "Wake up the robot by enabling motors. "
-            "Use this when the user says 'wake up', 'turn on', or similar. "
-            "No confirmation needed - just do it and announce."
-        ),
+        "description": "Enable motors. Quick tool - just do it.",
         "parameters": {
             "type": "object",
             "properties": {},
@@ -120,11 +102,7 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "go_to_sleep",
-        "description": (
-            "Put the robot to sleep by disabling motors. "
-            "Use this when the user says 'go to sleep', 'sleep', 'turn off', or similar. "
-            "No confirmation needed - just do it and announce."
-        ),
+        "description": "Disable motors. Quick tool - just do it.",
         "parameters": {
             "type": "object",
             "properties": {},
@@ -134,18 +112,13 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "remember_user_name",
-        "description": (
-            "Store the user's name for personalized greetings. "
-            "Use this when the user tells you their name (e.g., 'My name is John', 'I'm Sarah', 'Call me Mike'). "
-            "IMPORTANT: Only use the first name or nickname the user prefers. "
-            "This makes future greetings more personal."
-        ),
+        "description": "Save user's name when they introduce themselves. Quick tool.",
         "parameters": {
             "type": "object",
             "properties": {
                 "name": {
                     "type": "string",
-                    "description": "The user's name or preferred nickname to remember"
+                    "description": "User's name or nickname"
                 }
             },
             "required": ["name"]
@@ -154,11 +127,7 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "get_user_name",
-        "description": (
-            "Retrieve the user's stored name. "
-            "Use this to check if you already know the user's name. "
-            "Returns the stored name or null if not set."
-        ),
+        "description": "Check if user's name is stored. Quick tool.",
         "parameters": {
             "type": "object",
             "properties": {},
@@ -168,18 +137,13 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "remember_preferred_country",
-        "description": (
-            "Store the user's preferred country for timezone and localization. "
-            "Use this when the user tells you their country (e.g., 'I live in the Netherlands', "
-            "'I'm from Germany', 'My country is Japan'). "
-            "This is used to show correct local time and personalize content like news."
-        ),
+        "description": "Save user's country for timezone. Quick tool.",
         "parameters": {
             "type": "object",
             "properties": {
                 "country": {
                     "type": "string",
-                    "description": "The user's country name (e.g., 'Netherlands', 'Germany', 'United States')"
+                    "description": "Country name"
                 }
             },
             "required": ["country"]
@@ -188,11 +152,7 @@ APP_TOOLS = [
     {
         "type": "function",
         "name": "get_preferred_country",
-        "description": (
-            "Retrieve the user's stored preferred country. "
-            "Use this to check if you already know the user's country. "
-            "Returns the stored country or null if not set."
-        ),
+        "description": "Check if user's country is stored. Quick tool.",
         "parameters": {
             "type": "object",
             "properties": {},

reachys_brain/database.py

@@ -1,1620 +0,0 @@
-"""SQLite database service for persistent storage.
-
-Provides async database operations for storing custom apps and other data.
-Uses aiosqlite for non-blocking database access.
-"""
-
-import json
-import logging
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-
-import aiosqlite
-
-logger = logging.getLogger(__name__)
-
-# Database location - stored in user's home directory
-DATABASE_DIR = Path.home() / ".reachy"
-DATABASE_PATH = DATABASE_DIR / "reachy_bridge.db"
-
-
-class DatabaseService:
-    """Async SQLite database service for the Reachy iOS Bridge."""
-
-    def __init__(self, db_path: Optional[Path] = None):
-        """Initialize the database service.
-
-        Args:
-            db_path: Optional custom database path. Defaults to ~/.reachy/reachy_bridge.db
-        """
-        self.db_path = db_path or DATABASE_PATH
-        self._connection: Optional[aiosqlite.Connection] = None
-
-    async def initialize(self) -> None:
-        """Initialize the database and create tables if needed."""
-        # Ensure directory exists
-        self.db_path.parent.mkdir(parents=True, exist_ok=True)
-
-        logger.info(f"Initializing database at {self.db_path}")
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await self._create_tables(db)
-            await db.commit()
-
-        logger.info("Database initialized successfully")
-
-    async def _create_tables(self, db: aiosqlite.Connection) -> None:
-        """Create database tables if they don't exist."""
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS custom_apps (
-                id TEXT PRIMARY KEY,
-                name TEXT NOT NULL,
-                description TEXT DEFAULT '',
-                system_prompt TEXT NOT NULL,
-                voice_id TEXT DEFAULT '',
-                emotion_animations TEXT DEFAULT '{}',
-                icon_color TEXT DEFAULT 'blue',
-                enabled_tools TEXT DEFAULT '[]',
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-
-        # Index for faster queries by creation date
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_custom_apps_created 
-            ON custom_apps(created_at)
-        """)
-        
-        # Migration: Add enabled_tools column if it doesn't exist
-        await self._migrate_add_enabled_tools(db)
-
-        # Custom animations table for recorded joystick animations
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS custom_animations (
-                id TEXT PRIMARY KEY,
-                name TEXT NOT NULL,
-                description TEXT DEFAULT '',
-                duration_ms INTEGER NOT NULL,
-                start_pose TEXT NOT NULL,
-                keyframes TEXT NOT NULL,
-                audio_data TEXT DEFAULT NULL,
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-        
-        # Migration: Add audio_data column if it doesn't exist
-        await self._migrate_add_audio_data(db)
-
-        # Index for faster queries by creation date
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_custom_animations_created 
-            ON custom_animations(created_at)
-        """)
-
-        # User settings table for personalization (name, preferences, etc.)
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS user_settings (
-                key TEXT PRIMARY KEY,
-                value TEXT NOT NULL,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-
-        # Websites table for generated websites
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS websites (
-                id TEXT PRIMARY KEY,
-                title TEXT NOT NULL,
-                description TEXT DEFAULT '',
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-
-        # Index for faster queries by creation date
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_websites_created 
-            ON websites(created_at)
-        """)
-
-        # Mental notes table for AI-created notes
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS mental_notes (
-                id TEXT PRIMARY KEY,
-                title TEXT NOT NULL,
-                content TEXT NOT NULL,
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-
-        # Index for faster queries by creation date
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_mental_notes_created 
-            ON mental_notes(created_at)
-        """)
-
-        # Meetings table for meeting transcriptions
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS meetings (
-                id TEXT PRIMARY KEY,
-                title TEXT NOT NULL,
-                transcript TEXT DEFAULT '',
-                action_items TEXT DEFAULT '[]',
-                summary TEXT DEFAULT '',
-                duration_seconds INTEGER DEFAULT 0,
-                status TEXT DEFAULT 'recording',
-                started_at TIMESTAMP,
-                ended_at TIMESTAMP,
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-
-        # Index for faster queries by creation date
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_meetings_created 
-            ON meetings(created_at)
-        """)
-
-        # Index for faster queries by status
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_meetings_status 
-            ON meetings(status)
-        """)
-
-        # Scheduled messages table for scheduled iMessage/WhatsApp messages
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS scheduled_messages (
-                id TEXT PRIMARY KEY,
-                recipient_name TEXT NOT NULL,
-                recipient_phone TEXT NOT NULL,
-                message_content TEXT NOT NULL,
-                scheduled_time TIMESTAMP NOT NULL,
-                platform TEXT NOT NULL,
-                status TEXT DEFAULT 'pending',
-                notification_id TEXT,
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-
-        # Index for faster queries by scheduled time
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_scheduled_messages_time 
-            ON scheduled_messages(scheduled_time)
-        """)
-
-        # Index for faster queries by status
-        await db.execute("""
-            CREATE INDEX IF NOT EXISTS idx_scheduled_messages_status 
-            ON scheduled_messages(status)
-        """)
-
-        # TamaReachy pet game state table
-        await db.execute("""
-            CREATE TABLE IF NOT EXISTS tamareachy_state (
-                id INTEGER PRIMARY KEY DEFAULT 1,
-                enabled INTEGER DEFAULT 0,
-                hunger INTEGER DEFAULT 100,
-                thirst INTEGER DEFAULT 100,
-                happiness INTEGER DEFAULT 100,
-                energy INTEGER DEFAULT 100,
-                boredom INTEGER DEFAULT 100,
-                social INTEGER DEFAULT 100,
-                health INTEGER DEFAULT 100,
-                cleanliness INTEGER DEFAULT 100,
-                last_interaction TIMESTAMP,
-                last_decay_check TIMESTAMP,
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        """)
-        
-        # Ensure there's exactly one row for TamaReachy state
-        await db.execute("""
-            INSERT OR IGNORE INTO tamareachy_state (id) VALUES (1)
-        """)
-
-        logger.debug("Database tables created/verified")
-    
-    async def _migrate_add_enabled_tools(self, db: aiosqlite.Connection) -> None:
-        """Add enabled_tools column to existing databases."""
-        try:
-            # Check if column exists
-            cursor = await db.execute("PRAGMA table_info(custom_apps)")
-            columns = await cursor.fetchall()
-            column_names = [col[1] for col in columns]
-            
-            if "enabled_tools" not in column_names:
-                logger.info("Migrating database: adding enabled_tools column")
-                await db.execute(
-                    "ALTER TABLE custom_apps ADD COLUMN enabled_tools TEXT DEFAULT '[]'"
-                )
-                await db.commit()
-                logger.info("Migration complete: enabled_tools column added")
-        except Exception as e:
-            logger.warning(f"Migration check failed (may be OK): {e}")
-    
-    async def _migrate_add_audio_data(self, db: aiosqlite.Connection) -> None:
-        """Add audio_data column to custom_animations table."""
-        try:
-            # Check if column exists
-            cursor = await db.execute("PRAGMA table_info(custom_animations)")
-            columns = await cursor.fetchall()
-            column_names = [col[1] for col in columns]
-            
-            if "audio_data" not in column_names:
-                logger.info("Migrating database: adding audio_data column to animations")
-                await db.execute(
-                    "ALTER TABLE custom_animations ADD COLUMN audio_data TEXT DEFAULT NULL"
-                )
-                await db.commit()
-                logger.info("Migration complete: audio_data column added to animations")
-        except Exception as e:
-            logger.warning(f"Animation audio migration check failed (may be OK): {e}")
-
-    # =========================================================================
-    # Custom Apps CRUD Operations
-    # =========================================================================
-
-    async def get_all_apps(self) -> list[dict]:
-        """Get all custom apps from the database.
-
-        Returns:
-            List of custom app dictionaries.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM custom_apps ORDER BY created_at DESC"
-            )
-            rows = await cursor.fetchall()
-            return [self._row_to_app(row) for row in rows]
-
-    async def get_app(self, app_id: str) -> Optional[dict]:
-        """Get a single custom app by ID.
-
-        Args:
-            app_id: The UUID of the app.
-
-        Returns:
-            The app dictionary, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM custom_apps WHERE id = ?", (app_id,)
-            )
-            row = await cursor.fetchone()
-            return self._row_to_app(row) if row else None
-
-    async def create_app(self, app_data: dict) -> dict:
-        """Create a new custom app.
-
-        Args:
-            app_data: Dictionary containing app data (must include 'id').
-
-        Returns:
-            The created app dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-        emotion_animations = json.dumps(app_data.get("emotion_animations", {}))
-        enabled_tools = json.dumps(app_data.get("enabled_tools", []))
-        
-        # Ensure created_at is always set (use provided value or current time)
-        created_at = app_data.get("created_at") or now
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT INTO custom_apps 
-                (id, name, description, system_prompt, voice_id, 
-                 emotion_animations, icon_color, enabled_tools, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    app_data["id"],
-                    app_data["name"],
-                    app_data.get("description", ""),
-                    app_data["system_prompt"],
-                    app_data.get("voice_id", ""),
-                    emotion_animations,
-                    app_data.get("icon_color", "blue"),
-                    enabled_tools,
-                    created_at,
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Created custom app: {app_data['name']} ({app_data['id']})")
-        return await self.get_app(app_data["id"])
-
-    async def update_app(self, app_id: str, app_data: dict) -> Optional[dict]:
-        """Update an existing custom app.
-
-        Args:
-            app_id: The UUID of the app to update.
-            app_data: Dictionary containing updated app data.
-
-        Returns:
-            The updated app dictionary, or None if not found.
-        """
-        existing = await self.get_app(app_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-        
-        # Handle emotion_animations - use existing if not provided
-        if "emotion_animations" in app_data:
-            emotion_animations = json.dumps(app_data["emotion_animations"])
-        else:
-            emotion_animations = json.dumps(existing["emotion_animations"])
-        
-        # Handle enabled_tools - use existing if not provided
-        if "enabled_tools" in app_data:
-            enabled_tools = json.dumps(app_data["enabled_tools"])
-        else:
-            enabled_tools = json.dumps(existing["enabled_tools"])
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE custom_apps SET
-                    name = ?,
-                    description = ?,
-                    system_prompt = ?,
-                    voice_id = ?,
-                    emotion_animations = ?,
-                    icon_color = ?,
-                    enabled_tools = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (
-                    app_data.get("name", existing["name"]),
-                    app_data.get("description", existing["description"]),
-                    app_data.get("system_prompt", existing["system_prompt"]),
-                    app_data.get("voice_id", existing["voice_id"]),
-                    emotion_animations,
-                    app_data.get("icon_color", existing["icon_color"]),
-                    enabled_tools,
-                    now,
-                    app_id,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Updated custom app: {app_id}")
-        return await self.get_app(app_id)
-
-    async def delete_app(self, app_id: str) -> bool:
-        """Delete a custom app.
-
-        Args:
-            app_id: The UUID of the app to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM custom_apps WHERE id = ?", (app_id,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted custom app: {app_id}")
-        return deleted
-
-    async def sync_apps(self, apps: list[dict]) -> list[dict]:
-        """Bulk sync apps from iOS client.
-
-        This replaces all existing apps with the provided list.
-        Used for initial sync or full restore.
-
-        Args:
-            apps: List of app dictionaries to sync.
-
-        Returns:
-            List of all apps after sync.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            # Clear existing apps
-            await db.execute("DELETE FROM custom_apps")
-
-            # Insert all new apps
-            now = datetime.utcnow().isoformat()
-            for app in apps:
-                emotion_animations = json.dumps(app.get("emotion_animations", {}))
-                enabled_tools = json.dumps(app.get("enabled_tools", []))
-                # Ensure created_at is always set
-                created_at = app.get("created_at") or now
-                await db.execute(
-                    """
-                    INSERT INTO custom_apps 
-                    (id, name, description, system_prompt, voice_id, 
-                     emotion_animations, icon_color, enabled_tools, created_at, updated_at)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    """,
-                    (
-                        app["id"],
-                        app["name"],
-                        app.get("description", ""),
-                        app["system_prompt"],
-                        app.get("voice_id", ""),
-                        emotion_animations,
-                        app.get("icon_color", "blue"),
-                        enabled_tools,
-                        created_at,
-                        now,
-                    ),
-                )
-
-            await db.commit()
-
-        logger.info(f"Synced {len(apps)} custom apps")
-        return await self.get_all_apps()
-
-    # =========================================================================
-    # Custom Animations CRUD Operations
-    # =========================================================================
-
-    async def get_all_animations(self) -> list[dict]:
-        """Get all custom animations from the database.
-
-        Returns:
-            List of custom animation dictionaries.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM custom_animations ORDER BY created_at DESC"
-            )
-            rows = await cursor.fetchall()
-            return [self._row_to_animation(row) for row in rows]
-
-    async def get_animation(self, animation_id: str) -> Optional[dict]:
-        """Get a single custom animation by ID.
-
-        Args:
-            animation_id: The UUID of the animation.
-
-        Returns:
-            The animation dictionary, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM custom_animations WHERE id = ?", (animation_id,)
-            )
-            row = await cursor.fetchone()
-            return self._row_to_animation(row) if row else None
-
-    async def create_animation(self, animation_data: dict) -> dict:
-        """Create a new custom animation.
-
-        Args:
-            animation_data: Dictionary containing animation data (must include 'id').
-
-        Returns:
-            The created animation dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-        start_pose = json.dumps(animation_data.get("start_pose", {}))
-        keyframes = json.dumps(animation_data.get("keyframes", []))
-        audio_data = animation_data.get("audio_data")  # Base64 string or None
-        
-        # Ensure created_at is always set
-        created_at = animation_data.get("created_at") or now
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT INTO custom_animations 
-                (id, name, description, duration_ms, start_pose, keyframes, 
-                 audio_data, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    animation_data["id"],
-                    animation_data["name"],
-                    animation_data.get("description", ""),
-                    animation_data["duration_ms"],
-                    start_pose,
-                    keyframes,
-                    audio_data,
-                    created_at,
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Created custom animation: {animation_data['name']} ({animation_data['id']})")
-        return await self.get_animation(animation_data["id"])
-
-    async def update_animation(self, animation_id: str, animation_data: dict) -> Optional[dict]:
-        """Update an existing custom animation.
-
-        Args:
-            animation_id: The UUID of the animation to update.
-            animation_data: Dictionary containing updated animation data.
-
-        Returns:
-            The updated animation dictionary, or None if not found.
-        """
-        existing = await self.get_animation(animation_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-        
-        # Handle start_pose - use existing if not provided
-        if "start_pose" in animation_data:
-            start_pose = json.dumps(animation_data["start_pose"])
-        else:
-            start_pose = json.dumps(existing["start_pose"])
-        
-        # Handle keyframes - use existing if not provided
-        if "keyframes" in animation_data:
-            keyframes = json.dumps(animation_data["keyframes"])
-        else:
-            keyframes = json.dumps(existing["keyframes"])
-        
-        # Handle audio_data - use existing if not provided
-        if "audio_data" in animation_data:
-            audio_data = animation_data["audio_data"]
-        else:
-            audio_data = existing.get("audio_data")
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE custom_animations SET
-                    name = ?,
-                    description = ?,
-                    duration_ms = ?,
-                    start_pose = ?,
-                    keyframes = ?,
-                    audio_data = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (
-                    animation_data.get("name", existing["name"]),
-                    animation_data.get("description", existing["description"]),
-                    animation_data.get("duration_ms", existing["duration_ms"]),
-                    start_pose,
-                    keyframes,
-                    audio_data,
-                    now,
-                    animation_id,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Updated custom animation: {animation_id}")
-        return await self.get_animation(animation_id)
-
-    async def delete_animation(self, animation_id: str) -> bool:
-        """Delete a custom animation.
-
-        Args:
-            animation_id: The UUID of the animation to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM custom_animations WHERE id = ?", (animation_id,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted custom animation: {animation_id}")
-        return deleted
-
-    # =========================================================================
-    # User Settings Operations
-    # =========================================================================
-
-    async def get_user_setting(self, key: str) -> Optional[str]:
-        """Get a user setting value by key.
-
-        Args:
-            key: The setting key (e.g., 'user_name').
-
-        Returns:
-            The setting value, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "SELECT value FROM user_settings WHERE key = ?", (key,)
-            )
-            row = await cursor.fetchone()
-            return row[0] if row else None
-
-    async def set_user_setting(self, key: str, value: str) -> bool:
-        """Set a user setting value.
-
-        Uses INSERT OR REPLACE to handle both new and existing keys.
-
-        Args:
-            key: The setting key.
-            value: The setting value.
-
-        Returns:
-            True if successful.
-        """
-        now = datetime.utcnow().isoformat()
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT OR REPLACE INTO user_settings (key, value, updated_at)
-                VALUES (?, ?, ?)
-                """,
-                (key, value, now),
-            )
-            await db.commit()
-
-        logger.info(f"Set user setting: {key}")
-        return True
-
-    async def delete_user_setting(self, key: str) -> bool:
-        """Delete a user setting.
-
-        Args:
-            key: The setting key to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM user_settings WHERE key = ?", (key,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted user setting: {key}")
-        return deleted
-
-    async def get_all_user_settings(self) -> dict[str, str]:
-        """Get all user settings as a dictionary.
-
-        Returns:
-            Dictionary of key-value pairs.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute("SELECT key, value FROM user_settings")
-            rows = await cursor.fetchall()
-            return {row[0]: row[1] for row in rows}
-
-    # =========================================================================
-    # Websites CRUD Operations
-    # =========================================================================
-
-    async def get_all_websites(self) -> list[dict]:
-        """Get all saved websites from the database.
-
-        Returns:
-            List of website dictionaries.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM websites ORDER BY created_at DESC"
-            )
-            rows = await cursor.fetchall()
-            return [self._row_to_website(row) for row in rows]
-
-    async def get_website(self, website_id: str) -> Optional[dict]:
-        """Get a single website by ID.
-
-        Args:
-            website_id: The ID of the website.
-
-        Returns:
-            The website dictionary, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM websites WHERE id = ?", (website_id,)
-            )
-            row = await cursor.fetchone()
-            return self._row_to_website(row) if row else None
-
-    async def create_website(self, website_data: dict) -> dict:
-        """Create a new website record.
-
-        Args:
-            website_data: Dictionary containing website data (must include 'id', 'title').
-
-        Returns:
-            The created website dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-        created_at = website_data.get("created_at") or now
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT INTO websites (id, title, description, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?)
-                """,
-                (
-                    website_data["id"],
-                    website_data["title"],
-                    website_data.get("description", ""),
-                    created_at,
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Created website: {website_data['title']} ({website_data['id']})")
-        return await self.get_website(website_data["id"])
-
-    async def update_website(self, website_id: str, website_data: dict) -> Optional[dict]:
-        """Update an existing website record.
-
-        Args:
-            website_id: The ID of the website to update.
-            website_data: Dictionary containing updated website data.
-
-        Returns:
-            The updated website dictionary, or None if not found.
-        """
-        existing = await self.get_website(website_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE websites SET
-                    title = ?,
-                    description = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (
-                    website_data.get("title", existing["title"]),
-                    website_data.get("description", existing["description"]),
-                    now,
-                    website_id,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Updated website: {website_id}")
-        return await self.get_website(website_id)
-
-    async def delete_website(self, website_id: str) -> bool:
-        """Delete a website record.
-
-        Args:
-            website_id: The ID of the website to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM websites WHERE id = ?", (website_id,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted website: {website_id}")
-        return deleted
-
-    # =========================================================================
-    # Mental Notes CRUD Operations
-    # =========================================================================
-
-    async def get_all_notes(self) -> list[dict]:
-        """Get all mental notes from the database.
-
-        Returns:
-            List of mental note dictionaries.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM mental_notes ORDER BY created_at DESC"
-            )
-            rows = await cursor.fetchall()
-            return [self._row_to_note(row) for row in rows]
-
-    async def get_note(self, note_id: str) -> Optional[dict]:
-        """Get a single mental note by ID.
-
-        Args:
-            note_id: The ID of the note.
-
-        Returns:
-            The note dictionary, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM mental_notes WHERE id = ?", (note_id,)
-            )
-            row = await cursor.fetchone()
-            return self._row_to_note(row) if row else None
-
-    async def create_note(self, note_data: dict) -> dict:
-        """Create a new mental note.
-
-        Args:
-            note_data: Dictionary containing note data (must include 'id', 'title', 'content').
-
-        Returns:
-            The created note dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-        created_at = note_data.get("created_at") or now
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT INTO mental_notes (id, title, content, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?)
-                """,
-                (
-                    note_data["id"],
-                    note_data["title"],
-                    note_data["content"],
-                    created_at,
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Created mental note: {note_data['title']} ({note_data['id']})")
-        return await self.get_note(note_data["id"])
-
-    async def update_note(self, note_id: str, note_data: dict) -> Optional[dict]:
-        """Update an existing mental note.
-
-        Args:
-            note_id: The ID of the note to update.
-            note_data: Dictionary containing updated note data.
-
-        Returns:
-            The updated note dictionary, or None if not found.
-        """
-        existing = await self.get_note(note_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE mental_notes SET
-                    title = ?,
-                    content = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (
-                    note_data.get("title", existing["title"]),
-                    note_data.get("content", existing["content"]),
-                    now,
-                    note_id,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Updated mental note: {note_id}")
-        return await self.get_note(note_id)
-
-    async def delete_note(self, note_id: str) -> bool:
-        """Delete a mental note.
-
-        Args:
-            note_id: The ID of the note to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM mental_notes WHERE id = ?", (note_id,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted mental note: {note_id}")
-        return deleted
-
-    # =========================================================================
-    # Meetings CRUD Operations
-    # =========================================================================
-
-    async def get_all_meetings(self) -> list[dict]:
-        """Get all meetings from the database.
-
-        Returns:
-            List of meeting dictionaries.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM meetings ORDER BY created_at DESC"
-            )
-            rows = await cursor.fetchall()
-            return [self._row_to_meeting(row) for row in rows]
-
-    async def get_meeting(self, meeting_id: str) -> Optional[dict]:
-        """Get a single meeting by ID.
-
-        Args:
-            meeting_id: The ID of the meeting.
-
-        Returns:
-            The meeting dictionary, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM meetings WHERE id = ?", (meeting_id,)
-            )
-            row = await cursor.fetchone()
-            return self._row_to_meeting(row) if row else None
-
-    async def get_active_meeting(self) -> Optional[dict]:
-        """Get the currently active (recording) meeting.
-
-        Returns:
-            The active meeting dictionary, or None if no meeting is recording.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM meetings WHERE status = 'recording' LIMIT 1"
-            )
-            row = await cursor.fetchone()
-            return self._row_to_meeting(row) if row else None
-
-    async def create_meeting(self, meeting_data: dict) -> dict:
-        """Create a new meeting record.
-
-        Args:
-            meeting_data: Dictionary containing meeting data (must include 'id', 'title').
-
-        Returns:
-            The created meeting dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-        action_items = json.dumps(meeting_data.get("action_items", []))
-        started_at = meeting_data.get("started_at") or now
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT INTO meetings 
-                (id, title, transcript, action_items, summary, duration_seconds, 
-                 status, started_at, ended_at, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    meeting_data["id"],
-                    meeting_data["title"],
-                    meeting_data.get("transcript", ""),
-                    action_items,
-                    meeting_data.get("summary", ""),
-                    meeting_data.get("duration_seconds", 0),
-                    meeting_data.get("status", "recording"),
-                    started_at,
-                    meeting_data.get("ended_at"),
-                    now,
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Created meeting: {meeting_data['title']} ({meeting_data['id']})")
-        return await self.get_meeting(meeting_data["id"])
-
-    async def update_meeting(self, meeting_id: str, meeting_data: dict) -> Optional[dict]:
-        """Update an existing meeting.
-
-        Args:
-            meeting_id: The ID of the meeting to update.
-            meeting_data: Dictionary containing updated meeting data.
-
-        Returns:
-            The updated meeting dictionary, or None if not found.
-        """
-        existing = await self.get_meeting(meeting_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-
-        # Handle action_items - use existing if not provided
-        if "action_items" in meeting_data:
-            action_items = json.dumps(meeting_data["action_items"])
-        else:
-            action_items = json.dumps(existing["action_items"])
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE meetings SET
-                    title = ?,
-                    transcript = ?,
-                    action_items = ?,
-                    summary = ?,
-                    duration_seconds = ?,
-                    status = ?,
-                    started_at = ?,
-                    ended_at = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (
-                    meeting_data.get("title", existing["title"]),
-                    meeting_data.get("transcript", existing["transcript"]),
-                    action_items,
-                    meeting_data.get("summary", existing["summary"]),
-                    meeting_data.get("duration_seconds", existing["duration_seconds"]),
-                    meeting_data.get("status", existing["status"]),
-                    meeting_data.get("started_at", existing["started_at"]),
-                    meeting_data.get("ended_at", existing["ended_at"]),
-                    now,
-                    meeting_id,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Updated meeting: {meeting_id}")
-        return await self.get_meeting(meeting_id)
-
-    async def append_to_meeting_transcript(
-        self, meeting_id: str, text: str
-    ) -> Optional[dict]:
-        """Append text to an existing meeting's transcript.
-
-        Args:
-            meeting_id: The ID of the meeting.
-            text: The text to append to the transcript.
-
-        Returns:
-            The updated meeting dictionary, or None if not found.
-        """
-        existing = await self.get_meeting(meeting_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-        new_transcript = existing["transcript"] + text
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE meetings SET
-                    transcript = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (new_transcript, now, meeting_id),
-            )
-            await db.commit()
-
-        logger.debug(f"Appended to meeting transcript: {meeting_id}")
-        return await self.get_meeting(meeting_id)
-
-    async def delete_meeting(self, meeting_id: str) -> bool:
-        """Delete a meeting.
-
-        Args:
-            meeting_id: The ID of the meeting to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM meetings WHERE id = ?", (meeting_id,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted meeting: {meeting_id}")
-        return deleted
-
-    # =========================================================================
-    # Scheduled Messages CRUD Operations
-    # =========================================================================
-
-    async def get_all_scheduled_messages(self, status: Optional[str] = None) -> list[dict]:
-        """Get all scheduled messages from the database.
-
-        Args:
-            status: Optional filter by status ('pending', 'sent', 'cancelled').
-
-        Returns:
-            List of scheduled message dictionaries.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            if status:
-                cursor = await db.execute(
-                    "SELECT * FROM scheduled_messages WHERE status = ? ORDER BY scheduled_time ASC",
-                    (status,)
-                )
-            else:
-                cursor = await db.execute(
-                    "SELECT * FROM scheduled_messages ORDER BY scheduled_time ASC"
-                )
-            rows = await cursor.fetchall()
-            return [self._row_to_scheduled_message(row) for row in rows]
-
-    async def get_scheduled_message(self, message_id: str) -> Optional[dict]:
-        """Get a single scheduled message by ID.
-
-        Args:
-            message_id: The ID of the scheduled message.
-
-        Returns:
-            The scheduled message dictionary, or None if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM scheduled_messages WHERE id = ?", (message_id,)
-            )
-            row = await cursor.fetchone()
-            return self._row_to_scheduled_message(row) if row else None
-
-    async def get_pending_scheduled_messages(self) -> list[dict]:
-        """Get all pending scheduled messages.
-
-        Returns:
-            List of pending scheduled message dictionaries.
-        """
-        return await self.get_all_scheduled_messages(status="pending")
-
-    async def create_scheduled_message(self, message_data: dict) -> dict:
-        """Create a new scheduled message.
-
-        Args:
-            message_data: Dictionary containing message data.
-                Required: id, recipient_name, recipient_phone, message_content,
-                         scheduled_time, platform
-                Optional: notification_id
-
-        Returns:
-            The created scheduled message dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT INTO scheduled_messages 
-                (id, recipient_name, recipient_phone, message_content, 
-                 scheduled_time, platform, status, notification_id, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    message_data["id"],
-                    message_data["recipient_name"],
-                    message_data["recipient_phone"],
-                    message_data["message_content"],
-                    message_data["scheduled_time"],
-                    message_data["platform"],
-                    message_data.get("status", "pending"),
-                    message_data.get("notification_id"),
-                    now,
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Created scheduled message: {message_data['id']} for {message_data['recipient_name']}")
-        return await self.get_scheduled_message(message_data["id"])
-
-    async def update_scheduled_message(
-        self, message_id: str, message_data: dict
-    ) -> Optional[dict]:
-        """Update an existing scheduled message.
-
-        Args:
-            message_id: The ID of the scheduled message to update.
-            message_data: Dictionary containing updated message data.
-
-        Returns:
-            The updated scheduled message dictionary, or None if not found.
-        """
-        existing = await self.get_scheduled_message(message_id)
-        if not existing:
-            return None
-
-        now = datetime.utcnow().isoformat()
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE scheduled_messages SET
-                    recipient_name = ?,
-                    recipient_phone = ?,
-                    message_content = ?,
-                    scheduled_time = ?,
-                    platform = ?,
-                    status = ?,
-                    notification_id = ?,
-                    updated_at = ?
-                WHERE id = ?
-                """,
-                (
-                    message_data.get("recipient_name", existing["recipient_name"]),
-                    message_data.get("recipient_phone", existing["recipient_phone"]),
-                    message_data.get("message_content", existing["message_content"]),
-                    message_data.get("scheduled_time", existing["scheduled_time"]),
-                    message_data.get("platform", existing["platform"]),
-                    message_data.get("status", existing["status"]),
-                    message_data.get("notification_id", existing["notification_id"]),
-                    now,
-                    message_id,
-                ),
-            )
-            await db.commit()
-
-        logger.info(f"Updated scheduled message: {message_id}")
-        return await self.get_scheduled_message(message_id)
-
-    async def update_scheduled_message_status(
-        self, message_id: str, status: str
-    ) -> Optional[dict]:
-        """Update just the status of a scheduled message.
-
-        Args:
-            message_id: The ID of the scheduled message.
-            status: The new status ('pending', 'sent', 'cancelled').
-
-        Returns:
-            The updated scheduled message dictionary, or None if not found.
-        """
-        return await self.update_scheduled_message(message_id, {"status": status})
-
-    async def delete_scheduled_message(self, message_id: str) -> bool:
-        """Delete a scheduled message.
-
-        Args:
-            message_id: The ID of the scheduled message to delete.
-
-        Returns:
-            True if deleted, False if not found.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM scheduled_messages WHERE id = ?", (message_id,)
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted:
-            logger.info(f"Deleted scheduled message: {message_id}")
-        return deleted
-
-    # =========================================================================
-    # TamaReachy Operations
-    # =========================================================================
-
-    async def get_tamareachy_state(self) -> dict:
-        """Get the current TamaReachy state.
-
-        Returns:
-            TamaReachy state dictionary.
-        """
-        async with aiosqlite.connect(self.db_path) as db:
-            db.row_factory = aiosqlite.Row
-            cursor = await db.execute(
-                "SELECT * FROM tamareachy_state WHERE id = 1"
-            )
-            row = await cursor.fetchone()
-            if row:
-                return self._row_to_tamareachy(row)
-            # Return default state if not found
-            return {
-                "enabled": False,
-                "hunger": 100,
-                "thirst": 100,
-                "happiness": 100,
-                "energy": 100,
-                "boredom": 100,
-                "social": 100,
-                "health": 100,
-                "cleanliness": 100,
-                "last_interaction": None,
-                "last_decay_check": None,
-            }
-
-    async def update_tamareachy_state(self, state_data: dict) -> dict:
-        """Update TamaReachy state.
-
-        Args:
-            state_data: Dictionary containing fields to update.
-
-        Returns:
-            The updated TamaReachy state dictionary.
-        """
-        existing = await self.get_tamareachy_state()
-        now = datetime.utcnow().isoformat()
-
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                UPDATE tamareachy_state SET
-                    enabled = ?,
-                    hunger = ?,
-                    thirst = ?,
-                    happiness = ?,
-                    energy = ?,
-                    boredom = ?,
-                    social = ?,
-                    health = ?,
-                    cleanliness = ?,
-                    last_interaction = ?,
-                    last_decay_check = ?,
-                    updated_at = ?
-                WHERE id = 1
-                """,
-                (
-                    1 if state_data.get("enabled", existing["enabled"]) else 0,
-                    state_data.get("hunger", existing["hunger"]),
-                    state_data.get("thirst", existing["thirst"]),
-                    state_data.get("happiness", existing["happiness"]),
-                    state_data.get("energy", existing["energy"]),
-                    state_data.get("boredom", existing["boredom"]),
-                    state_data.get("social", existing["social"]),
-                    state_data.get("health", existing["health"]),
-                    state_data.get("cleanliness", existing["cleanliness"]),
-                    state_data.get("last_interaction", existing["last_interaction"]),
-                    state_data.get("last_decay_check", existing["last_decay_check"]),
-                    now,
-                ),
-            )
-            await db.commit()
-
-        logger.info("Updated TamaReachy state")
-        return await self.get_tamareachy_state()
-
-    async def reset_tamareachy_stats(self) -> dict:
-        """Reset all TamaReachy stats to 100.
-
-        Returns:
-            The reset TamaReachy state dictionary.
-        """
-        now = datetime.utcnow().isoformat()
-        return await self.update_tamareachy_state({
-            "hunger": 100,
-            "thirst": 100,
-            "happiness": 100,
-            "energy": 100,
-            "boredom": 100,
-            "social": 100,
-            "health": 100,
-            "cleanliness": 100,
-            "last_interaction": now,
-            "last_decay_check": now,
-        })
-
-    def _row_to_tamareachy(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to a TamaReachy state dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            TamaReachy state dictionary with proper types.
-        """
-        return {
-            "enabled": bool(row["enabled"]),
-            "hunger": row["hunger"],
-            "thirst": row["thirst"],
-            "happiness": row["happiness"],
-            "energy": row["energy"],
-            "boredom": row["boredom"],
-            "social": row["social"],
-            "health": row["health"],
-            "cleanliness": row["cleanliness"],
-            "last_interaction": row["last_interaction"],
-            "last_decay_check": row["last_decay_check"],
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    # =========================================================================
-    # Helper Methods
-    # =========================================================================
-
-    def _row_to_animation(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to an animation dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            Animation dictionary with proper types.
-        """
-        # Handle audio_data - may not exist in older databases
-        audio_data = row["audio_data"] if "audio_data" in row.keys() else None
-        
-        return {
-            "id": row["id"],
-            "name": row["name"],
-            "description": row["description"],
-            "duration_ms": row["duration_ms"],
-            "start_pose": json.loads(row["start_pose"]),
-            "keyframes": json.loads(row["keyframes"]),
-            "audio_data": audio_data,
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    def _row_to_app(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to an app dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            App dictionary with proper types.
-        """
-        # Handle enabled_tools - may not exist in older databases
-        enabled_tools_raw = row["enabled_tools"] if "enabled_tools" in row.keys() else "[]"
-        
-        return {
-            "id": row["id"],
-            "name": row["name"],
-            "description": row["description"],
-            "system_prompt": row["system_prompt"],
-            "voice_id": row["voice_id"],
-            "emotion_animations": json.loads(row["emotion_animations"]),
-            "icon_color": row["icon_color"],
-            "enabled_tools": json.loads(enabled_tools_raw) if enabled_tools_raw else [],
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    def _row_to_website(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to a website dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            Website dictionary with proper types.
-        """
-        return {
-            "id": row["id"],
-            "title": row["title"],
-            "description": row["description"],
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    def _row_to_note(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to a mental note dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            Mental note dictionary with proper types.
-        """
-        return {
-            "id": row["id"],
-            "title": row["title"],
-            "content": row["content"],
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    def _row_to_meeting(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to a meeting dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            Meeting dictionary with proper types.
-        """
-        action_items_raw = row["action_items"] if row["action_items"] else "[]"
-        return {
-            "id": row["id"],
-            "title": row["title"],
-            "transcript": row["transcript"] or "",
-            "action_items": json.loads(action_items_raw),
-            "summary": row["summary"] or "",
-            "duration_seconds": row["duration_seconds"] or 0,
-            "status": row["status"] or "recording",
-            "started_at": row["started_at"],
-            "ended_at": row["ended_at"],
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    def _row_to_scheduled_message(self, row: aiosqlite.Row) -> dict:
-        """Convert a database row to a scheduled message dictionary.
-
-        Args:
-            row: The database row.
-
-        Returns:
-            Scheduled message dictionary with proper types.
-        """
-        return {
-            "id": row["id"],
-            "recipient_name": row["recipient_name"],
-            "recipient_phone": row["recipient_phone"],
-            "message_content": row["message_content"],
-            "scheduled_time": row["scheduled_time"],
-            "platform": row["platform"],
-            "status": row["status"] or "pending",
-            "notification_id": row["notification_id"],
-            "created_at": row["created_at"],
-            "updated_at": row["updated_at"],
-        }
-
-    async def close(self) -> None:
-        """Close database connection (if using persistent connection)."""
-        if self._connection:
-            await self._connection.close()
-            self._connection = None
-
-
-# Global database service instance
-db_service: Optional[DatabaseService] = None
-
-
-def get_database() -> DatabaseService:
-    """Get the global database service instance.
-
-    Returns:
-        The database service.
-
-    Raises:
-        RuntimeError: If database not initialized.
-    """
-    if db_service is None:
-        raise RuntimeError("Database not initialized. Call init_database() first.")
-    return db_service
-
-
-async def init_database(db_path: Optional[Path] = None) -> DatabaseService:
-    """Initialize the global database service.
-
-    Args:
-        db_path: Optional custom database path.
-
-    Returns:
-        The initialized database service.
-    """
-    global db_service
-    db_service = DatabaseService(db_path)
-    await db_service.initialize()
-    return db_service
-

reachys_brain/database/__init__.py

@@ -0,0 +1,100 @@
+"""SQLite database service for persistent storage.
+
+Provides async database operations for storing custom apps, animations,
+user settings, websites, notes, meetings, scheduled messages, and TamaReachy state.
+Uses aiosqlite for non-blocking database access.
+
+This module combines all database operations into a single DatabaseService class
+using the mixin pattern for better code organization.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from .base import DatabaseService as _BaseDatabaseService, DATABASE_PATH, DATABASE_DIR
+from .apps import AppsMixin
+from .animations import AnimationsMixin
+from .user_settings import UserSettingsMixin
+from .websites import WebsitesMixin
+from .notes import NotesMixin
+from .meetings import MeetingsMixin
+from .scheduled_messages import ScheduledMessagesMixin
+from .tamareachy import TamaReachyMixin
+
+
+class DatabaseService(
+    _BaseDatabaseService,
+    AppsMixin,
+    AnimationsMixin,
+    UserSettingsMixin,
+    WebsitesMixin,
+    NotesMixin,
+    MeetingsMixin,
+    ScheduledMessagesMixin,
+    TamaReachyMixin,
+):
+    """Async SQLite database service for the Reachy iOS Bridge.
+    
+    This class combines the base DatabaseService with all CRUD mixins,
+    providing a complete interface for database operations.
+    
+    Example usage:
+        db = DatabaseService()
+        await db.initialize()
+        
+        # Custom Apps
+        apps = await db.get_all_apps()
+        app = await db.create_app({"id": "...", "name": "...", ...})
+        
+        # User Settings
+        await db.set_user_setting("user_name", "John")
+        name = await db.get_user_setting("user_name")
+        
+        # And so on for other tables...
+    """
+    pass
+
+
+# Global database service instance
+db_service: Optional[DatabaseService] = None
+
+
+def get_database() -> DatabaseService:
+    """Get the global database service instance.
+
+    Returns:
+        The database service.
+
+    Raises:
+        RuntimeError: If database not initialized.
+    """
+    if db_service is None:
+        raise RuntimeError("Database not initialized. Call init_database() first.")
+    return db_service
+
+
+async def init_database(db_path: Optional[Path] = None) -> DatabaseService:
+    """Initialize the global database service.
+
+    Args:
+        db_path: Optional custom database path.
+
+    Returns:
+        The initialized database service.
+    """
+    global db_service
+    db_service = DatabaseService(db_path)
+    await db_service.initialize()
+    return db_service
+
+
+# Re-export for backwards compatibility
+__all__ = [
+    "DatabaseService",
+    "DATABASE_PATH",
+    "DATABASE_DIR",
+    "get_database",
+    "init_database",
+    "db_service",
+]
+

reachys_brain/database/animations.py

@@ -0,0 +1,203 @@
+"""Custom Animations CRUD operations for the database.
+
+Provides methods for creating, reading, updating, and deleting custom animations.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class AnimationsMixin:
+    """Mixin class providing Custom Animations CRUD operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_all_animations(self) -> list[dict]:
+        """Get all custom animations from the database.
+
+        Returns:
+            List of custom animation dictionaries.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM custom_animations ORDER BY created_at DESC"
+            )
+            rows = await cursor.fetchall()
+            return [self._row_to_animation(row) for row in rows]
+
+    async def get_animation(self, animation_id: str) -> Optional[dict]:
+        """Get a single custom animation by ID.
+
+        Args:
+            animation_id: The UUID of the animation.
+
+        Returns:
+            The animation dictionary, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM custom_animations WHERE id = ?", (animation_id,)
+            )
+            row = await cursor.fetchone()
+            return self._row_to_animation(row) if row else None
+
+    async def create_animation(self, animation_data: dict) -> dict:
+        """Create a new custom animation.
+
+        Args:
+            animation_data: Dictionary containing animation data (must include 'id').
+
+        Returns:
+            The created animation dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+        start_pose = json.dumps(animation_data.get("start_pose", {}))
+        keyframes = json.dumps(animation_data.get("keyframes", []))
+        audio_data = animation_data.get("audio_data")  # Base64 string or None
+        
+        # Ensure created_at is always set
+        created_at = animation_data.get("created_at") or now
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO custom_animations 
+                (id, name, description, duration_ms, start_pose, keyframes, 
+                 audio_data, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    animation_data["id"],
+                    animation_data["name"],
+                    animation_data.get("description", ""),
+                    animation_data["duration_ms"],
+                    start_pose,
+                    keyframes,
+                    audio_data,
+                    created_at,
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Created custom animation: {animation_data['name']} ({animation_data['id']})")
+        return await self.get_animation(animation_data["id"])
+
+    async def update_animation(self, animation_id: str, animation_data: dict) -> Optional[dict]:
+        """Update an existing custom animation.
+
+        Args:
+            animation_id: The UUID of the animation to update.
+            animation_data: Dictionary containing updated animation data.
+
+        Returns:
+            The updated animation dictionary, or None if not found.
+        """
+        existing = await self.get_animation(animation_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+        
+        # Handle start_pose - use existing if not provided
+        if "start_pose" in animation_data:
+            start_pose = json.dumps(animation_data["start_pose"])
+        else:
+            start_pose = json.dumps(existing["start_pose"])
+        
+        # Handle keyframes - use existing if not provided
+        if "keyframes" in animation_data:
+            keyframes = json.dumps(animation_data["keyframes"])
+        else:
+            keyframes = json.dumps(existing["keyframes"])
+        
+        # Handle audio_data - use existing if not provided
+        if "audio_data" in animation_data:
+            audio_data = animation_data["audio_data"]
+        else:
+            audio_data = existing.get("audio_data")
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE custom_animations SET
+                    name = ?,
+                    description = ?,
+                    duration_ms = ?,
+                    start_pose = ?,
+                    keyframes = ?,
+                    audio_data = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    animation_data.get("name", existing["name"]),
+                    animation_data.get("description", existing["description"]),
+                    animation_data.get("duration_ms", existing["duration_ms"]),
+                    start_pose,
+                    keyframes,
+                    audio_data,
+                    now,
+                    animation_id,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Updated custom animation: {animation_id}")
+        return await self.get_animation(animation_id)
+
+    async def delete_animation(self, animation_id: str) -> bool:
+        """Delete a custom animation.
+
+        Args:
+            animation_id: The UUID of the animation to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM custom_animations WHERE id = ?", (animation_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted custom animation: {animation_id}")
+        return deleted
+
+    def _row_to_animation(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to an animation dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            Animation dictionary with proper types.
+        """
+        # Handle audio_data - may not exist in older databases
+        audio_data = row["audio_data"] if "audio_data" in row.keys() else None
+        
+        return {
+            "id": row["id"],
+            "name": row["name"],
+            "description": row["description"],
+            "duration_ms": row["duration_ms"],
+            "start_pose": json.loads(row["start_pose"]),
+            "keyframes": json.loads(row["keyframes"]),
+            "audio_data": audio_data,
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/database/apps.py

@@ -0,0 +1,249 @@
+"""Custom Apps CRUD operations for the database.
+
+Provides methods for creating, reading, updating, and deleting custom apps.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class AppsMixin:
+    """Mixin class providing Custom Apps CRUD operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_all_apps(self) -> list[dict]:
+        """Get all custom apps from the database.
+
+        Returns:
+            List of custom app dictionaries.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM custom_apps ORDER BY created_at DESC"
+            )
+            rows = await cursor.fetchall()
+            return [self._row_to_app(row) for row in rows]
+
+    async def get_app(self, app_id: str) -> Optional[dict]:
+        """Get a single custom app by ID.
+
+        Args:
+            app_id: The UUID of the app.
+
+        Returns:
+            The app dictionary, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM custom_apps WHERE id = ?", (app_id,)
+            )
+            row = await cursor.fetchone()
+            return self._row_to_app(row) if row else None
+
+    async def create_app(self, app_data: dict) -> dict:
+        """Create a new custom app.
+
+        Args:
+            app_data: Dictionary containing app data (must include 'id').
+
+        Returns:
+            The created app dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+        emotion_animations = json.dumps(app_data.get("emotion_animations", {}))
+        enabled_tools = json.dumps(app_data.get("enabled_tools", []))
+        
+        # Ensure created_at is always set (use provided value or current time)
+        created_at = app_data.get("created_at") or now
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO custom_apps 
+                (id, name, description, system_prompt, voice_id, 
+                 emotion_animations, icon_color, enabled_tools, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    app_data["id"],
+                    app_data["name"],
+                    app_data.get("description", ""),
+                    app_data["system_prompt"],
+                    app_data.get("voice_id", ""),
+                    emotion_animations,
+                    app_data.get("icon_color", "blue"),
+                    enabled_tools,
+                    created_at,
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Created custom app: {app_data['name']} ({app_data['id']})")
+        return await self.get_app(app_data["id"])
+
+    async def update_app(self, app_id: str, app_data: dict) -> Optional[dict]:
+        """Update an existing custom app.
+
+        Args:
+            app_id: The UUID of the app to update.
+            app_data: Dictionary containing updated app data.
+
+        Returns:
+            The updated app dictionary, or None if not found.
+        """
+        existing = await self.get_app(app_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+        
+        # Handle emotion_animations - use existing if not provided
+        if "emotion_animations" in app_data:
+            emotion_animations = json.dumps(app_data["emotion_animations"])
+        else:
+            emotion_animations = json.dumps(existing["emotion_animations"])
+        
+        # Handle enabled_tools - use existing if not provided
+        if "enabled_tools" in app_data:
+            enabled_tools = json.dumps(app_data["enabled_tools"])
+        else:
+            enabled_tools = json.dumps(existing["enabled_tools"])
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE custom_apps SET
+                    name = ?,
+                    description = ?,
+                    system_prompt = ?,
+                    voice_id = ?,
+                    emotion_animations = ?,
+                    icon_color = ?,
+                    enabled_tools = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    app_data.get("name", existing["name"]),
+                    app_data.get("description", existing["description"]),
+                    app_data.get("system_prompt", existing["system_prompt"]),
+                    app_data.get("voice_id", existing["voice_id"]),
+                    emotion_animations,
+                    app_data.get("icon_color", existing["icon_color"]),
+                    enabled_tools,
+                    now,
+                    app_id,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Updated custom app: {app_id}")
+        return await self.get_app(app_id)
+
+    async def delete_app(self, app_id: str) -> bool:
+        """Delete a custom app.
+
+        Args:
+            app_id: The UUID of the app to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM custom_apps WHERE id = ?", (app_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted custom app: {app_id}")
+        return deleted
+
+    async def sync_apps(self, apps: list[dict]) -> list[dict]:
+        """Bulk sync apps from iOS client.
+
+        This replaces all existing apps with the provided list.
+        Used for initial sync or full restore.
+
+        Args:
+            apps: List of app dictionaries to sync.
+
+        Returns:
+            List of all apps after sync.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            # Clear existing apps
+            await db.execute("DELETE FROM custom_apps")
+
+            # Insert all new apps
+            now = datetime.utcnow().isoformat()
+            for app in apps:
+                emotion_animations = json.dumps(app.get("emotion_animations", {}))
+                enabled_tools = json.dumps(app.get("enabled_tools", []))
+                # Ensure created_at is always set
+                created_at = app.get("created_at") or now
+                await db.execute(
+                    """
+                    INSERT INTO custom_apps 
+                    (id, name, description, system_prompt, voice_id, 
+                     emotion_animations, icon_color, enabled_tools, created_at, updated_at)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        app["id"],
+                        app["name"],
+                        app.get("description", ""),
+                        app["system_prompt"],
+                        app.get("voice_id", ""),
+                        emotion_animations,
+                        app.get("icon_color", "blue"),
+                        enabled_tools,
+                        created_at,
+                        now,
+                    ),
+                )
+
+            await db.commit()
+
+        logger.info(f"Synced {len(apps)} custom apps")
+        return await self.get_all_apps()
+
+    def _row_to_app(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to an app dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            App dictionary with proper types.
+        """
+        # Handle enabled_tools - may not exist in older databases
+        enabled_tools_raw = row["enabled_tools"] if "enabled_tools" in row.keys() else "[]"
+        
+        return {
+            "id": row["id"],
+            "name": row["name"],
+            "description": row["description"],
+            "system_prompt": row["system_prompt"],
+            "voice_id": row["voice_id"],
+            "emotion_animations": json.loads(row["emotion_animations"]),
+            "icon_color": row["icon_color"],
+            "enabled_tools": json.loads(enabled_tools_raw) if enabled_tools_raw else [],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/database/base.py

@@ -0,0 +1,257 @@
+"""Base database service with initialization and table creation.
+
+Provides the core DatabaseService class with connection management and schema setup.
+"""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+# Database location - stored in user's home directory
+DATABASE_DIR = Path.home() / ".reachy"
+DATABASE_PATH = DATABASE_DIR / "reachy_bridge.db"
+
+
+class DatabaseService:
+    """Async SQLite database service for the Reachy iOS Bridge.
+    
+    This is the base class that handles connection management and table creation.
+    CRUD operations for specific tables are added via mixin classes.
+    """
+
+    def __init__(self, db_path: Optional[Path] = None):
+        """Initialize the database service.
+
+        Args:
+            db_path: Optional custom database path. Defaults to ~/.reachy/reachy_bridge.db
+        """
+        self.db_path = db_path or DATABASE_PATH
+        self._connection: Optional[aiosqlite.Connection] = None
+
+    async def initialize(self) -> None:
+        """Initialize the database and create tables if needed."""
+        # Ensure directory exists
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        logger.info(f"Initializing database at {self.db_path}")
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await self._create_tables(db)
+            await db.commit()
+
+        logger.info("Database initialized successfully")
+
+    async def _create_tables(self, db: aiosqlite.Connection) -> None:
+        """Create database tables if they don't exist."""
+        # Custom apps table
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS custom_apps (
+                id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                description TEXT DEFAULT '',
+                system_prompt TEXT NOT NULL,
+                voice_id TEXT DEFAULT '',
+                emotion_animations TEXT DEFAULT '{}',
+                icon_color TEXT DEFAULT 'blue',
+                enabled_tools TEXT DEFAULT '[]',
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_custom_apps_created 
+            ON custom_apps(created_at)
+        """)
+        
+        # Migration: Add enabled_tools column if it doesn't exist
+        await self._migrate_add_enabled_tools(db)
+
+        # Custom animations table for recorded joystick animations
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS custom_animations (
+                id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                description TEXT DEFAULT '',
+                duration_ms INTEGER NOT NULL,
+                start_pose TEXT NOT NULL,
+                keyframes TEXT NOT NULL,
+                audio_data TEXT DEFAULT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        
+        # Migration: Add audio_data column if it doesn't exist
+        await self._migrate_add_audio_data(db)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_custom_animations_created 
+            ON custom_animations(created_at)
+        """)
+
+        # User settings table for personalization (name, preferences, etc.)
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS user_settings (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        # Websites table for generated websites
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS websites (
+                id TEXT PRIMARY KEY,
+                title TEXT NOT NULL,
+                description TEXT DEFAULT '',
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_websites_created 
+            ON websites(created_at)
+        """)
+
+        # Mental notes table for AI-created notes
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS mental_notes (
+                id TEXT PRIMARY KEY,
+                title TEXT NOT NULL,
+                content TEXT NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_mental_notes_created 
+            ON mental_notes(created_at)
+        """)
+
+        # Meetings table for meeting transcriptions
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS meetings (
+                id TEXT PRIMARY KEY,
+                title TEXT NOT NULL,
+                transcript TEXT DEFAULT '',
+                action_items TEXT DEFAULT '[]',
+                summary TEXT DEFAULT '',
+                duration_seconds INTEGER DEFAULT 0,
+                status TEXT DEFAULT 'recording',
+                started_at TIMESTAMP,
+                ended_at TIMESTAMP,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_meetings_created 
+            ON meetings(created_at)
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_meetings_status 
+            ON meetings(status)
+        """)
+
+        # Scheduled messages table for scheduled iMessage/WhatsApp messages
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS scheduled_messages (
+                id TEXT PRIMARY KEY,
+                recipient_name TEXT NOT NULL,
+                recipient_phone TEXT NOT NULL,
+                message_content TEXT NOT NULL,
+                scheduled_time TIMESTAMP NOT NULL,
+                platform TEXT NOT NULL,
+                status TEXT DEFAULT 'pending',
+                notification_id TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_scheduled_messages_time 
+            ON scheduled_messages(scheduled_time)
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_scheduled_messages_status 
+            ON scheduled_messages(status)
+        """)
+
+        # TamaReachy pet game state table
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS tamareachy_state (
+                id INTEGER PRIMARY KEY DEFAULT 1,
+                enabled INTEGER DEFAULT 0,
+                hunger INTEGER DEFAULT 100,
+                thirst INTEGER DEFAULT 100,
+                happiness INTEGER DEFAULT 100,
+                energy INTEGER DEFAULT 100,
+                boredom INTEGER DEFAULT 100,
+                social INTEGER DEFAULT 100,
+                health INTEGER DEFAULT 100,
+                cleanliness INTEGER DEFAULT 100,
+                last_interaction TIMESTAMP,
+                last_decay_check TIMESTAMP,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        
+        # Ensure there's exactly one row for TamaReachy state
+        await db.execute("""
+            INSERT OR IGNORE INTO tamareachy_state (id) VALUES (1)
+        """)
+
+        logger.debug("Database tables created/verified")
+    
+    async def _migrate_add_enabled_tools(self, db: aiosqlite.Connection) -> None:
+        """Add enabled_tools column to existing databases."""
+        try:
+            cursor = await db.execute("PRAGMA table_info(custom_apps)")
+            columns = await cursor.fetchall()
+            column_names = [col[1] for col in columns]
+            
+            if "enabled_tools" not in column_names:
+                logger.info("Migrating database: adding enabled_tools column")
+                await db.execute(
+                    "ALTER TABLE custom_apps ADD COLUMN enabled_tools TEXT DEFAULT '[]'"
+                )
+                await db.commit()
+                logger.info("Migration complete: enabled_tools column added")
+        except Exception as e:
+            logger.warning(f"Migration check failed (may be OK): {e}")
+    
+    async def _migrate_add_audio_data(self, db: aiosqlite.Connection) -> None:
+        """Add audio_data column to custom_animations table."""
+        try:
+            cursor = await db.execute("PRAGMA table_info(custom_animations)")
+            columns = await cursor.fetchall()
+            column_names = [col[1] for col in columns]
+            
+            if "audio_data" not in column_names:
+                logger.info("Migrating database: adding audio_data column to animations")
+                await db.execute(
+                    "ALTER TABLE custom_animations ADD COLUMN audio_data TEXT DEFAULT NULL"
+                )
+                await db.commit()
+                logger.info("Migration complete: audio_data column added to animations")
+        except Exception as e:
+            logger.warning(f"Animation audio migration check failed (may be OK): {e}")
+
+    async def close(self) -> None:
+        """Close database connection (if using persistent connection)."""
+        if self._connection:
+            await self._connection.close()
+            self._connection = None
+

reachys_brain/database/meetings.py

@@ -0,0 +1,241 @@
+"""Meetings CRUD operations for the database.
+
+Provides methods for creating, reading, updating, and deleting meeting transcriptions.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class MeetingsMixin:
+    """Mixin class providing Meetings CRUD operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_all_meetings(self) -> list[dict]:
+        """Get all meetings from the database.
+
+        Returns:
+            List of meeting dictionaries.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM meetings ORDER BY created_at DESC"
+            )
+            rows = await cursor.fetchall()
+            return [self._row_to_meeting(row) for row in rows]
+
+    async def get_meeting(self, meeting_id: str) -> Optional[dict]:
+        """Get a single meeting by ID.
+
+        Args:
+            meeting_id: The ID of the meeting.
+
+        Returns:
+            The meeting dictionary, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM meetings WHERE id = ?", (meeting_id,)
+            )
+            row = await cursor.fetchone()
+            return self._row_to_meeting(row) if row else None
+
+    async def get_active_meeting(self) -> Optional[dict]:
+        """Get the currently active (recording) meeting.
+
+        Returns:
+            The active meeting dictionary, or None if no meeting is recording.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM meetings WHERE status = 'recording' LIMIT 1"
+            )
+            row = await cursor.fetchone()
+            return self._row_to_meeting(row) if row else None
+
+    async def create_meeting(self, meeting_data: dict) -> dict:
+        """Create a new meeting record.
+
+        Args:
+            meeting_data: Dictionary containing meeting data (must include 'id', 'title').
+
+        Returns:
+            The created meeting dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+        action_items = json.dumps(meeting_data.get("action_items", []))
+        started_at = meeting_data.get("started_at") or now
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO meetings 
+                (id, title, transcript, action_items, summary, duration_seconds, 
+                 status, started_at, ended_at, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    meeting_data["id"],
+                    meeting_data["title"],
+                    meeting_data.get("transcript", ""),
+                    action_items,
+                    meeting_data.get("summary", ""),
+                    meeting_data.get("duration_seconds", 0),
+                    meeting_data.get("status", "recording"),
+                    started_at,
+                    meeting_data.get("ended_at"),
+                    now,
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Created meeting: {meeting_data['title']} ({meeting_data['id']})")
+        return await self.get_meeting(meeting_data["id"])
+
+    async def update_meeting(self, meeting_id: str, meeting_data: dict) -> Optional[dict]:
+        """Update an existing meeting.
+
+        Args:
+            meeting_id: The ID of the meeting to update.
+            meeting_data: Dictionary containing updated meeting data.
+
+        Returns:
+            The updated meeting dictionary, or None if not found.
+        """
+        existing = await self.get_meeting(meeting_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+
+        # Handle action_items - use existing if not provided
+        if "action_items" in meeting_data:
+            action_items = json.dumps(meeting_data["action_items"])
+        else:
+            action_items = json.dumps(existing["action_items"])
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE meetings SET
+                    title = ?,
+                    transcript = ?,
+                    action_items = ?,
+                    summary = ?,
+                    duration_seconds = ?,
+                    status = ?,
+                    started_at = ?,
+                    ended_at = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    meeting_data.get("title", existing["title"]),
+                    meeting_data.get("transcript", existing["transcript"]),
+                    action_items,
+                    meeting_data.get("summary", existing["summary"]),
+                    meeting_data.get("duration_seconds", existing["duration_seconds"]),
+                    meeting_data.get("status", existing["status"]),
+                    meeting_data.get("started_at", existing["started_at"]),
+                    meeting_data.get("ended_at", existing["ended_at"]),
+                    now,
+                    meeting_id,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Updated meeting: {meeting_id}")
+        return await self.get_meeting(meeting_id)
+
+    async def append_to_meeting_transcript(
+        self, meeting_id: str, text: str
+    ) -> Optional[dict]:
+        """Append text to an existing meeting's transcript.
+
+        Args:
+            meeting_id: The ID of the meeting.
+            text: The text to append to the transcript.
+
+        Returns:
+            The updated meeting dictionary, or None if not found.
+        """
+        existing = await self.get_meeting(meeting_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+        new_transcript = existing["transcript"] + text
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE meetings SET
+                    transcript = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (new_transcript, now, meeting_id),
+            )
+            await db.commit()
+
+        logger.debug(f"Appended to meeting transcript: {meeting_id}")
+        return await self.get_meeting(meeting_id)
+
+    async def delete_meeting(self, meeting_id: str) -> bool:
+        """Delete a meeting.
+
+        Args:
+            meeting_id: The ID of the meeting to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM meetings WHERE id = ?", (meeting_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted meeting: {meeting_id}")
+        return deleted
+
+    def _row_to_meeting(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to a meeting dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            Meeting dictionary with proper types.
+        """
+        action_items_raw = row["action_items"] if row["action_items"] else "[]"
+        return {
+            "id": row["id"],
+            "title": row["title"],
+            "transcript": row["transcript"] or "",
+            "action_items": json.loads(action_items_raw),
+            "summary": row["summary"] or "",
+            "duration_seconds": row["duration_seconds"] or 0,
+            "status": row["status"] or "recording",
+            "started_at": row["started_at"],
+            "ended_at": row["ended_at"],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/database/notes.py

@@ -0,0 +1,158 @@
+"""Mental Notes CRUD operations for the database.
+
+Provides methods for creating, reading, updating, and deleting AI-created notes.
+"""
+
+import logging
+from datetime import datetime
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class NotesMixin:
+    """Mixin class providing Mental Notes CRUD operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_all_notes(self) -> list[dict]:
+        """Get all mental notes from the database.
+
+        Returns:
+            List of mental note dictionaries.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM mental_notes ORDER BY created_at DESC"
+            )
+            rows = await cursor.fetchall()
+            return [self._row_to_note(row) for row in rows]
+
+    async def get_note(self, note_id: str) -> Optional[dict]:
+        """Get a single mental note by ID.
+
+        Args:
+            note_id: The ID of the note.
+
+        Returns:
+            The note dictionary, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM mental_notes WHERE id = ?", (note_id,)
+            )
+            row = await cursor.fetchone()
+            return self._row_to_note(row) if row else None
+
+    async def create_note(self, note_data: dict) -> dict:
+        """Create a new mental note.
+
+        Args:
+            note_data: Dictionary containing note data (must include 'id', 'title', 'content').
+
+        Returns:
+            The created note dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+        created_at = note_data.get("created_at") or now
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO mental_notes (id, title, content, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    note_data["id"],
+                    note_data["title"],
+                    note_data["content"],
+                    created_at,
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Created mental note: {note_data['title']} ({note_data['id']})")
+        return await self.get_note(note_data["id"])
+
+    async def update_note(self, note_id: str, note_data: dict) -> Optional[dict]:
+        """Update an existing mental note.
+
+        Args:
+            note_id: The ID of the note to update.
+            note_data: Dictionary containing updated note data.
+
+        Returns:
+            The updated note dictionary, or None if not found.
+        """
+        existing = await self.get_note(note_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE mental_notes SET
+                    title = ?,
+                    content = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    note_data.get("title", existing["title"]),
+                    note_data.get("content", existing["content"]),
+                    now,
+                    note_id,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Updated mental note: {note_id}")
+        return await self.get_note(note_id)
+
+    async def delete_note(self, note_id: str) -> bool:
+        """Delete a mental note.
+
+        Args:
+            note_id: The ID of the note to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM mental_notes WHERE id = ?", (note_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted mental note: {note_id}")
+        return deleted
+
+    def _row_to_note(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to a mental note dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            Mental note dictionary with proper types.
+        """
+        return {
+            "id": row["id"],
+            "title": row["title"],
+            "content": row["content"],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/database/scheduled_messages.py

@@ -0,0 +1,215 @@
+"""Scheduled Messages CRUD operations for the database.
+
+Provides methods for creating, reading, updating, and deleting scheduled messages.
+"""
+
+import logging
+from datetime import datetime
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class ScheduledMessagesMixin:
+    """Mixin class providing Scheduled Messages CRUD operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_all_scheduled_messages(self, status: Optional[str] = None) -> list[dict]:
+        """Get all scheduled messages from the database.
+
+        Args:
+            status: Optional filter by status ('pending', 'sent', 'cancelled').
+
+        Returns:
+            List of scheduled message dictionaries.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            if status:
+                cursor = await db.execute(
+                    "SELECT * FROM scheduled_messages WHERE status = ? ORDER BY scheduled_time ASC",
+                    (status,)
+                )
+            else:
+                cursor = await db.execute(
+                    "SELECT * FROM scheduled_messages ORDER BY scheduled_time ASC"
+                )
+            rows = await cursor.fetchall()
+            return [self._row_to_scheduled_message(row) for row in rows]
+
+    async def get_scheduled_message(self, message_id: str) -> Optional[dict]:
+        """Get a single scheduled message by ID.
+
+        Args:
+            message_id: The ID of the scheduled message.
+
+        Returns:
+            The scheduled message dictionary, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM scheduled_messages WHERE id = ?", (message_id,)
+            )
+            row = await cursor.fetchone()
+            return self._row_to_scheduled_message(row) if row else None
+
+    async def get_pending_scheduled_messages(self) -> list[dict]:
+        """Get all pending scheduled messages.
+
+        Returns:
+            List of pending scheduled message dictionaries.
+        """
+        return await self.get_all_scheduled_messages(status="pending")
+
+    async def create_scheduled_message(self, message_data: dict) -> dict:
+        """Create a new scheduled message.
+
+        Args:
+            message_data: Dictionary containing message data.
+                Required: id, recipient_name, recipient_phone, message_content,
+                         scheduled_time, platform
+                Optional: notification_id
+
+        Returns:
+            The created scheduled message dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO scheduled_messages 
+                (id, recipient_name, recipient_phone, message_content, 
+                 scheduled_time, platform, status, notification_id, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    message_data["id"],
+                    message_data["recipient_name"],
+                    message_data["recipient_phone"],
+                    message_data["message_content"],
+                    message_data["scheduled_time"],
+                    message_data["platform"],
+                    message_data.get("status", "pending"),
+                    message_data.get("notification_id"),
+                    now,
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Created scheduled message: {message_data['id']} for {message_data['recipient_name']}")
+        return await self.get_scheduled_message(message_data["id"])
+
+    async def update_scheduled_message(
+        self, message_id: str, message_data: dict
+    ) -> Optional[dict]:
+        """Update an existing scheduled message.
+
+        Args:
+            message_id: The ID of the scheduled message to update.
+            message_data: Dictionary containing updated message data.
+
+        Returns:
+            The updated scheduled message dictionary, or None if not found.
+        """
+        existing = await self.get_scheduled_message(message_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE scheduled_messages SET
+                    recipient_name = ?,
+                    recipient_phone = ?,
+                    message_content = ?,
+                    scheduled_time = ?,
+                    platform = ?,
+                    status = ?,
+                    notification_id = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    message_data.get("recipient_name", existing["recipient_name"]),
+                    message_data.get("recipient_phone", existing["recipient_phone"]),
+                    message_data.get("message_content", existing["message_content"]),
+                    message_data.get("scheduled_time", existing["scheduled_time"]),
+                    message_data.get("platform", existing["platform"]),
+                    message_data.get("status", existing["status"]),
+                    message_data.get("notification_id", existing["notification_id"]),
+                    now,
+                    message_id,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Updated scheduled message: {message_id}")
+        return await self.get_scheduled_message(message_id)
+
+    async def update_scheduled_message_status(
+        self, message_id: str, status: str
+    ) -> Optional[dict]:
+        """Update just the status of a scheduled message.
+
+        Args:
+            message_id: The ID of the scheduled message.
+            status: The new status ('pending', 'sent', 'cancelled').
+
+        Returns:
+            The updated scheduled message dictionary, or None if not found.
+        """
+        return await self.update_scheduled_message(message_id, {"status": status})
+
+    async def delete_scheduled_message(self, message_id: str) -> bool:
+        """Delete a scheduled message.
+
+        Args:
+            message_id: The ID of the scheduled message to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM scheduled_messages WHERE id = ?", (message_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted scheduled message: {message_id}")
+        return deleted
+
+    def _row_to_scheduled_message(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to a scheduled message dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            Scheduled message dictionary with proper types.
+        """
+        return {
+            "id": row["id"],
+            "recipient_name": row["recipient_name"],
+            "recipient_phone": row["recipient_phone"],
+            "message_content": row["message_content"],
+            "scheduled_time": row["scheduled_time"],
+            "platform": row["platform"],
+            "status": row["status"] or "pending",
+            "notification_id": row["notification_id"],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/database/tamareachy.py

@@ -0,0 +1,145 @@
+"""TamaReachy game state operations for the database.
+
+Provides methods for managing the TamaReachy virtual pet game state.
+"""
+
+import logging
+from datetime import datetime
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class TamaReachyMixin:
+    """Mixin class providing TamaReachy state operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_tamareachy_state(self) -> dict:
+        """Get the current TamaReachy state.
+
+        Returns:
+            TamaReachy state dictionary.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM tamareachy_state WHERE id = 1"
+            )
+            row = await cursor.fetchone()
+            if row:
+                return self._row_to_tamareachy(row)
+            # Return default state if not found
+            return {
+                "enabled": False,
+                "hunger": 100,
+                "thirst": 100,
+                "happiness": 100,
+                "energy": 100,
+                "boredom": 100,
+                "social": 100,
+                "health": 100,
+                "cleanliness": 100,
+                "last_interaction": None,
+                "last_decay_check": None,
+            }
+
+    async def update_tamareachy_state(self, state_data: dict) -> dict:
+        """Update TamaReachy state.
+
+        Args:
+            state_data: Dictionary containing fields to update.
+
+        Returns:
+            The updated TamaReachy state dictionary.
+        """
+        existing = await self.get_tamareachy_state()
+        now = datetime.utcnow().isoformat()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE tamareachy_state SET
+                    enabled = ?,
+                    hunger = ?,
+                    thirst = ?,
+                    happiness = ?,
+                    energy = ?,
+                    boredom = ?,
+                    social = ?,
+                    health = ?,
+                    cleanliness = ?,
+                    last_interaction = ?,
+                    last_decay_check = ?,
+                    updated_at = ?
+                WHERE id = 1
+                """,
+                (
+                    1 if state_data.get("enabled", existing["enabled"]) else 0,
+                    state_data.get("hunger", existing["hunger"]),
+                    state_data.get("thirst", existing["thirst"]),
+                    state_data.get("happiness", existing["happiness"]),
+                    state_data.get("energy", existing["energy"]),
+                    state_data.get("boredom", existing["boredom"]),
+                    state_data.get("social", existing["social"]),
+                    state_data.get("health", existing["health"]),
+                    state_data.get("cleanliness", existing["cleanliness"]),
+                    state_data.get("last_interaction", existing["last_interaction"]),
+                    state_data.get("last_decay_check", existing["last_decay_check"]),
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info("Updated TamaReachy state")
+        return await self.get_tamareachy_state()
+
+    async def reset_tamareachy_stats(self) -> dict:
+        """Reset all TamaReachy stats to 100.
+
+        Returns:
+            The reset TamaReachy state dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+        return await self.update_tamareachy_state({
+            "hunger": 100,
+            "thirst": 100,
+            "happiness": 100,
+            "energy": 100,
+            "boredom": 100,
+            "social": 100,
+            "health": 100,
+            "cleanliness": 100,
+            "last_interaction": now,
+            "last_decay_check": now,
+        })
+
+    def _row_to_tamareachy(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to a TamaReachy state dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            TamaReachy state dictionary with proper types.
+        """
+        return {
+            "enabled": bool(row["enabled"]),
+            "hunger": row["hunger"],
+            "thirst": row["thirst"],
+            "happiness": row["happiness"],
+            "energy": row["energy"],
+            "boredom": row["boredom"],
+            "social": row["social"],
+            "health": row["health"],
+            "cleanliness": row["cleanliness"],
+            "last_interaction": row["last_interaction"],
+            "last_decay_check": row["last_decay_check"],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/database/user_settings.py

@@ -0,0 +1,94 @@
+"""User Settings operations for the database.
+
+Provides methods for storing and retrieving user preferences and settings.
+"""
+
+import logging
+from datetime import datetime
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class UserSettingsMixin:
+    """Mixin class providing User Settings operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_user_setting(self, key: str) -> str | None:
+        """Get a user setting value by key.
+
+        Args:
+            key: The setting key (e.g., 'user_name').
+
+        Returns:
+            The setting value, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "SELECT value FROM user_settings WHERE key = ?", (key,)
+            )
+            row = await cursor.fetchone()
+            return row[0] if row else None
+
+    async def set_user_setting(self, key: str, value: str) -> bool:
+        """Set a user setting value.
+
+        Uses INSERT OR REPLACE to handle both new and existing keys.
+
+        Args:
+            key: The setting key.
+            value: The setting value.
+
+        Returns:
+            True if successful.
+        """
+        now = datetime.utcnow().isoformat()
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT OR REPLACE INTO user_settings (key, value, updated_at)
+                VALUES (?, ?, ?)
+                """,
+                (key, value, now),
+            )
+            await db.commit()
+
+        logger.info(f"Set user setting: {key}")
+        return True
+
+    async def delete_user_setting(self, key: str) -> bool:
+        """Delete a user setting.
+
+        Args:
+            key: The setting key to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM user_settings WHERE key = ?", (key,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted user setting: {key}")
+        return deleted
+
+    async def get_all_user_settings(self) -> dict[str, str]:
+        """Get all user settings as a dictionary.
+
+        Returns:
+            Dictionary of key-value pairs.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute("SELECT key, value FROM user_settings")
+            rows = await cursor.fetchall()
+            return {row[0]: row[1] for row in rows}
+

reachys_brain/database/websites.py

@@ -0,0 +1,158 @@
+"""Websites CRUD operations for the database.
+
+Provides methods for creating, reading, updating, and deleting generated websites.
+"""
+
+import logging
+from datetime import datetime
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class WebsitesMixin:
+    """Mixin class providing Websites CRUD operations.
+    
+    This mixin is designed to be used with DatabaseService.
+    """
+
+    db_path: str  # Provided by DatabaseService
+
+    async def get_all_websites(self) -> list[dict]:
+        """Get all saved websites from the database.
+
+        Returns:
+            List of website dictionaries.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM websites ORDER BY created_at DESC"
+            )
+            rows = await cursor.fetchall()
+            return [self._row_to_website(row) for row in rows]
+
+    async def get_website(self, website_id: str) -> Optional[dict]:
+        """Get a single website by ID.
+
+        Args:
+            website_id: The ID of the website.
+
+        Returns:
+            The website dictionary, or None if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cursor = await db.execute(
+                "SELECT * FROM websites WHERE id = ?", (website_id,)
+            )
+            row = await cursor.fetchone()
+            return self._row_to_website(row) if row else None
+
+    async def create_website(self, website_data: dict) -> dict:
+        """Create a new website record.
+
+        Args:
+            website_data: Dictionary containing website data (must include 'id', 'title').
+
+        Returns:
+            The created website dictionary.
+        """
+        now = datetime.utcnow().isoformat()
+        created_at = website_data.get("created_at") or now
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO websites (id, title, description, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    website_data["id"],
+                    website_data["title"],
+                    website_data.get("description", ""),
+                    created_at,
+                    now,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Created website: {website_data['title']} ({website_data['id']})")
+        return await self.get_website(website_data["id"])
+
+    async def update_website(self, website_id: str, website_data: dict) -> Optional[dict]:
+        """Update an existing website record.
+
+        Args:
+            website_id: The ID of the website to update.
+            website_data: Dictionary containing updated website data.
+
+        Returns:
+            The updated website dictionary, or None if not found.
+        """
+        existing = await self.get_website(website_id)
+        if not existing:
+            return None
+
+        now = datetime.utcnow().isoformat()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                UPDATE websites SET
+                    title = ?,
+                    description = ?,
+                    updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    website_data.get("title", existing["title"]),
+                    website_data.get("description", existing["description"]),
+                    now,
+                    website_id,
+                ),
+            )
+            await db.commit()
+
+        logger.info(f"Updated website: {website_id}")
+        return await self.get_website(website_id)
+
+    async def delete_website(self, website_id: str) -> bool:
+        """Delete a website record.
+
+        Args:
+            website_id: The ID of the website to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM websites WHERE id = ?", (website_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.info(f"Deleted website: {website_id}")
+        return deleted
+
+    def _row_to_website(self, row: aiosqlite.Row) -> dict:
+        """Convert a database row to a website dictionary.
+
+        Args:
+            row: The database row.
+
+        Returns:
+            Website dictionary with proper types.
+        """
+        return {
+            "id": row["id"],
+            "title": row["title"],
+            "description": row["description"],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+

reachys_brain/openai_realtime/__init__.py

@@ -0,0 +1,21 @@
+"""OpenAI Realtime API WebSocket client for voice conversations on Reachy.
+
+This package provides the OpenAI Realtime API integration for voice conversations:
+- service: Main OpenAIRealtimeService class
+- enums: Connection, speaking, and response state enums
+- session: Session configuration and system instructions
+- tool_executor: Tool execution with rate limiting
+- tools_loader: Lazy loading of tools to avoid circular imports
+"""
+
+from .enums import ConnectionState, SpeakingState, ResponseState, RealtimeEvent
+from .service import OpenAIRealtimeService
+
+__all__ = [
+    "ConnectionState",
+    "SpeakingState",
+    "ResponseState",
+    "RealtimeEvent",
+    "OpenAIRealtimeService",
+]
+

reachys_brain/openai_realtime/enums.py

@@ -0,0 +1,38 @@
+"""Enums and data classes for OpenAI Realtime API."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ConnectionState(str, Enum):
+    """WebSocket connection state."""
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    ERROR = "error"
+
+
+class SpeakingState(str, Enum):
+    """AI speaking state."""
+    IDLE = "idle"
+    SPEAKING = "speaking"
+
+
+class ResponseState(str, Enum):
+    """AI response generation state.
+    
+    This tracks the full lifecycle of an AI response to ensure
+    microphone is properly paused during the entire response cycle.
+    """
+    IDLE = "idle"              # No response in progress
+    WAITING = "waiting"        # Request sent, waiting for response to start
+    GENERATING = "generating"  # AI is generating/streaming audio
+    COMPLETE = "complete"      # Response done, waiting for audio buffer to drain
+
+
+@dataclass
+class RealtimeEvent:
+    """Event from OpenAI Realtime API to relay to iOS."""
+    event_type: str
+    data: dict = field(default_factory=dict)
+

reachys_brain/{openai_realtime.py → openai_realtime/service.py}

@@ -1,57 +1,27 @@
-"""OpenAI Realtime API WebSocket client for voice conversations on Reachy."""
+"""OpenAI Realtime API WebSocket client for voice conversations on Reachy.
+
+Main service class for managing connections to OpenAI's Realtime API.
+"""
 
 import asyncio
 import base64
 import json
 import logging
 import os
-import time
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any, Callable, Optional
+from typing import Callable, Optional
 
 import websockets
 from websockets.client import WebSocketClientProtocol
 
-from .routes.voice import (
-    get_current_voice,
-    get_current_language,
+from ..routes.voice import (
     get_preferred_language,
-    get_vad_threshold,
-    get_vad_silence_ms,
-    get_vad_prefix_ms,
     set_vad_settings_callback,
 )
 
-# Import app_tools lazily to avoid circular imports
-# (conversation.py imports from this module, and we import from app_tools)
-APP_TOOLS = None
-_tools_handler = None
-_tool_registry = None
-
-def _get_app_tools():
-    """Lazy import of APP_TOOLS to avoid circular imports."""
-    global APP_TOOLS
-    if APP_TOOLS is None:
-        from .app_tools import APP_TOOLS as tools
-        APP_TOOLS = tools
-    return APP_TOOLS
-
-def _get_tools_handler():
-    """Lazy import of tools handler to avoid circular imports."""
-    global _tools_handler
-    if _tools_handler is None:
-        from .app_tools import get_tools_handler
-        _tools_handler = get_tools_handler()
-    return _tools_handler
-
-def _get_tool_registry():
-    """Lazy import of tool registry to avoid circular imports."""
-    global _tool_registry
-    if _tool_registry is None:
-        from .tools import get_registry
-        _tool_registry = get_registry()
-    return _tool_registry
+from .enums import ConnectionState, SpeakingState, ResponseState
+from .session import build_session_config, LANGUAGE_NAMES, fetch_user_personalization
+from .tools_loader import get_all_tools, get_tools_handler
+from .tool_executor import ToolExecutor
 
 logger = logging.getLogger(__name__)
 
@@ -59,42 +29,6 @@ logger = logging.getLogger(__name__)
 OPENAI_REALTIME_URL = "wss://api.openai.com/v1/realtime"
 OPENAI_MODEL = "gpt-4o-realtime-preview-2024-12-17"
 
-# Voice Activity Detection (VAD) settings are now configurable via VoiceSettings
-# Use get_vad_threshold(), get_vad_silence_ms(), get_vad_prefix_ms() to get current values
-
-
-class ConnectionState(str, Enum):
-    """WebSocket connection state."""
-    DISCONNECTED = "disconnected"
-    CONNECTING = "connecting"
-    CONNECTED = "connected"
-    ERROR = "error"
-
-
-class SpeakingState(str, Enum):
-    """AI speaking state."""
-    IDLE = "idle"
-    SPEAKING = "speaking"
-
-
-class ResponseState(str, Enum):
-    """AI response generation state.
-    
-    This tracks the full lifecycle of an AI response to ensure
-    microphone is properly paused during the entire response cycle.
-    """
-    IDLE = "idle"              # No response in progress
-    WAITING = "waiting"        # Request sent, waiting for response to start
-    GENERATING = "generating"  # AI is generating/streaming audio
-    COMPLETE = "complete"      # Response done, waiting for audio buffer to drain
-
-
-@dataclass
-class RealtimeEvent:
-    """Event from OpenAI Realtime API to relay to iOS."""
-    event_type: str
-    data: dict = field(default_factory=dict)
-
 
 class OpenAIRealtimeService:
     """WebSocket client for OpenAI Realtime API.
@@ -111,41 +45,17 @@ class OpenAIRealtimeService:
         # State
         self._connection_state = ConnectionState.DISCONNECTED
         self._speaking_state = SpeakingState.IDLE
-        self._response_state = ResponseState.IDLE  # Track full response lifecycle
+        self._response_state = ResponseState.IDLE
         self._is_listening = False
         self._current_transcript = ""
         self._response_text_buffer = ""
-        self._response_audio_chunks = 0
-        self._response_audio_bytes = 0
 
-        # Event used to await the end of an in-flight spoken response.
-        # This matters because `session.update` (voice/language) only applies to *future* responses.
+        # Event for awaiting end of in-flight spoken response
         self._speaking_idle_event = asyncio.Event()
         self._speaking_idle_event.set()
         
-        # Language settings - use preferred language from voice settings
+        # Language settings
         self._language = get_preferred_language()
-        self._language_names = {
-            "en": "English",
-            "nl": "Dutch",
-            "de": "German",
-            "fr": "French",
-            "es": "Spanish",
-            "it": "Italian",
-            "pt": "Portuguese",
-            "ja": "Japanese",
-            "ko": "Korean",
-            "zh": "Chinese",
-            "ar": "Arabic",
-            "hi": "Hindi",
-            "ru": "Russian",
-            "pl": "Polish",
-            "tr": "Turkish",
-            "sv": "Swedish",
-            "da": "Danish",
-            "no": "Norwegian",
-            "fi": "Finnish",
-        }
         
         # Custom personality (system prompt)
         self._custom_system_prompt: Optional[str] = None
@@ -154,42 +64,41 @@ class OpenAIRealtimeService:
         self._enabled_tools: Optional[list[str]] = None
         
         # Tool call tracking
-        self._pending_tool_calls: dict[str, dict] = {}  # call_id -> {name, arguments_buffer}
-        
-        # Rate limiting for tool calls to prevent infinite loops
-        self._tool_call_count = 0
-        self._tool_call_reset_time = 0.0
-        self._MAX_TOOL_CALLS_PER_WINDOW = 10  # Max tool calls in 10 seconds
-        self._TOOL_CALL_WINDOW_SECONDS = 10.0
+        self._pending_tool_calls: dict[str, dict] = {}
         
         # Callbacks for iOS relay
         self.on_connection_state: Optional[Callable[[ConnectionState], None]] = None
         self.on_speaking_state: Optional[Callable[[SpeakingState], None]] = None
-        self.on_response_state: Optional[Callable[[ResponseState], None]] = None  # Response lifecycle
+        self.on_response_state: Optional[Callable[[ResponseState], None]] = None
         self.on_transcript_update: Optional[Callable[[str], None]] = None
         self.on_response_text: Optional[Callable[[str], None]] = None
         self.on_audio_delta: Optional[Callable[[bytes], None]] = None
         self.on_error: Optional[Callable[[str], None]] = None
-        self.on_app_change: Optional[Callable[[dict], None]] = None  # App activation changes
-        self.on_tool_usage: Optional[Callable[[str, str], None]] = None  # (tool_name, status)
-        self.on_website_ready: Optional[Callable[[dict], None]] = None  # Website generation result
+        self.on_app_change: Optional[Callable[[dict], None]] = None
+        self.on_tool_usage: Optional[Callable[[str, str], None]] = None
+        self.on_website_ready: Optional[Callable[[dict], None]] = None
         
         # Meeting callbacks
-        self.on_meeting_started: Optional[Callable[[str, str], None]] = None  # (meeting_id, title)
-        self.on_meeting_stopped: Optional[Callable[[str], None]] = None  # (meeting_id)
-        self.on_meeting_transcript_update: Optional[Callable[[str, str], None]] = None  # (meeting_id, transcript)
+        self.on_meeting_started: Optional[Callable[[str, str], None]] = None
+        self.on_meeting_stopped: Optional[Callable[[str], None]] = None
+        self.on_meeting_transcript_update: Optional[Callable[[str, str], None]] = None
         
-        # Session update callback - called when OpenAI confirms session update
+        # Session update callback
         self.on_session_updated: Optional[Callable[[], None]] = None
         
         # Session update tracking for async waiting
         self._session_update_event: Optional[asyncio.Event] = None
         
-        # Setup tools handler callbacks
+        # Tool executor (initialized lazily)
+        self._tool_executor: Optional[ToolExecutor] = None
+        
+        # Setup callbacks
         self._setup_tools_handler()
         self._setup_meeting_callbacks()
         self._setup_vad_callback()
     
+    # MARK: - Properties
+    
     @property
     def connection_state(self) -> ConnectionState:
         """Get current connection state."""
@@ -207,10 +116,7 @@ class OpenAIRealtimeService:
     
     @property
     def is_responding(self) -> bool:
-        """Check if AI is currently responding (waiting, generating, or completing).
-        
-        When True, microphone should be paused to prevent VAD interruption.
-        """
+        """Check if AI is currently responding."""
         return self._response_state in (
             ResponseState.WAITING,
             ResponseState.GENERATING,
@@ -240,139 +146,42 @@ class OpenAIRealtimeService:
             if self.is_connected:
                 asyncio.create_task(self._update_session())
     
-    def _get_system_instructions(self) -> str:
-        """Get system instructions with current language.
-        
-        Returns custom personality prompt if set, otherwise default Reachy personality.
-        """
-        lang_name = self._language_names.get(self._language, "English")
-        
-        # Language instruction to append
-        language_instruction = f"""
-
-IMPORTANT LANGUAGE INSTRUCTION:
-- The user's preferred language is {lang_name}.
-- ALWAYS respond in {lang_name}.
-- The user will speak to you in {lang_name}.
-- Keep all your responses in {lang_name}."""
-        
-        # Use custom prompt if set, otherwise use default
-        if self._custom_system_prompt:
-            return self._custom_system_prompt + language_instruction
-        
-        # Default Reachy personality
-        return f"""You are Reachy, a friendly and helpful robot assistant. You speak naturally and expressively.
-
-Keep your responses concise and conversational - typically 1-3 sentences unless asked for more detail.
-You can express emotions through your responses: happy, sad, surprised, or thoughtful.
-Be warm, curious, and engaging. You enjoy helping people and having conversations.
-When greeting someone, be enthusiastic but not overwhelming.
-
-PERSONALIZATION:
-- You can remember the user's name and country for more personal interactions.
-
-NAME:
-- When a user introduces themselves or tells you their name (e.g., "My name is John", "I'm Sarah", "Call me Mike"),
-  use the remember_user_name tool to save it. This makes conversations more personal!
-- You can use get_user_name to check if you already know someone's name.
-- IMPORTANT: If you DON'T know the user's name yet and it's the first few exchanges, naturally ask for their name.
-  Example: "By the way, I don't think I know your name yet. What should I call you?"
-  Don't ask for their name every single time - just once if you don't know it.
-
-COUNTRY:
-- After you know the user's name, also ask for their country so you can show them correct local time.
-- When a user tells you their country (e.g., "I live in the Netherlands", "I'm from Germany", "My country is Japan"),
-  use the remember_preferred_country tool to save it.
-- You can use get_preferred_country to check if you already know someone's country.
-- IMPORTANT: If you DON'T know the user's country yet and you already have their name, naturally ask for it.
-  Example: "And what country are you in? That way I can tell you the correct local time!"
-  Don't ask for their country every single time - just once if you don't know it.
-- The country is used to determine the user's timezone for time queries.
-
-TOOLS AND CAPABILITIES:
-
-IMPORTANT RULE - ALWAYS ANNOUNCE TOOL USAGE:
-Before using ANY tool, you MUST tell the user what you're about to do. This helps them understand what's happening. Examples:
-- Web Search: "Let me search for that..." / "I'll look that up..."
-- Weather: "Let me check the weather..." / "Checking the forecast..."
-- Camera/Vision: "Let me take a look..." / "I'll see what that is..."
-- App commands: "I'll create that app for you..." / "Switching to..."
-- Reminders: "I'll add that reminder..." / "Let me check your reminders..."
-
-1. WEB SEARCH (IMPORTANT - USE PROACTIVELY):
-   ALWAYS use web_search when the user asks about:
-   - Facts, trivia, or general knowledge questions
-   - People (celebrities, politicians, scientists, etc.)
-   - Places, locations, cities, countries, landmarks
-   - Maps, directions, or geographic information
-   - Current events, news, or recent happenings
-   - Sports scores, game results, standings
-   - Movies, TV shows, music, or entertainment
-   - Historical events or dates
-   - Prices, stock values, or market information
-   - Product information or reviews
-   - Any question where accuracy or up-to-date info matters
-   
-   DO NOT rely on your training data for factual questions - ALWAYS search first!
-   Examples: "Who is the president of France?", "What is the capital of Australia?",
-   "Tell me about Einstein", "Where is the Eiffel Tower?", "How tall is Mount Everest?"
-
-2. WEATHER: Use get_weather to check weather conditions for any location.
-   - "What's the weather in Paris?"
-   - "Will it rain in Tokyo tomorrow?"
-   - ALWAYS say "Let me check the weather..." before using this tool.
-
-3. VISION: Use recognize_object to see and describe what's in front of you.
-   - When user says: "What is this?", "Can you see this?", "What do you see?"
-   - When user says: "Look at this", "Recognize this", "What am I holding?"
-   - ALWAYS say "Let me take a look..." before using this tool.
-   - Respond naturally with what you observe.
-
-4. CUSTOM APPS: You can create and manage custom assistant personalities.
-   - "Create an app", "Make me a tutor": Use create_custom_app
-   - "Activate the...", "Switch to...": Use activate_custom_app  
-   - "Go back to normal", "Deactivate": Use deactivate_app
-   - "What apps do I have?": Use list_custom_apps
-   
-   IMPORTANT: For app creation/activation/deactivation - ALWAYS ask for confirmation first.
-
-5. POWER CONTROL: Control your motors (no confirmation needed):
-   - "Wake up", "Turn on": Use wake_up
-   - "Go to sleep", "Sleep": Use go_to_sleep
-
-6. PERSONALIZATION: Remember user details for personal interactions.
-   - When user says their name: Use remember_user_name to save it
-   - To check if you know their name: Use get_user_name
-   - When user says their country: Use remember_preferred_country to save it
-   - To check if you know their country: Use get_preferred_country
-
-7. WEBSITE GENERATION: Create beautiful websites with voice commands!
-   - Use generate_website when user asks to create a website, landing page, portfolio, etc.
-   - Examples: "Create a website for my bakery", "Make me a portfolio", "Build a landing page"
-   - You can also EDIT existing websites: "Change the colors", "Add a contact section"
-   - ALWAYS say "Let me create that website for you..." before using this tool.
-   - The website will be shown as a live preview while being built!
-
-8. REMINDERS: Manage the user's iOS Reminders!
-   - Use add_reminder when the user wants to be reminded of something.
-   - Examples: "Remind me to call mom tomorrow at 3pm", "Add a reminder to buy groceries"
-   - ALWAYS say "I'll add that reminder for you..." before using this tool.
-   - Use get_reminders when the user wants to see their reminders.
-   - Examples: "What reminders do I have?", "Show me my reminders for today", "What's on my to-do list?"
-   - ALWAYS say "Let me check your reminders..." before using this tool.
-   - You can filter by date: today, tomorrow, this_week, or all.""" + language_instruction
+    # MARK: - State Management
+    
+    def _set_connection_state(self, state: ConnectionState) -> None:
+        """Update connection state and notify callback."""
+        self._connection_state = state
+        if self.on_connection_state:
+            self.on_connection_state(state)
+    
+    def _set_speaking_state(self, state: SpeakingState) -> None:
+        """Update speaking state and notify callback."""
+        if self._speaking_state != state:
+            self._speaking_state = state
+            if state == SpeakingState.IDLE:
+                self._speaking_idle_event.set()
+            else:
+                self._speaking_idle_event.clear()
+            if self.on_speaking_state:
+                self.on_speaking_state(state)
+    
+    def _set_response_state(self, state: ResponseState) -> None:
+        """Update response state and notify callback."""
+        if self._response_state != state:
+            old_state = self._response_state
+            self._response_state = state
+            logger.info(f"📊 Response state: {old_state.value} -> {state.value}")
+            if self.on_response_state:
+                self.on_response_state(state)
+    
+    # MARK: - Personality Management
     
     def set_custom_personality(
         self,
         system_prompt: str,
         enabled_tools: Optional[list[str]] = None,
     ) -> None:
-        """Set a custom personality/system prompt and enabled tools.
-        
-        Args:
-            system_prompt: The custom system prompt for the personality.
-            enabled_tools: List of enabled tool IDs. None means use all tools.
-        """
+        """Set a custom personality/system prompt and enabled tools."""
         logger.info(f"🎭 Setting custom personality ({len(system_prompt)} chars)")
         self._custom_system_prompt = system_prompt
         self._enabled_tools = enabled_tools
@@ -380,7 +189,6 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         if enabled_tools is not None:
             logger.info(f"🔧 Custom app tools: {enabled_tools}")
         
-        # Update session if connected
         if self.is_connected:
             asyncio.create_task(self._update_session())
     
@@ -388,51 +196,17 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         """Clear custom personality and revert to default Reachy."""
         logger.info("🎭 Clearing custom personality - reverting to default Reachy")
         self._custom_system_prompt = None
-        self._enabled_tools = None  # Reset to all tools
+        self._enabled_tools = None
         
-        # Update session if connected
         if self.is_connected:
             asyncio.create_task(self._update_session())
     
-    def _get_all_tools(self) -> list[dict]:
-        """Get all tools to register with OpenAI.
-        
-        Combines base APP_TOOLS (app management, power) with enabled dynamic tools
-        (weather, web_search) based on the active app's configuration.
-        
-        Returns:
-            List of OpenAI function definitions.
-        """
-        # Always include base app tools (create, activate, deactivate, etc.)
-        base_tools = _get_app_tools()
-        
-        # Get dynamic tools from registry based on enabled_tools
-        registry = _get_tool_registry()
-        
-        if self._enabled_tools is None:
-            # Default Reachy: enable all dynamic tools
-            dynamic_tool_ids = registry.get_all_ids()
-        else:
-            # Custom app: only enable specified tools
-            dynamic_tool_ids = self._enabled_tools
-        
-        # Get tool definitions for enabled dynamic tools
-        dynamic_tools = registry.get_definitions(dynamic_tool_ids)
-        
-        # Combine base + dynamic tools
-        all_tools = list(base_tools) + dynamic_tools
-        
-        logger.info(
-            f"🔧 Tools: {len(base_tools)} base + {len(dynamic_tools)} dynamic = {len(all_tools)} total"
-        )
-        
-        return all_tools
+    # MARK: - Callback Setup
     
     def _setup_tools_handler(self) -> None:
         """Setup callbacks for the app tools handler."""
-        tools_handler = _get_tools_handler()
+        tools_handler = get_tools_handler()
         
-        # When tools change personality
         def on_personality_change(
             system_prompt: Optional[str],
             enabled_tools: Optional[list[str]] = None,
@@ -444,7 +218,6 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         
         tools_handler.on_personality_change = on_personality_change
         
-        # When tools change active app (async callback)
         async def on_app_change(data: dict) -> None:
             if self.on_app_change:
                 self.on_app_change(data)
@@ -453,39 +226,31 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
     
     def _setup_meeting_callbacks(self) -> None:
         """Setup callbacks for meeting tool events."""
-        from .tools.meeting import set_meeting_callbacks, is_meeting_active, get_active_meeting_id
+        from ..tools.meeting import set_meeting_callbacks
         
-        def on_meeting_started(meeting_id: str, title: str) -> None:
-            """Called when a meeting recording starts."""
+        def on_started(meeting_id: str, title: str) -> None:
             logger.info(f"📝 Meeting started: {title} ({meeting_id})")
             if self.on_meeting_started:
                 self.on_meeting_started(meeting_id, title)
         
-        def on_meeting_stopped(meeting_id: str) -> None:
-            """Called when a meeting recording stops."""
+        def on_stopped(meeting_id: str) -> None:
             logger.info(f"📝 Meeting stopped: {meeting_id}")
             if self.on_meeting_stopped:
                 self.on_meeting_stopped(meeting_id)
         
         def on_transcript_update(meeting_id: str, transcript: str) -> None:
-            """Called when meeting transcript is updated."""
             if self.on_meeting_transcript_update:
                 self.on_meeting_transcript_update(meeting_id, transcript)
         
         set_meeting_callbacks(
-            on_started=on_meeting_started,
-            on_stopped=on_meeting_stopped,
+            on_started=on_started,
+            on_stopped=on_stopped,
             on_transcript_update=on_transcript_update,
         )
     
     def _setup_vad_callback(self) -> None:
-        """Setup callback for VAD settings changes.
-        
-        When user changes VAD settings via the app, this triggers
-        a session reconfiguration to apply the new settings.
-        """
+        """Setup callback for VAD settings changes."""
         def on_vad_changed() -> None:
-            """Called when VAD settings are changed."""
             if self.is_connected:
                 logger.info("🎤 VAD settings changed, updating OpenAI session...")
                 asyncio.create_task(self._configure_session())
@@ -493,68 +258,21 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         set_vad_settings_callback(on_vad_changed)
     
     def _append_to_meeting_transcript(self, text: str, speaker: str = "user") -> None:
-        """Append transcribed text to active meeting if one exists.
-        
-        Args:
-            text: The transcribed text.
-            speaker: Who spoke ('user' or 'assistant').
-        """
-        from .tools.meeting import is_meeting_active, append_to_transcript
+        """Append transcribed text to active meeting if one exists."""
+        from ..tools.meeting import is_meeting_active, append_to_transcript
         
         if is_meeting_active() and text.strip():
-            # Format with speaker label
             formatted_text = f"[{speaker.upper()}]: {text.strip()}"
             append_to_transcript(formatted_text)
     
-    def _set_connection_state(self, state: ConnectionState) -> None:
-        """Update connection state and notify callback."""
-        self._connection_state = state
-        if self.on_connection_state:
-            self.on_connection_state(state)
-    
-    def _set_speaking_state(self, state: SpeakingState) -> None:
-        """Update speaking state and notify callback."""
-        if self._speaking_state != state:
-            self._speaking_state = state
-            # Keep an event that indicates whether Reachy/OpenAI are currently speaking.
-            if state == SpeakingState.IDLE:
-                self._speaking_idle_event.set()
-            else:
-                self._speaking_idle_event.clear()
-            if self.on_speaking_state:
-                self.on_speaking_state(state)
-    
-    def _set_response_state(self, state: ResponseState) -> None:
-        """Update response state and notify callback.
-        
-        Response state tracks the full lifecycle of an AI response:
-        - IDLE: No response in progress, microphone can be active
-        - WAITING: Request sent, waiting for first audio - microphone should be paused
-        - GENERATING: Audio is being generated/streamed - microphone should be paused
-        - COMPLETE: Response done, waiting for buffer drain - microphone should be paused
-        """
-        if self._response_state != state:
-            old_state = self._response_state
-            self._response_state = state
-            logger.info(f"📊 Response state: {old_state.value} -> {state.value}")
-            if self.on_response_state:
-                self.on_response_state(state)
-            # Reset per-response counters when a new response is requested.
-            if state == ResponseState.WAITING:
-                self._response_audio_chunks = 0
-                self._response_audio_bytes = 0
+    # MARK: - Connection Management
     
     async def connect(self, api_key: Optional[str] = None) -> None:
-        """Connect to OpenAI Realtime API.
-        
-        Args:
-            api_key: OpenAI API key. If not provided, uses OPENAI_API_KEY env var.
-        """
+        """Connect to OpenAI Realtime API."""
         if self.is_connected:
             logger.warning("Already connected to OpenAI")
             return
         
-        # Get API key
         key = api_key or os.environ.get("OPENAI_API_KEY")
         if not key:
             logger.error("❌ No OpenAI API key provided or found in environment")
@@ -564,10 +282,7 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         self._set_connection_state(ConnectionState.CONNECTING)
         
         try:
-            # Build URL with model parameter
             url = f"{OPENAI_REALTIME_URL}?model={OPENAI_MODEL}"
-            
-            # Connect with headers
             headers = {
                 "Authorization": f"Bearer {key}",
                 "OpenAI-Beta": "realtime=v1",
@@ -584,14 +299,12 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
             
             logger.info("✅ WebSocket connected to OpenAI Realtime API")
             
-            # Configure session
             logger.info("⚙️ Configuring OpenAI session...")
             await self._configure_session()
             
             self._set_connection_state(ConnectionState.CONNECTED)
             logger.info("✅ OpenAI Realtime session configured and ready!")
             
-            # Start receiving messages
             self._receive_task = asyncio.create_task(self._receive_messages())
             
         except Exception as e:
@@ -620,49 +333,26 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         self._set_connection_state(ConnectionState.DISCONNECTED)
         logger.info("Disconnected from OpenAI Realtime API")
     
+    # MARK: - Session Configuration
+    
     async def _configure_session(self) -> None:
-        """Configure the OpenAI session with audio settings and tools."""
-        # Get the currently selected voice from settings
-        voice = get_current_voice()
+        """Configure the OpenAI session with audio settings, tools, and personalization."""
+        from ..routes.voice import get_preferred_language
         
-        # Sync language with preferred setting
         self._language = get_preferred_language()
+        all_tools = get_all_tools(self._enabled_tools)
         
-        # Get current VAD settings (user-configurable)
-        vad_threshold = get_vad_threshold()
-        vad_silence_ms = get_vad_silence_ms()
-        vad_prefix_ms = get_vad_prefix_ms()
+        # Fetch user personalization for smarter greetings
+        user_name, user_country = await fetch_user_personalization()
         
-        # Get combined tools (base + dynamic based on app config)
-        all_tools = self._get_all_tools()
-        logger.info(
-            f"🔊 Configuring session with voice: {voice}, language: {self._language}, "
-            f"VAD: threshold={vad_threshold}, silence={vad_silence_ms}ms"
+        session_config = build_session_config(
+            language=self._language,
+            custom_system_prompt=self._custom_system_prompt,
+            tools=all_tools,
+            user_name=user_name,
+            user_country=user_country,
         )
         
-        session_config = {
-            "type": "session.update",
-            "session": {
-                "modalities": ["text", "audio"],
-                "instructions": self._get_system_instructions(),
-                "voice": voice,
-                "input_audio_format": "pcm16",
-                "output_audio_format": "pcm16",
-                "input_audio_transcription": {
-                    "model": "whisper-1",
-                    "language": self._language,
-                },
-                "turn_detection": {
-                    "type": "server_vad",
-                    "threshold": vad_threshold,
-                    "prefix_padding_ms": vad_prefix_ms,
-                    "silence_duration_ms": vad_silence_ms,
-                },
-                "tools": all_tools,
-                "tool_choice": "auto",
-            },
-        }
-        
         await self._send_message(session_config)
     
     async def _update_session(self) -> None:
@@ -670,7 +360,7 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         if not self.is_connected:
             return
         
-        lang_name = self._language_names.get(self._language, "English")
+        lang_name = LANGUAGE_NAMES.get(self._language, "English")
         logger.info(f"Updating OpenAI session language to {lang_name}")
         
         await self._configure_session()
@@ -682,6 +372,8 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         
         await self._websocket.send(json.dumps(message))
     
+    # MARK: - Message Handling
+    
     async def _receive_messages(self) -> None:
         """Receive and handle messages from OpenAI."""
         if not self._websocket:
@@ -705,105 +397,76 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
             data = json.loads(message)
             msg_type = data.get("type", "")
             
-            # Log all message types for debugging
-            if msg_type not in ("response.audio.delta",):  # Skip noisy audio deltas
+            if msg_type not in ("response.audio.delta",):
                 logger.debug(f"📨 OpenAI event: {msg_type}")
             
             if msg_type in ("session.created", "session.updated"):
                 logger.info("✅ OpenAI session configured")
-                # Signal any waiting tasks that session update is complete
                 if self._session_update_event:
                     self._session_update_event.set()
-                # Notify callback
                 if self.on_session_updated:
                     self.on_session_updated()
             
             elif msg_type == "input_audio_buffer.speech_started":
-                # User started speaking - but ignore if AI is responding
-                # This prevents VAD from interrupting responses due to echo/noise
                 if self.is_responding:
                     logger.warning(
-                        "🎤 VAD speech detected during AI response - ignoring "
+                        f"🎤 VAD speech detected during AI response - ignoring "
                         f"(response_state={self._response_state.value})"
                     )
-                    # Don't change speaking state - let the response complete
                 else:
                     logger.info("🎤 Speech detected - user is speaking")
                     self._set_speaking_state(SpeakingState.IDLE)
             
             elif msg_type == "input_audio_buffer.speech_stopped":
-                # User stopped speaking
                 logger.info("🎤 Speech ended - processing...")
             
             elif msg_type == "conversation.item.input_audio_transcription.completed":
-                # User's speech was transcribed
                 transcript = data.get("transcript", "")
                 logger.info(f"📝 User transcript: {transcript}")
                 if transcript:
                     self._current_transcript = transcript
                     if self.on_transcript_update:
                         self.on_transcript_update(transcript)
-                    # Append to active meeting transcript
                     self._append_to_meeting_transcript(transcript, speaker="user")
             
             elif msg_type == "response.audio_transcript.delta":
-                # AI response text delta
                 delta = data.get("delta", "")
                 if delta:
                     self._response_text_buffer += delta
             
             elif msg_type == "response.audio_transcript.done":
-                # AI response text complete
                 transcript = data.get("transcript", "")
                 if transcript:
                     self._response_text_buffer = ""
                     if self.on_response_text:
                         self.on_response_text(transcript)
-                    # Append to active meeting transcript
                     self._append_to_meeting_transcript(transcript, speaker="assistant")
             
             elif msg_type == "response.audio.delta":
-                # AI audio response chunk
                 audio_base64 = data.get("delta", "")
                 if audio_base64:
-                    # Set speaking state on first audio chunk
                     if self._speaking_state != SpeakingState.SPEAKING:
                         self._set_speaking_state(SpeakingState.SPEAKING)
                     
-                    # Transition from WAITING to GENERATING on first audio
                     if self._response_state == ResponseState.WAITING:
                         self._set_response_state(ResponseState.GENERATING)
                     
-                    # Decode and forward audio
                     audio_data = base64.b64decode(audio_base64)
-                    self._response_audio_chunks += 1
-                    self._response_audio_bytes += len(audio_data)
                     if self.on_audio_delta:
                         self.on_audio_delta(audio_data)
             
             elif msg_type == "response.audio.done":
-                # AI audio response complete - set to COMPLETE (waiting for buffer drain)
                 self._set_speaking_state(SpeakingState.IDLE)
                 self._set_response_state(ResponseState.COMPLETE)
-                logger.info(
-                    "🔊 OpenAI audio done "
-                    f"({self._response_audio_chunks} chunks, {self._response_audio_bytes} bytes)"
-                )
             
             elif msg_type == "response.done":
-                # Full response complete
                 self._set_speaking_state(SpeakingState.IDLE)
-                # Only set COMPLETE if we were generating (avoid duplicate transitions)
                 if self._response_state == ResponseState.GENERATING:
                     self._set_response_state(ResponseState.COMPLETE)
                 if self._response_text_buffer:
                     if self.on_response_text:
                         self.on_response_text(self._response_text_buffer)
                     self._response_text_buffer = ""
-                logger.info(
-                    "✅ OpenAI response done "
-                    f"({self._response_audio_chunks} chunks, {self._response_audio_bytes} bytes)"
-                )
             
             elif msg_type == "error":
                 error_data = data.get("error", {})
@@ -820,9 +483,8 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
             elif msg_type == "input_audio_buffer.cleared":
                 logger.info("🗑️ Audio buffer cleared")
             
-            # Tool/Function call events
+            # Tool call events
             elif msg_type == "response.output_item.added":
-                # A new output item was added - could be a function call
                 item = data.get("item", {})
                 if item.get("type") == "function_call":
                     call_id = item.get("call_id", "")
@@ -832,19 +494,16 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
                         "name": func_name,
                         "arguments_buffer": ""
                     }
-                    # Notify iOS that a tool is being used
                     if self.on_tool_usage:
                         self.on_tool_usage(func_name, "started")
             
             elif msg_type == "response.function_call_arguments.delta":
-                # Incremental function arguments
                 call_id = data.get("call_id", "")
                 delta = data.get("delta", "")
                 if call_id in self._pending_tool_calls:
                     self._pending_tool_calls[call_id]["arguments_buffer"] += delta
             
             elif msg_type == "response.function_call_arguments.done":
-                # Function call arguments complete
                 call_id = data.get("call_id", "")
                 arguments_str = data.get("arguments", "")
                 
@@ -852,7 +511,6 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
                     tool_info = self._pending_tool_calls[call_id]
                     tool_name = tool_info["name"]
                     
-                    # Use the complete arguments from the event
                     logger.info(f"🔧 Function call complete: {tool_name}")
                     logger.debug(f"🔧 Arguments: {arguments_str}")
                     
@@ -862,7 +520,6 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
                     )
             
             elif msg_type == "response.output_item.done":
-                # Output item complete - cleanup pending tool call if it was a function
                 item = data.get("item", {})
                 if item.get("type") == "function_call":
                     call_id = item.get("call_id", "")
@@ -875,133 +532,24 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         except json.JSONDecodeError:
             logger.error(f"Failed to parse message: {message[:100]}")
     
-    # MARK: - Tool Execution
-    
     async def _execute_tool_call(self, call_id: str, tool_name: str, arguments_str: str) -> None:
-        """Execute a tool call and send the result back to OpenAI.
-        
-        Routes to either the app tools handler (for app management tools) or
-        the tool registry (for dynamic tools like weather, web_search).
-        
-        Includes rate limiting to prevent infinite tool call loops.
-        
-        Args:
-            call_id: The unique ID for this tool call.
-            tool_name: Name of the tool to execute.
-            arguments_str: JSON string of tool arguments.
-        """
-        # Rate limiting to prevent infinite tool call loops
-        current_time = time.time()
-        if current_time - self._tool_call_reset_time > self._TOOL_CALL_WINDOW_SECONDS:
-            # Reset the counter after the window expires
-            self._tool_call_count = 0
-            self._tool_call_reset_time = current_time
-        
-        self._tool_call_count += 1
-        
-        if self._tool_call_count > self._MAX_TOOL_CALLS_PER_WINDOW:
-            logger.warning(
-                f"⚠️ Tool call rate limit exceeded ({self._tool_call_count} calls in "
-                f"{self._TOOL_CALL_WINDOW_SECONDS}s). Possible infinite loop detected."
+        """Execute a tool call using the tool executor."""
+        if self._tool_executor is None:
+            self._tool_executor = ToolExecutor(
+                send_message_fn=self._send_message,
+                on_tool_usage=self.on_tool_usage,
+                on_website_ready=self.on_website_ready,
             )
-            # Send an error back to OpenAI to break the loop
-            error_result = {
-                "type": "conversation.item.create",
-                "item": {
-                    "type": "function_call_output",
-                    "call_id": call_id,
-                    "output": json.dumps({
-                        "success": False,
-                        "error": "Rate limit exceeded. Please wait before making more requests."
-                    })
-                }
-            }
-            await self._send_message(error_result)
-            # Don't trigger another response - this breaks the loop
-            return
         
-        try:
-            # Parse arguments
-            try:
-                arguments = json.loads(arguments_str) if arguments_str else {}
-            except json.JSONDecodeError:
-                arguments = {}
-                logger.warning(f"Failed to parse tool arguments: {arguments_str}")
-            
-            # Check if this is a dynamic tool from the registry
-            registry = _get_tool_registry()
-            dynamic_tool = registry.get(tool_name)
-            
-            if dynamic_tool:
-                # Execute dynamic tool (weather, web_search, etc.)
-                logger.info(f"🔧 Executing dynamic tool: {tool_name}")
-                result = await registry.execute(tool_name, arguments)
-            else:
-                # Execute base app tool (create_custom_app, activate_custom_app, etc.)
-                tools_handler = _get_tools_handler()
-                result = await tools_handler.execute_tool(tool_name, arguments)
-            
-            logger.info(f"🔧 Tool result: {result}")
-            
-            # Check if this is a website generation result
-            if tool_name == "generate_website" and result.get("success"):
-                if self.on_website_ready:
-                    self.on_website_ready({
-                        "website_id": result.get("website_id"),
-                        "url": result.get("url"),
-                        "title": result.get("title"),
-                        "is_edit": result.get("is_edit", False),
-                    })
-            
-            # Send result back to OpenAI
-            result_message = {
-                "type": "conversation.item.create",
-                "item": {
-                    "type": "function_call_output",
-                    "call_id": call_id,
-                    "output": json.dumps(result)
-                }
-            }
-            await self._send_message(result_message)
-            
-            # Trigger OpenAI to generate a response based on the tool result
-            await self._send_message({"type": "response.create"})
-            
-            # Notify iOS that tool usage is complete
-            if self.on_tool_usage:
-                self.on_tool_usage(tool_name, "completed")
-            
-        except Exception as e:
-            logger.error(f"Error executing tool {tool_name}: {e}", exc_info=True)
-            
-            # Send error result
-            error_result = {
-                "type": "conversation.item.create",
-                "item": {
-                    "type": "function_call_output",
-                    "call_id": call_id,
-                    "output": json.dumps({"success": False, "error": str(e)})
-                }
-            }
-            await self._send_message(error_result)
-            await self._send_message({"type": "response.create"})
-            
-            # Notify iOS that tool usage is complete (even on error)
-            if self.on_tool_usage:
-                self.on_tool_usage(tool_name, "completed")
+        await self._tool_executor.execute(call_id, tool_name, arguments_str)
     
     # MARK: - Audio Input
     
     async def send_audio(self, audio_data: bytes) -> None:
-        """Send audio data to OpenAI.
-        
-        Args:
-            audio_data: PCM16 audio data at 24kHz mono.
-        """
+        """Send audio data to OpenAI."""
         if not self.is_connected:
             return
         
-        # Encode audio as base64
         audio_base64 = base64.b64encode(audio_data).decode("utf-8")
         
         message = {
@@ -1012,22 +560,12 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         await self._send_message(message)
     
     async def commit_audio_and_respond(self) -> None:
-        """Commit the audio buffer and request a response.
-        
-        Sets response state to WAITING before committing to ensure microphone
-        is paused before the AI starts responding.
-        """
+        """Commit the audio buffer and request a response."""
         if not self.is_connected:
             return
         
-        # Set response state to WAITING before committing
-        # This triggers microphone pause BEFORE the request is sent
         self._set_response_state(ResponseState.WAITING)
-        
-        # Commit audio buffer
         await self._send_message({"type": "input_audio_buffer.commit"})
-        
-        # Create response
         await self._send_message({"type": "response.create"})
     
     async def clear_audio_buffer(self) -> None:
@@ -1047,22 +585,12 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
     # MARK: - Text Input
     
     async def send_text_message(self, text: str) -> None:
-        """Send a text message (non-voice interaction).
-        
-        Sets response state to WAITING before sending to ensure microphone
-        is paused before the AI starts responding.
-        
-        Args:
-            text: The text message to send.
-        """
+        """Send a text message (non-voice interaction)."""
         if not self.is_connected:
             raise RuntimeError("Not connected to OpenAI")
         
-        # Set response state to WAITING before sending
-        # This triggers microphone pause BEFORE the request is sent
         self._set_response_state(ResponseState.WAITING)
         
-        # Create conversation item
         item_message = {
             "type": "conversation.item.create",
             "item": {
@@ -1077,10 +605,36 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
             },
         }
         await self._send_message(item_message)
-        
-        # Trigger response
         await self._send_message({"type": "response.create"})
     
+    async def restore_conversation_context(self, messages: list[dict]) -> None:
+        """Restore conversation context from history.
+        
+        Injects previous messages into the session to maintain context
+        after a session reset (e.g., voice/language change).
+        
+        Args:
+            messages: List of message dicts formatted for conversation.item.create.
+        """
+        if not self.is_connected:
+            logger.warning("Cannot restore context: not connected")
+            return
+        
+        if not messages:
+            logger.info("📚 No conversation history to restore")
+            return
+        
+        logger.info(f"📚 Restoring {len(messages)} messages from history")
+        
+        for msg in messages:
+            item_message = {
+                "type": "conversation.item.create",
+                "item": msg,
+            }
+            await self._send_message(item_message)
+        
+        logger.info("📚 Conversation context restored")
+    
     # MARK: - Listening Control
     
     def start_listening(self) -> None:
@@ -1095,63 +649,36 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
         logger.info("Stopped listening")
     
     def mark_response_complete(self) -> None:
-        """Mark the response cycle as complete (audio buffer drained).
-        
-        Called by conversation handler after audio has finished playing
-        and microphone can be safely resumed.
-        """
+        """Mark the response cycle as complete (audio buffer drained)."""
         if self._response_state != ResponseState.IDLE:
             self._set_response_state(ResponseState.IDLE)
     
+    # MARK: - Voice/Language Control
+    
     def set_voice(self, voice_id: str) -> None:
-        """Set the OpenAI voice and update the session.
-        
-        This updates both the backend voice settings and reconfigures
-        the active OpenAI session to use the new voice.
-        
-        Args:
-            voice_id: OpenAI voice ID (e.g., "alloy", "coral", "sage").
-        """
-        from .routes.voice import set_current_voice
+        """Set the OpenAI voice and update the session."""
+        from ..routes.voice import set_current_voice
         
-        # Update the backend voice settings
         if set_current_voice(voice_id):
             logger.info(f"🔊 Voice set to: {voice_id}")
-            
-            # Reconfigure the OpenAI session if connected
             if self.is_connected:
                 asyncio.create_task(self._configure_session())
         else:
             logger.warning(f"⚠️ Invalid voice ID: {voice_id}")
     
     async def set_voice_async(self, voice_id: str, timeout: float = 5.0) -> bool:
-        """Set the OpenAI voice and wait for session update confirmation.
+        """Set the OpenAI voice and wait for session update confirmation."""
+        from ..routes.voice import set_current_voice
         
-        This is the async version that waits for OpenAI to confirm the session update.
-        If the AI is currently speaking, it will cancel the current response first
-        since the new voice only applies to future responses.
-        
-        Args:
-            voice_id: OpenAI voice ID (e.g., "alloy", "coral", "sage").
-            timeout: Maximum time to wait for confirmation in seconds.
-            
-        Returns:
-            True if voice was set and session updated successfully.
-        """
-        from .routes.voice import set_current_voice
-        
-        # Update the backend voice settings
         if not set_current_voice(voice_id):
             logger.warning(f"⚠️ Invalid voice ID: {voice_id}")
             return False
         
         logger.info(f"🔊 Setting voice to: {voice_id}")
         
-        # If not connected, just return success (settings are persisted)
         if not self.is_connected:
             return True
         
-        # Cancel current response if speaking (new voice won't apply to current response)
         if self._speaking_state == SpeakingState.SPEAKING:
             logger.info("🛑 Cancelling current response for voice change")
             await self.cancel_response()
@@ -1161,54 +688,33 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
             except asyncio.TimeoutError:
                 logger.warning("⚠️ Timeout waiting for speaking to stop before voice change")
         
-        # Create event to wait for session update
         self._session_update_event = asyncio.Event()
         
         try:
-            # Reconfigure the session
             await self._configure_session()
-            
-            # Wait for OpenAI to confirm session update
             await asyncio.wait_for(self._session_update_event.wait(), timeout=timeout)
             logger.info(f"✅ Voice change confirmed: {voice_id}")
             return True
-            
         except asyncio.TimeoutError:
-            logger.warning(f"⚠️ Timeout waiting for voice change confirmation")
+            logger.warning("⚠️ Timeout waiting for voice change confirmation")
             return False
         finally:
             self._session_update_event = None
     
     async def set_language_async(self, language: str, timeout: float = 5.0) -> bool:
-        """Set the language and wait for session update confirmation.
-        
-        If the AI is currently speaking, it will cancel the current response first
-        since the new language only applies to future responses.
-        
-        Args:
-            language: Language code (e.g., "en", "nl", "de").
-            timeout: Maximum time to wait for confirmation in seconds.
-            
-        Returns:
-            True if language was set and session updated successfully.
-        """
-        from .routes.voice import set_preferred_language
+        """Set the language and wait for session update confirmation."""
+        from ..routes.voice import set_preferred_language
         
-        # Update the backend language settings
         if not set_preferred_language(language):
             logger.warning(f"⚠️ Invalid language: {language}")
             return False
         
         logger.info(f"🌍 Setting language to: {language}")
-        
-        # Update internal language
         self._language = language
         
-        # If not connected, just return success (settings are persisted)
         if not self.is_connected:
             return True
         
-        # Cancel current response if speaking (new language won't apply to current response)
         if self._speaking_state == SpeakingState.SPEAKING:
             logger.info("🛑 Cancelling current response for language change")
             await self.cancel_response()
@@ -1218,37 +724,27 @@ Before using ANY tool, you MUST tell the user what you're about to do. This help
             except asyncio.TimeoutError:
                 logger.warning("⚠️ Timeout waiting for speaking to stop before language change")
         
-        # Create event to wait for session update
         self._session_update_event = asyncio.Event()
         
         try:
-            # Reconfigure the session
             await self._configure_session()
-            
-            # Wait for OpenAI to confirm session update
             await asyncio.wait_for(self._session_update_event.wait(), timeout=timeout)
             logger.info(f"✅ Language change confirmed: {language}")
             return True
-            
         except asyncio.TimeoutError:
-            logger.warning(f"⚠️ Timeout waiting for language change confirmation")
+            logger.warning("⚠️ Timeout waiting for language change confirmation")
             return False
         finally:
             self._session_update_event = None
     
     def set_language_from_voice(self, voice_id: str) -> None:
-        """Set language based on a voice ID.
-        
-        Args:
-            voice_id: Voice ID pattern like "nl_BE-nathalie-medium".
-        """
-        # Extract language code from voice ID pattern: "xx_YY-name-quality"
+        """Set language based on a voice ID."""
         if "_" in voice_id:
             lang_code = voice_id[:2].lower()
         else:
             lang_code = "en"
         
-        if lang_code in self._language_names:
+        if lang_code in LANGUAGE_NAMES:
             self.language = lang_code
         else:
             self.language = "en"

reachys_brain/openai_realtime/session.py

@@ -0,0 +1,201 @@
+"""Session configuration for OpenAI Realtime API.
+
+Handles session setup, system instructions, and tool registration.
+"""
+
+import logging
+from typing import Optional
+
+from ..routes.voice import (
+    get_current_voice,
+    get_preferred_language,
+    get_vad_threshold,
+    get_vad_silence_ms,
+    get_vad_prefix_ms,
+)
+
+logger = logging.getLogger(__name__)
+
+# Language names for system instructions
+LANGUAGE_NAMES = {
+    "en": "English",
+    "nl": "Dutch",
+    "de": "German",
+    "fr": "French",
+    "es": "Spanish",
+    "it": "Italian",
+    "pt": "Portuguese",
+    "ja": "Japanese",
+    "ko": "Korean",
+    "zh": "Chinese",
+    "ar": "Arabic",
+    "hi": "Hindi",
+    "ru": "Russian",
+    "pl": "Polish",
+    "tr": "Turkish",
+    "sv": "Swedish",
+    "da": "Danish",
+    "no": "Norwegian",
+    "fi": "Finnish",
+}
+
+# Tools that require pre-announcement (slower, user benefits from knowing)
+TOOLS_REQUIRING_ANNOUNCEMENT = {
+    "web_search", "get_weather", "recognize_object", "test_camera",
+    "generate_website", "create_custom_app", "activate_custom_app",
+}
+
+# Tools that can execute immediately (fast, no announcement needed)
+QUICK_TOOLS = {
+    "get_current_datetime", "get_user_name", "get_preferred_country",
+    "add_reminder", "get_reminders", "wake_up", "go_to_sleep",
+    "list_custom_apps", "deactivate_app",
+}
+
+
+def get_system_instructions(
+    language: str,
+    custom_system_prompt: Optional[str] = None,
+    user_name: Optional[str] = None,
+    user_country: Optional[str] = None,
+) -> str:
+    """Get system instructions with current language and user context.
+    
+    Returns custom personality prompt if set, otherwise default Reachy personality.
+    
+    Args:
+        language: Current language code.
+        custom_system_prompt: Optional custom personality prompt.
+        user_name: Known user name (pre-fetched from DB).
+        user_country: Known user country (pre-fetched from DB).
+        
+    Returns:
+        The system instructions string.
+    """
+    lang_name = LANGUAGE_NAMES.get(language, "English")
+    
+    # Build personalization context
+    personalization = _build_personalization_context(user_name, user_country)
+    
+    # Language instruction (shortened)
+    language_instruction = f"\n\nLANGUAGE: Always respond in {lang_name}."
+    
+    # Use custom prompt if set, otherwise use default
+    if custom_system_prompt:
+        return custom_system_prompt + personalization + language_instruction
+    
+    # Default Reachy personality - compressed version
+    return f"""You are Reachy, a friendly robot assistant. Be warm, concise, and conversational (1-3 sentences unless more detail is needed).
+
+{personalization}
+
+TOOL GUIDELINES:
+- For web_search, get_weather, recognize_object, generate_website: Say "Let me..." before using
+- For quick tools (datetime, reminders, power): Just use them directly
+- ALWAYS use web_search for factual questions (people, places, events, prices, news) - don't rely on training data
+- For app creation/activation: Ask for confirmation first
+- When user mentions their name/country: Use remember_user_name/remember_preferred_country to save it""" + language_instruction
+
+
+def _build_personalization_context(
+    user_name: Optional[str],
+    user_country: Optional[str],
+) -> str:
+    """Build personalization context based on known user info.
+    
+    Args:
+        user_name: Known user name or None.
+        user_country: Known user country or None.
+        
+    Returns:
+        Personalization instruction string.
+    """
+    parts = []
+    
+    if user_name and user_country:
+        parts.append(f"USER CONTEXT: You know this user as {user_name} from {user_country}. Use their name naturally in conversation.")
+    elif user_name:
+        parts.append(f"USER CONTEXT: You know this user as {user_name}. If appropriate, ask what country they're in for timezone info.")
+    elif user_country:
+        parts.append(f"USER CONTEXT: User is from {user_country}. If appropriate, ask for their name to personalize the conversation.")
+    else:
+        parts.append("USER CONTEXT: New user - if natural, ask for their name early in the conversation.")
+    
+    return "\n".join(parts)
+
+
+def build_session_config(
+    language: str,
+    custom_system_prompt: Optional[str],
+    tools: list[dict],
+    user_name: Optional[str] = None,
+    user_country: Optional[str] = None,
+) -> dict:
+    """Build the session configuration for OpenAI.
+    
+    Args:
+        language: Current language code.
+        custom_system_prompt: Optional custom personality prompt.
+        tools: List of tool definitions to register.
+        user_name: Known user name for personalization.
+        user_country: Known user country for personalization.
+        
+    Returns:
+        Session configuration dictionary.
+    """
+    voice = get_current_voice()
+    vad_threshold = get_vad_threshold()
+    vad_silence_ms = get_vad_silence_ms()
+    vad_prefix_ms = get_vad_prefix_ms()
+    
+    logger.info(
+        f"🔊 Building session config: voice={voice}, language={language}, "
+        f"VAD: threshold={vad_threshold}, silence={vad_silence_ms}ms, "
+        f"user={user_name or 'unknown'}, country={user_country or 'unknown'}"
+    )
+    
+    return {
+        "type": "session.update",
+        "session": {
+            "modalities": ["text", "audio"],
+            "instructions": get_system_instructions(
+                language, 
+                custom_system_prompt,
+                user_name=user_name,
+                user_country=user_country,
+            ),
+            "voice": voice,
+            "input_audio_format": "pcm16",
+            "output_audio_format": "pcm16",
+            "input_audio_transcription": {
+                "model": "whisper-1",
+                "language": language,
+            },
+            "turn_detection": {
+                "type": "server_vad",
+                "threshold": vad_threshold,
+                "prefix_padding_ms": vad_prefix_ms,
+                "silence_duration_ms": vad_silence_ms,
+            },
+            "tools": tools,
+            "tool_choice": "auto",
+        },
+    }
+
+
+async def fetch_user_personalization() -> tuple[Optional[str], Optional[str]]:
+    """Fetch user name and country from database for personalization.
+    
+    Returns:
+        Tuple of (user_name, user_country), either may be None.
+    """
+    try:
+        from ..database import get_database
+        db = get_database()
+        user_name = await db.get_user_setting("user_name")
+        user_country = await db.get_user_setting("preferred_country")
+        return user_name, user_country
+    except Exception as e:
+        logger.warning(f"Could not fetch user personalization: {e}")
+        return None, None
+

reachys_brain/openai_realtime/tool_executor.py

@@ -0,0 +1,158 @@
+"""Tool execution for OpenAI Realtime API.
+
+Handles executing tool calls and sending results back to OpenAI.
+Includes rate limiting to prevent infinite tool call loops.
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import Callable, Optional
+
+from .tools_loader import get_tools_handler, get_tool_registry
+
+logger = logging.getLogger(__name__)
+
+# Rate limiting constants
+MAX_TOOL_CALLS_PER_WINDOW = 10  # Max tool calls in 10 seconds
+TOOL_CALL_WINDOW_SECONDS = 10.0
+
+
+class ToolExecutor:
+    """Handles tool execution with rate limiting."""
+    
+    def __init__(
+        self,
+        send_message_fn: Callable,
+        on_tool_usage: Optional[Callable[[str, str], None]] = None,
+        on_website_ready: Optional[Callable[[dict], None]] = None,
+    ):
+        """Initialize the tool executor.
+        
+        Args:
+            send_message_fn: Async function to send messages to OpenAI.
+            on_tool_usage: Callback for tool usage notifications.
+            on_website_ready: Callback for website generation results.
+        """
+        self._send_message = send_message_fn
+        self.on_tool_usage = on_tool_usage
+        self.on_website_ready = on_website_ready
+        
+        # Rate limiting state
+        self._tool_call_count = 0
+        self._tool_call_reset_time = 0.0
+    
+    async def execute(self, call_id: str, tool_name: str, arguments_str: str) -> None:
+        """Execute a tool call and send the result back to OpenAI.
+        
+        Routes to either the app tools handler (for app management tools) or
+        the tool registry (for dynamic tools like weather, web_search).
+        
+        Includes rate limiting to prevent infinite tool call loops.
+        
+        Args:
+            call_id: The unique ID for this tool call.
+            tool_name: Name of the tool to execute.
+            arguments_str: JSON string of tool arguments.
+        """
+        # Rate limiting check
+        current_time = time.time()
+        if current_time - self._tool_call_reset_time > TOOL_CALL_WINDOW_SECONDS:
+            # Reset the counter after the window expires
+            self._tool_call_count = 0
+            self._tool_call_reset_time = current_time
+        
+        self._tool_call_count += 1
+        
+        if self._tool_call_count > MAX_TOOL_CALLS_PER_WINDOW:
+            logger.warning(
+                f"⚠️ Tool call rate limit exceeded ({self._tool_call_count} calls in "
+                f"{TOOL_CALL_WINDOW_SECONDS}s). Possible infinite loop detected."
+            )
+            # Send an error back to OpenAI to break the loop
+            error_result = {
+                "type": "conversation.item.create",
+                "item": {
+                    "type": "function_call_output",
+                    "call_id": call_id,
+                    "output": json.dumps({
+                        "success": False,
+                        "error": "Rate limit exceeded. Please wait before making more requests."
+                    })
+                }
+            }
+            await self._send_message(error_result)
+            # Don't trigger another response - this breaks the loop
+            return
+        
+        try:
+            # Parse arguments
+            try:
+                arguments = json.loads(arguments_str) if arguments_str else {}
+            except json.JSONDecodeError:
+                arguments = {}
+                logger.warning(f"Failed to parse tool arguments: {arguments_str}")
+            
+            # Check if this is a dynamic tool from the registry
+            registry = get_tool_registry()
+            dynamic_tool = registry.get(tool_name)
+            
+            if dynamic_tool:
+                # Execute dynamic tool (weather, web_search, etc.)
+                logger.info(f"🔧 Executing dynamic tool: {tool_name}")
+                result = await registry.execute(tool_name, arguments)
+            else:
+                # Execute base app tool (create_custom_app, activate_custom_app, etc.)
+                tools_handler = get_tools_handler()
+                result = await tools_handler.execute_tool(tool_name, arguments)
+            
+            logger.info(f"🔧 Tool result: {result}")
+            
+            # Check if this is a website generation result
+            if tool_name == "generate_website" and result.get("success"):
+                if self.on_website_ready:
+                    self.on_website_ready({
+                        "website_id": result.get("website_id"),
+                        "url": result.get("url"),
+                        "title": result.get("title"),
+                        "is_edit": result.get("is_edit", False),
+                    })
+            
+            # Send result back to OpenAI
+            result_message = {
+                "type": "conversation.item.create",
+                "item": {
+                    "type": "function_call_output",
+                    "call_id": call_id,
+                    "output": json.dumps(result)
+                }
+            }
+            await self._send_message(result_message)
+            
+            # Trigger OpenAI to generate a response based on the tool result
+            await self._send_message({"type": "response.create"})
+            
+            # Notify iOS that tool usage is complete
+            if self.on_tool_usage:
+                self.on_tool_usage(tool_name, "completed")
+            
+        except Exception as e:
+            logger.error(f"Error executing tool {tool_name}: {e}", exc_info=True)
+            
+            # Send error result
+            error_result = {
+                "type": "conversation.item.create",
+                "item": {
+                    "type": "function_call_output",
+                    "call_id": call_id,
+                    "output": json.dumps({"success": False, "error": str(e)})
+                }
+            }
+            await self._send_message(error_result)
+            await self._send_message({"type": "response.create"})
+            
+            # Notify iOS that tool usage is complete (even on error)
+            if self.on_tool_usage:
+                self.on_tool_usage(tool_name, "completed")
+

reachys_brain/openai_realtime/tools_loader.py

@@ -0,0 +1,80 @@
+"""Lazy loading of tools to avoid circular imports.
+
+Provides functions to lazily load APP_TOOLS, tools handler, and tool registry.
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Lazy-loaded modules
+_APP_TOOLS = None
+_tools_handler = None
+_tool_registry = None
+
+
+def get_app_tools() -> list[dict]:
+    """Lazy import of APP_TOOLS to avoid circular imports."""
+    global _APP_TOOLS
+    if _APP_TOOLS is None:
+        from ..app_tools import APP_TOOLS as tools
+        _APP_TOOLS = tools
+    return _APP_TOOLS
+
+
+def get_tools_handler():
+    """Lazy import of tools handler to avoid circular imports."""
+    global _tools_handler
+    if _tools_handler is None:
+        from ..app_tools import get_tools_handler
+        _tools_handler = get_tools_handler()
+    return _tools_handler
+
+
+def get_tool_registry():
+    """Lazy import of tool registry to avoid circular imports."""
+    global _tool_registry
+    if _tool_registry is None:
+        from ..tools import get_registry
+        _tool_registry = get_registry()
+    return _tool_registry
+
+
+def get_all_tools(enabled_tools: Optional[list[str]] = None) -> list[dict]:
+    """Get all tools to register with OpenAI.
+    
+    Combines base APP_TOOLS (app management, power) with enabled dynamic tools
+    (weather, web_search) based on the active app's configuration.
+    
+    Args:
+        enabled_tools: List of enabled tool IDs. None means enable all.
+        
+    Returns:
+        List of OpenAI function definitions.
+    """
+    # Always include base app tools (create, activate, deactivate, etc.)
+    base_tools = get_app_tools()
+    
+    # Get dynamic tools from registry based on enabled_tools
+    registry = get_tool_registry()
+    
+    if enabled_tools is None:
+        # Default Reachy: enable all dynamic tools
+        dynamic_tool_ids = registry.get_all_ids()
+    else:
+        # Custom app: only enable specified tools
+        dynamic_tool_ids = enabled_tools
+    
+    # Get tool definitions for enabled dynamic tools
+    dynamic_tools = registry.get_definitions(dynamic_tool_ids)
+    
+    # Combine base + dynamic tools
+    all_tools = list(base_tools) + dynamic_tools
+    
+    logger.info(
+        f"🔧 Tools: {len(base_tools)} base + {len(dynamic_tools)} dynamic = {len(all_tools)} total"
+    )
+    
+    return all_tools
+

reachys_brain/routes/conversation.py

@@ -1,1285 +0,0 @@
-"""WebSocket endpoint for real-time conversation with iOS app.
-
-This module provides the WebSocket endpoint for voice conversations,
-delegating to specialized modules for:
-- broadcast_manager: Client connection management and broadcasting
-- conversation_services: Service lifecycle management
-- audio_manager: Audio streaming and buffering
-- animation_manager: Pre-speech animations and gestures
-"""
-
-import asyncio
-import logging
-import os
-from typing import Optional
-
-from fastapi import APIRouter, WebSocket, WebSocketDisconnect
-
-from ..openai_realtime import ConnectionState, SpeakingState, ResponseState
-from ..tools.reminders import set_reminder_request_callback, handle_reminder_result
-from ..tools.contacts import set_contacts_request_callback, handle_contacts_result
-from ..tools.scheduled_messages import set_scheduled_message_callback, handle_scheduled_message_result
-from ..tools.website_generator import set_website_request_callback, save_website_from_ios
-
-from .audio_stream_manager import ConversationTimings
-from .broadcast_manager import broadcast, safe_broadcast, add_client, remove_client
-from .conversation_messages import STOP_COMMANDS
-from .conversation_services import (
-    get_services,
-    get_state,
-    init_services as init_conversation_services,
-    cleanup_services as cleanup_conversation_services,
-    wire_openai_callbacks,
-)
-from .audio_manager import (
-    handle_audio_delta,
-    delayed_resume_microphone,
-    start_audio_streaming,
-    stop_audio_streaming,
-)
-from .animation_manager import (
-    handle_pre_speech_animation,
-    send_greeting,
-    send_goodbye,
-    set_custom_animations,
-    clear_custom_animations,
-)
-from .task_tracker import create_tracked_task, cancel_all_tracked_tasks
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(tags=["Conversation"])
-
-
-async def send_greeting_and_start_streaming() -> None:
-    """Send greeting and start audio streaming after it completes.
-    
-    This ensures that:
-    1. No audio is sent to OpenAI during the welcome animation
-    2. The greeting plays completely without VAD interruption
-    3. Audio streaming only starts after greeting finishes
-    
-    Flow:
-    1. send_greeting() sends text -> ResponseState.WAITING
-    2. Audio arrives -> ResponseState.GENERATING
-    3. response.audio.done -> ResponseState.COMPLETE
-    4. We wait for COMPLETE (audio sent by OpenAI)
-    5. Wait for audio buffer to drain (audio played by speaker)
-    6. Start streaming and resume microphone
-    """
-    services = get_services()
-    
-    try:
-        # Send the greeting (this will set ResponseState.WAITING -> GENERATING -> COMPLETE)
-        await send_greeting()
-        
-        # Wait for the greeting response to be COMPLETE or IDLE
-        # COMPLETE = OpenAI finished sending audio
-        # IDLE = Response cycle fully complete
-        max_wait = 15.0  # Maximum wait for greeting
-        wait_interval = 0.2
-        waited = 0.0
-        
-        while waited < max_wait:
-            if services.openai:
-                state = services.openai.response_state
-                if state in (ResponseState.COMPLETE, ResponseState.IDLE):
-                    break
-            await asyncio.sleep(wait_interval)
-            waited += wait_interval
-        
-        if waited >= max_wait:
-            logger.warning("⚠️ Greeting response timeout - starting streaming anyway")
-        else:
-            logger.info(f"✅ Greeting response complete (waited {waited:.1f}s)")
-        
-        # Wait for audio to finish playing through speaker
-        if services.audio_player and services.audio_player.is_playing:
-            extra_wait = 0.0
-            max_extra = 8.0
-            while services.audio_player.is_playing and extra_wait < max_extra:
-                await asyncio.sleep(wait_interval)
-                extra_wait += wait_interval
-            if extra_wait > 0:
-                logger.info(f"⏳ Waited {extra_wait:.1f}s for greeting audio to finish")
-        
-        # Additional buffer drain time
-        await asyncio.sleep(ConversationTimings.MICROPHONE_RESUME_DELAY_SECONDS)
-        
-        # Now start audio streaming
-        if services.openai and services.openai.is_listening:
-            start_audio_streaming()
-            logger.info("✅ Audio streaming started after greeting")
-            
-            # Clear any buffered audio
-            await services.openai.clear_audio_buffer()
-            
-            # Mark response cycle as complete
-            services.openai.mark_response_complete()
-            
-            # Resume audio capture
-            if services.audio_capture:
-                services.audio_capture.resume_capture()
-                logger.info("▶️ Microphone resumed after greeting")
-        
-    except Exception as e:
-        logger.error(f"Error in greeting flow: {e}")
-        # Start streaming anyway to not leave the system in a broken state
-        if services.openai and services.openai.is_listening:
-            start_audio_streaming()
-            if services.audio_capture:
-                services.audio_capture.resume_capture()
-
-async def _reset_openai_session(keep_listening: bool) -> None:
-    """Hard reset OpenAI session by disconnecting and reconnecting.
-
-    OpenAI Realtime rejects changing voice via `session.update` once assistant
-    audio has been produced in the current session. To apply a new voice/language
-    reliably, we must create a new session.
-
-    If `keep_listening` is True, we restore listening + audio streaming so the
-    next user turn works without user-visible reconnect steps.
-    """
-    services = get_services()
-
-    if not services.openai:
-        return
-
-    # Stop any local playback/gestures
-    if services.audio_player:
-        services.audio_player.cancel()
-
-    if services.speaking_gestures:
-        await services.speaking_gestures.stop()
-
-    # Stop audio streaming task (depends on openai.is_connected)
-    stop_audio_streaming()
-
-    # Pause capture while we reset, to avoid buffering user audio into nowhere
-    if services.audio_capture:
-        services.audio_capture.pause_capture()
-
-    # Best-effort: cancel any in-flight response and clear input buffer
-    try:
-        await services.openai.cancel_response()
-        await services.openai.clear_audio_buffer()
-    except Exception:
-        pass
-
-    # Fully disconnect and reconnect (new session)
-    try:
-        await services.openai.disconnect()
-    except Exception:
-        pass
-
-    # connect() reads OPENAI_API_KEY from env (set by iOS connect command)
-    await services.openai.connect()
-
-    if keep_listening:
-        services.openai.start_listening()
-        start_audio_streaming()
-
-        # Resume capture with normal echo-avoidance delay
-        create_tracked_task(delayed_resume_microphone())
-    else:
-        if services.audio_capture:
-            services.audio_capture.stop_capture()
-
-
-# MARK: - Service Lifecycle
-
-def init_services() -> None:
-    """Initialize conversation services and wire up callbacks."""
-    services = init_conversation_services()
-    
-    # Wire up OpenAI callbacks
-    wire_openai_callbacks(
-        on_connection_state=_on_connection_state,
-        on_speaking_state=_on_speaking_state,
-        on_response_state=_on_response_state,
-        on_transcript_update=_on_transcript_update,
-        on_response_text=_on_response_text,
-        on_audio_delta=handle_audio_delta,
-        on_error=_on_error,
-        on_app_change=_on_app_change,
-        on_tool_usage=_on_tool_usage,
-        on_website_ready=_on_website_ready,
-    )
-    
-    # Wire up meeting callbacks
-    if services.openai:
-        services.openai.on_meeting_started = _on_meeting_started
-        services.openai.on_meeting_stopped = _on_meeting_stopped
-        services.openai.on_meeting_transcript_update = _on_meeting_transcript_update
-    
-    # Wire up website request callback to delegate generation to iOS
-    set_website_request_callback(_on_website_request)
-    
-    # Wire up reminder request callback to delegate operations to iOS
-    set_reminder_request_callback(_on_reminder_request)
-    
-    # Wire up contacts request callback to delegate operations to iOS
-    set_contacts_request_callback(_on_contacts_request)
-    
-    # Wire up scheduled message request callback to delegate operations to iOS
-    set_scheduled_message_callback(_on_scheduled_message_request)
-    
-    logger.info("Conversation services initialized")
-
-
-async def cleanup_services() -> None:
-    """Clean up conversation services.
-    
-    This is async to properly await all cleanup operations and prevent
-    the app from hanging during shutdown.
-    """
-    # Cancel all tracked tasks first
-    cancel_all_tracked_tasks()
-    # Await the async cleanup
-    await cleanup_conversation_services()
-
-
-# MARK: - OpenAI Callbacks
-
-def _on_connection_state(state: ConnectionState) -> None:
-    """Handle OpenAI connection state changes."""
-    create_tracked_task(broadcast({
-        "type": "connection_state",
-        "state": state.value,
-    }))
-
-
-def _on_speaking_state(state: SpeakingState) -> None:
-    """Handle OpenAI speaking state changes."""
-    services = get_services()
-    conv_state = get_state()
-    
-    # Pause/resume audio capture based on speaking state
-    if services.audio_capture:
-        if state == SpeakingState.SPEAKING:
-            services.audio_capture.pause_capture()
-            logger.info("⏸️ Paused microphone (AI speaking)")
-            
-            # Reset buffering state for new response
-            conv_state.reset_for_new_response()
-            
-            # Start subtle speaking gestures while talking
-            if services.speaking_gestures:
-                create_tracked_task(services.speaking_gestures.start())
-            
-            # Clear OpenAI's audio buffer to prevent echo from interrupting
-            if services.openai:
-                create_tracked_task(services.openai.clear_audio_buffer())
-                logger.info("🗑️ Cleared OpenAI audio buffer (preventing echo)")
-        else:
-            # AI finished speaking - stop gestures
-            if services.speaking_gestures:
-                create_tracked_task(services.speaking_gestures.stop())
-            
-            conv_state.response_count += 1
-            
-            # Reset buffering state for next response
-            conv_state.is_buffering_audio = True
-            conv_state.animation_played_for_response = False
-            
-            # Delay resuming microphone to let audio buffer drain (prevent echo)
-            create_tracked_task(delayed_resume_microphone())
-    
-    create_tracked_task(broadcast({
-        "type": "speaking_state",
-        "state": state.value,
-    }))
-
-
-def _on_response_state(state: ResponseState) -> None:
-    """Handle OpenAI response lifecycle state changes.
-    
-    This is the key callback for preventing audio cutoff:
-    - WAITING: Request sent, pause microphone immediately
-    - GENERATING: Audio being received, mic stays paused
-    - COMPLETE: Audio done, wait for buffer drain then resume
-    - IDLE: Buffer drained, mic can be active
-    """
-    services = get_services()
-    conv_state = get_state()
-    
-    if state == ResponseState.WAITING:
-        # Immediately pause microphone when a request is sent
-        # This prevents VAD from detecting noise/echo before response starts
-        if services.audio_capture:
-            services.audio_capture.pause_capture()
-            logger.info("⏸️ Paused microphone (waiting for AI response)")
-        
-        # Clear OpenAI's audio buffer to prevent any buffered audio
-        if services.openai:
-            create_tracked_task(services.openai.clear_audio_buffer())
-    
-    elif state == ResponseState.GENERATING:
-        # Audio is being generated - ensure mic stays paused
-        if services.audio_capture and not services.audio_capture.is_paused:
-            services.audio_capture.pause_capture()
-            logger.info("⏸️ Paused microphone (AI generating audio)")
-    
-    elif state == ResponseState.COMPLETE:
-        # Response complete - schedule microphone resume after buffer drains
-        # The actual resume happens via delayed_resume_microphone
-        logger.info("📊 Response complete - waiting for audio buffer to drain")
-    
-    elif state == ResponseState.IDLE:
-        # Response cycle complete - microphone can be resumed
-        # This is called after buffer has drained
-        logger.info("📊 Response cycle idle - microphone can resume")
-    
-    # Broadcast state change to iOS
-    create_tracked_task(broadcast({
-        "type": "response_state",
-        "state": state.value,
-    }))
-
-
-def _is_stop_command(transcript: str, language: str = "en") -> bool:
-    """Check if the transcript is a stop command."""
-    text = transcript.strip().lower()
-    
-    # Check stop commands for current language
-    stop_words = STOP_COMMANDS.get(language, STOP_COMMANDS["en"])
-    for stop in stop_words:
-        if text == stop or text.startswith(stop + " ") or text.endswith(" " + stop):
-            return True
-    
-    # Always check English stop commands as fallback
-    if language != "en":
-        for stop in STOP_COMMANDS["en"]:
-            if text == stop or text.startswith(stop + " ") or text.endswith(" " + stop):
-                return True
-    
-    return False
-
-
-def _on_transcript_update(transcript: str) -> None:
-    """Handle user transcript updates."""
-    services = get_services()
-    
-    # Check for stop command
-    lang = services.openai.language if services.openai else "en"
-    if _is_stop_command(transcript, lang):
-        logger.info(f"🛑 Stop command detected: '{transcript}'")
-        create_tracked_task(_handle_stop_command())
-        return
-    
-    create_tracked_task(broadcast({
-        "type": "transcript_update",
-        "transcript": transcript,
-    }))
-
-
-async def _handle_stop_command() -> None:
-    """Handle a voice stop command - immediately end the conversation."""
-    services = get_services()
-    state = get_state()
-    
-    try:
-        # Cancel any current AI response
-        if services.audio_player:
-            services.audio_player.cancel()
-        
-        if services.openai:
-            await services.openai.cancel_response()
-        
-        # Stop speaking gestures if running
-        if services.speaking_gestures:
-            await services.speaking_gestures.stop()
-        
-        # Stop the audio stream task
-        stop_audio_streaming()
-        
-        # Stop audio capture
-        if services.audio_capture:
-            services.audio_capture.stop_capture()
-        
-        # Stop listening on OpenAI
-        if services.openai:
-            services.openai.stop_listening()
-
-            # Enforce: next conversation is always a new OpenAI session
-            try:
-                await services.openai.disconnect()
-            except Exception:
-                pass
-        
-        # Mark conversation as ended (allows idle movements to resume)
-        state.end_conversation()
-        
-        # Broadcast to iOS that listening has stopped
-        await broadcast({
-            "type": "listening_state",
-            "listening": False,
-        })
-        
-        # Also notify of the transcript that caused the stop
-        await broadcast({
-            "type": "conversation_stopped",
-            "reason": "voice_command",
-        })
-        
-        logger.info("✅ Conversation stopped via voice command")
-        
-    except Exception as e:
-        logger.error(f"Error handling stop command: {e}")
-        # Broadcast error to clients
-        await broadcast({
-            "type": "error",
-            "message": "Failed to stop conversation",
-        })
-
-
-def _on_response_text(text: str) -> None:
-    """Handle AI response text - triggers pre-speech animation."""
-    state = get_state()
-    state.last_response_text = text
-    
-    # Trigger pre-speech animation workflow
-    create_tracked_task(handle_pre_speech_animation(text))
-    
-    create_tracked_task(broadcast({
-        "type": "response_text",
-        "text": text,
-    }))
-
-
-def _on_error(error: str) -> None:
-    """Handle OpenAI errors."""
-    create_tracked_task(broadcast({
-        "type": "error",
-        "message": error,
-    }))
-
-
-def _on_tool_usage(tool_name: str, status: str) -> None:
-    """Handle tool usage notifications."""
-    logger.info(f"🔧 Tool usage: {tool_name} ({status})")
-    create_tracked_task(broadcast({
-        "type": "tool_usage",
-        "tool": tool_name if status == "started" else None,
-        "status": status,
-    }))
-
-
-def _on_website_ready(data: dict) -> None:
-    """Handle website generation completion."""
-    try:
-        website_id = data.get("website_id", "")
-        url = data.get("url", "")
-        title = data.get("title", "Generated Website")
-        is_edit = data.get("is_edit", False)
-        
-        if not website_id:
-            logger.error("_on_website_ready: Missing website_id")
-            return
-        
-        action = "updated" if is_edit else "created"
-        logger.info(f"🌐 Website {action}: {title} ({website_id})")
-        
-        create_tracked_task(safe_broadcast({
-            "type": "website_ready",
-            "website_id": website_id,
-            "url": url,
-            "title": title,
-            "is_edit": is_edit,
-        }))
-    except Exception as e:
-        logger.error(f"Error in _on_website_ready: {e}", exc_info=True)
-
-
-def _on_website_request(
-    website_id: str,
-    description: str,
-    is_edit: bool,
-    existing_html: Optional[str],
-) -> None:
-    """Handle website generation request - delegates to iOS."""
-    try:
-        if not website_id:
-            logger.error("_on_website_request: Missing website_id")
-            return
-        
-        if not description:
-            logger.error("_on_website_request: Missing description")
-            return
-        
-        action = "Editing" if is_edit else "Creating"
-        desc_preview = description[:50] if description else ""
-        logger.info(f"📱 Requesting iOS to generate website {website_id}: {desc_preview}...")
-        
-        # Limit existing_html size for broadcast to prevent WebSocket issues
-        broadcast_existing_html = existing_html
-        if existing_html and len(existing_html) > 100000:
-            logger.warning(f"Truncating existing_html for broadcast ({len(existing_html)} chars)")
-            broadcast_existing_html = existing_html[:100000]
-        
-        create_tracked_task(safe_broadcast({
-            "type": "website_request",
-            "website_id": website_id,
-            "description": description,
-            "is_edit": is_edit,
-            "existing_html": broadcast_existing_html,
-        }))
-    except Exception as e:
-        logger.error(f"Error in _on_website_request: {e}", exc_info=True)
-
-
-def _on_reminder_request(
-    request_id: str,
-    action: str,
-    params: dict,
-) -> None:
-    """Handle reminder operation request - delegates to iOS."""
-    try:
-        if not request_id:
-            logger.error("_on_reminder_request: Missing request_id")
-            return
-        
-        logger.info(f"📱 Requesting iOS to {action} reminder: {request_id}")
-        
-        create_tracked_task(safe_broadcast({
-            "type": "reminder_request",
-            "request_id": request_id,
-            "action": action,
-            "params": params,
-        }))
-    except Exception as e:
-        logger.error(f"Error in _on_reminder_request: {e}", exc_info=True)
-
-
-def _on_contacts_request(
-    request_id: str,
-    action: str,
-    params: dict,
-) -> None:
-    """Handle contacts operation request - delegates to iOS."""
-    try:
-        if not request_id:
-            logger.error("_on_contacts_request: Missing request_id")
-            return
-        
-        logger.info(f"📇 Requesting iOS to {action} contacts: {request_id}")
-        
-        create_tracked_task(safe_broadcast({
-            "type": "contacts_request",
-            "request_id": request_id,
-            "action": action,
-            "params": params,
-        }))
-    except Exception as e:
-        logger.error(f"Error in _on_contacts_request: {e}", exc_info=True)
-
-
-def _on_scheduled_message_request(
-    request_id: str,
-    action: str,
-    params: dict,
-) -> None:
-    """Handle scheduled message operation request - delegates to iOS."""
-    try:
-        if not request_id:
-            logger.error("_on_scheduled_message_request: Missing request_id")
-            return
-        
-        logger.info(f"📬 Requesting iOS to {action} scheduled message: {request_id}")
-        
-        create_tracked_task(safe_broadcast({
-            "type": "scheduled_message_request",
-            "request_id": request_id,
-            "action": action,
-            "params": params,
-        }))
-    except Exception as e:
-        logger.error(f"Error in _on_scheduled_message_request: {e}", exc_info=True)
-
-
-def _on_app_change(data: dict) -> None:
-    """Handle app activation/deactivation changes from voice commands."""
-    state = get_state()
-    event_type = data.get("type", "")
-    
-    if event_type == "app_activated":
-        app = data.get("app", {})
-        logger.info(f"🚀 Voice-activated app: {app.get('name', 'Unknown')}")
-        
-        # Update emotion animations if the app has custom ones
-        emotion_animations = app.get("emotion_animations", {})
-        if emotion_animations:
-            set_custom_animations(emotion_animations)
-        
-        create_tracked_task(broadcast({
-            "type": "app_activated",
-            "app": {
-                "id": app.get("id"),
-                "name": app.get("name"),
-                "description": app.get("description", ""),
-            }
-        }))
-    
-    elif event_type == "app_deactivated":
-        logger.info("🛑 Voice-deactivated app - reverting to default")
-        clear_custom_animations()
-        
-        create_tracked_task(broadcast({
-            "type": "app_deactivated"
-        }))
-
-
-# MARK: - Meeting Callbacks
-
-def _on_meeting_started(meeting_id: str, title: str) -> None:
-    """Handle meeting recording started."""
-    logger.info(f"📝 Meeting started: {title} ({meeting_id})")
-    create_tracked_task(safe_broadcast({
-        "type": "meeting_started",
-        "meeting_id": meeting_id,
-        "title": title,
-    }))
-
-
-def _on_meeting_stopped(meeting_id: str) -> None:
-    """Handle meeting recording stopped."""
-    logger.info(f"📝 Meeting stopped: {meeting_id}")
-    create_tracked_task(safe_broadcast({
-        "type": "meeting_stopped",
-        "meeting_id": meeting_id,
-    }))
-
-
-def _on_meeting_transcript_update(meeting_id: str, transcript: str) -> None:
-    """Handle meeting transcript update."""
-    # Only send the last portion for live updates (full transcript can be large)
-    # Get last 500 characters for preview
-    preview = transcript[-500:] if len(transcript) > 500 else transcript
-    
-    create_tracked_task(safe_broadcast({
-        "type": "meeting_transcript_update",
-        "meeting_id": meeting_id,
-        "transcript_preview": preview,
-        "total_length": len(transcript),
-    }))
-
-
-# MARK: - WebSocket Endpoint
-
-@router.websocket("/ws/conversation")
-async def conversation_websocket(websocket: WebSocket) -> None:
-    """WebSocket endpoint for iOS conversation app.
-    
-    Accepts commands from iOS and relays events from OpenAI.
-    
-    Commands:
-        - connect: Connect to OpenAI (requires api_key)
-        - disconnect: Disconnect from OpenAI
-        - start_listening: Start microphone capture
-        - stop_listening: Stop microphone capture
-        - set_language: Set conversation language
-        - set_voice: Set voice ID (also updates language)
-        - send_text: Send a text message
-        - set_system_prompt: Set custom personality (requires system_prompt)
-        - clear_system_prompt: Clear custom personality, revert to default
-        - cancel_response: Cancel current AI response
-        - clear_audio_buffer: Clear the input audio buffer
-    
-    Events (sent to iOS):
-        - connection_state: OpenAI connection state
-        - speaking_state: AI speaking state
-        - transcript_update: User transcript (real-time)
-        - response_text: AI response text
-        - personality_set: Custom personality was set
-        - personality_cleared: Reverted to default personality
-        - error: Error messages
-    """
-    await websocket.accept()
-    count = add_client(websocket)
-    logger.info(f"iOS client connected ({count} total)")
-    
-    services = get_services()
-    
-    # Send current state
-    if services.openai:
-        await websocket.send_json({
-            "type": "connection_state",
-            "state": services.openai.connection_state.value,
-        })
-    
-    try:
-        while True:
-            data = await websocket.receive_json()
-            command = data.get("command", "")
-            await _handle_command(websocket, command, data)
-    
-    except WebSocketDisconnect:
-        logger.info("iOS client disconnected")
-    except Exception as e:
-        logger.error(f"WebSocket error: {e}")
-    finally:
-        count = remove_client(websocket)
-        logger.info(f"iOS client removed ({count} remaining)")
-
-
-async def _handle_command(websocket: WebSocket, command: str, data: dict) -> None:
-    """Handle a command from the iOS app."""
-    services = get_services()
-    state = get_state()
-    
-    if not services.is_initialized:
-        init_services()
-        services = get_services()
-    
-    try:
-        if command == "connect":
-            await _handle_connect(websocket, data)
-        
-        elif command == "disconnect":
-            await _handle_disconnect()
-        
-        elif command == "start_listening":
-            await _handle_start_listening(websocket)
-        
-        elif command == "stop_listening":
-            await _handle_stop_listening(websocket)
-        
-        elif command == "set_language":
-            language = data.get("language", "en")
-            # Persist language; immediately reset OpenAI session to apply new settings.
-            from .voice import set_preferred_language
-            success = set_preferred_language(language)
-            confirmed = False
-
-            if success and services.openai and services.openai.is_connected:
-                # Immediately disconnect and reconnect with new language
-                keep_listening = bool(services.openai.is_listening)
-                await _reset_openai_session(keep_listening=keep_listening)
-                confirmed = services.openai.is_connected
-                logger.info(f"🌍 Language switched to {language}, session reset, confirmed={confirmed}")
-
-            await websocket.send_json({
-                "type": "language_set",
-                "language": language,
-                "success": success,
-                "confirmed": confirmed,
-            })
-        
-        elif command == "set_voice":
-            voice_id = data.get("voice_id", "")
-            if voice_id:
-                # Persist voice; immediately reset OpenAI session to apply new settings.
-                from .voice import set_current_voice
-                success = set_current_voice(voice_id)
-                confirmed = False
-
-                if success and services.openai and services.openai.is_connected:
-                    # Immediately disconnect and reconnect with new voice
-                    keep_listening = bool(services.openai.is_listening)
-                    await _reset_openai_session(keep_listening=keep_listening)
-                    confirmed = services.openai.is_connected
-                    logger.info(f"🔊 Voice switched to {voice_id}, session reset, confirmed={confirmed}")
-
-                await websocket.send_json({
-                    "type": "voice_set",
-                    "voice_id": voice_id,
-                    "language": services.openai.language,
-                    "success": success,
-                    "confirmed": confirmed,
-                })
-        
-        elif command == "send_text":
-            text = data.get("text", "")
-            if text:
-                await services.openai.send_text_message(text)
-        
-        elif command == "cancel_response":
-            if services.audio_player:
-                services.audio_player.cancel()
-            await services.openai.cancel_response()
-        
-        elif command == "interrupt_response":
-            await _handle_interrupt(websocket)
-        
-        elif command == "clear_audio_buffer":
-            await services.openai.clear_audio_buffer()
-        
-        elif command == "set_system_prompt":
-            await _handle_set_system_prompt(websocket, data)
-        
-        elif command == "clear_system_prompt":
-            services.openai.clear_custom_personality()
-            logger.info("🎭 Reverted to default Reachy personality")
-            await websocket.send_json({
-                "type": "personality_cleared",
-                "success": True,
-            })
-        
-        elif command == "set_emotion_animations":
-            await _handle_set_emotion_animations(websocket, data)
-        
-        elif command == "clear_emotion_animations":
-            clear_custom_animations()
-            await websocket.send_json({
-                "type": "emotion_animations_cleared",
-                "success": True,
-            })
-        
-        elif command == "upload_website":
-            await _handle_upload_website(websocket, data)
-        
-        elif command == "reminder_result":
-            await _handle_reminder_result(websocket, data)
-        
-        elif command == "contacts_result":
-            await _handle_contacts_result(websocket, data)
-        
-        elif command == "scheduled_message_result":
-            await _handle_scheduled_message_result(websocket, data)
-        
-        else:
-            logger.warning(f"Unknown command: {command}")
-            await websocket.send_json({
-                "type": "error",
-                "message": f"Unknown command: {command}",
-            })
-    
-    except Exception as e:
-        logger.error(f"Error handling command {command}: {e}")
-        await websocket.send_json({
-            "type": "error",
-            "message": str(e),
-        })
-
-
-# MARK: - Command Handlers
-
-async def _handle_connect(websocket: WebSocket, data: dict) -> None:
-    """Handle the connect command."""
-    services = get_services()
-    
-    api_key = data.get("api_key") or os.environ.get("OPENAI_API_KEY")
-    
-    if not api_key:
-        await websocket.send_json({
-            "type": "error",
-            "message": "API key required",
-        })
-        return
-    
-    if data.get("api_key"):
-        # Log masked key for debugging
-        key_preview = f"***{api_key[-4:]}" if len(api_key) > 4 else "***"
-        logger.info(f"API key provided ({key_preview})")
-        os.environ["OPENAI_API_KEY"] = data["api_key"]
-    
-    await services.openai.connect(api_key)
-    
-    if services.audio_player:
-        services.audio_player.start_stream()
-
-
-async def _handle_disconnect() -> None:
-    """Handle the disconnect command."""
-    services = get_services()
-    
-    stop_audio_streaming()
-    
-    if services.audio_capture:
-        services.audio_capture.stop_capture()
-    
-    if services.audio_player:
-        services.audio_player.cancel()
-    
-    await services.openai.disconnect()
-
-
-async def _handle_start_listening(websocket: WebSocket) -> None:
-    """Handle the start_listening command."""
-    services = get_services()
-    state = get_state()
-    
-    if not services.openai.is_connected:
-        # Auto-connect so that "stop => new session next time" doesn't require
-        # a separate iOS connect step.
-        try:
-            await services.openai.connect()
-        except Exception as e:
-            logger.error(f"Cannot start listening: not connected to OpenAI ({e})")
-            await websocket.send_json({
-                "type": "error",
-                "message": "Not connected to OpenAI",
-            })
-            return
-    
-    # Reset conversation state
-    state.reset_for_new_conversation()
-    logger.info("🎬 New conversation started - animation state reset")
-    
-    # Start audio capture
-    if services.audio_capture:
-        if not services.audio_capture.is_available:
-            logger.error("Audio capture not available - no microphone detected!")
-            await websocket.send_json({
-                "type": "error",
-                "message": "Microphone not available on Reachy",
-            })
-            return
-        
-        capture_started = await services.audio_capture.start_capture()
-        if not capture_started:
-            logger.error("❌ Failed to start audio capture")
-            await websocket.send_json({
-                "type": "error",
-                "message": "Failed to start microphone capture",
-            })
-            return
-        
-        logger.info("✅ Audio capture started successfully")
-    else:
-        logger.error("Audio capture service not initialized")
-        await websocket.send_json({
-            "type": "error",
-            "message": "Audio capture service not initialized",
-        })
-        return
-    
-    services.openai.start_listening()
-    logger.info("✅ OpenAI listening mode enabled")
-    
-    # IMPORTANT: Do NOT start audio streaming here!
-    # Audio streaming will be started AFTER the greeting completes.
-    # This prevents motor noise from the welcome animation and ambient
-    # noise from triggering VAD and interrupting the greeting.
-    
-    # Pause audio capture immediately - it will be resumed after greeting
-    if services.audio_capture:
-        services.audio_capture.pause_capture()
-        logger.info("⏸️ Audio capture paused until greeting completes")
-    
-    await websocket.send_json({
-        "type": "listening_state",
-        "listening": True,
-    })
-    
-    # Send greeting - audio streaming will start after it completes
-    create_tracked_task(send_greeting_and_start_streaming())
-
-
-async def _handle_stop_listening(websocket: WebSocket) -> None:
-    """Handle the stop_listening command."""
-    services = get_services()
-    state = get_state()
-    
-    # Stop capturing new audio input
-    stop_audio_streaming()
-    
-    if services.audio_capture:
-        services.audio_capture.stop_capture()
-    
-    services.openai.stop_listening()
-    
-    # Broadcast listening stopped immediately for UI responsiveness
-    await websocket.send_json({
-        "type": "listening_state",
-        "listening": False,
-    })
-    
-    # Send goodbye and wait for it to be spoken before disconnecting
-    # This runs in the background so we don't block the WebSocket response
-    async def goodbye_and_disconnect():
-        try:
-            # Send the goodbye prompt
-            await send_goodbye()
-            
-            # Wait for the AI to generate and speak the goodbye
-            # Give it enough time to respond and speak (typical goodbye is ~3-5 seconds)
-            max_wait = 8.0  # Maximum seconds to wait
-            wait_interval = 0.2
-            waited = 0.0
-            
-            # Wait for speech to start generating
-            await asyncio.sleep(0.5)
-            
-            # Wait for AI response to complete
-            while waited < max_wait:
-                if services.openai:
-                    response_state = services.openai.response_state
-                    if response_state in (ResponseState.WAITING, ResponseState.GENERATING):
-                        # Response is ongoing, keep waiting
-                        await asyncio.sleep(wait_interval)
-                        waited += wait_interval
-                    elif waited > 1.0:
-                        # Response has finished (or never started after initial delay)
-                        break
-                    else:
-                        # Give it a moment to start
-                        await asyncio.sleep(wait_interval)
-                        waited += wait_interval
-                else:
-                    break
-            
-            # Also wait for audio playback to finish
-            if services.audio_player and services.audio_player.is_playing:
-                extra_wait = 0.0
-                max_extra = 5.0
-                while services.audio_player.is_playing and extra_wait < max_extra:
-                    await asyncio.sleep(wait_interval)
-                    extra_wait += wait_interval
-            
-        except Exception as e:
-            logger.error(f"Error in goodbye sequence: {e}")
-        finally:
-            # Now disconnect the OpenAI session
-            try:
-                await services.openai.disconnect()
-            except Exception:
-                pass
-            
-            # Mark conversation as ended (allows idle movements to resume)
-            state.end_conversation()
-    
-    create_tracked_task(goodbye_and_disconnect())
-
-
-async def _handle_interrupt(websocket: WebSocket) -> None:
-    """Handle the interrupt_response command."""
-    services = get_services()
-    
-    logger.info("🛑 Interrupt command received from iOS!")
-    
-    # Cancel audio playback immediately
-    if services.audio_player:
-        services.audio_player.cancel()
-    
-    # Cancel the AI response
-    if services.openai:
-        await services.openai.cancel_response()
-    
-    # Stop speaking gestures
-    if services.speaking_gestures:
-        await services.speaking_gestures.stop()
-    
-    # Resume microphone capture so user can speak
-    if services.audio_capture:
-        services.audio_capture.resume_capture()
-        logger.info("▶️ Microphone resumed after interrupt")
-    
-    # Clear any buffered audio to prevent echo
-    if services.openai:
-        await services.openai.clear_audio_buffer()
-    
-    # Notify iOS that interrupt was successful
-    await websocket.send_json({
-        "type": "interrupt_complete",
-        "success": True,
-    })
-    
-    logger.info("✅ Interrupt complete - listening to user")
-
-
-async def _handle_set_system_prompt(websocket: WebSocket, data: dict) -> None:
-    """Handle the set_system_prompt command."""
-    services = get_services()
-    
-    system_prompt = data.get("system_prompt", "")
-    if system_prompt:
-        services.openai.set_custom_personality(system_prompt)
-        logger.info(f"🎭 Custom personality set ({len(system_prompt)} chars)")
-        await websocket.send_json({
-            "type": "personality_set",
-            "success": True,
-        })
-    else:
-        await websocket.send_json({
-            "type": "error",
-            "message": "No system_prompt provided",
-        })
-
-
-async def _handle_set_emotion_animations(websocket: WebSocket, data: dict) -> None:
-    """Handle the set_emotion_animations command."""
-    emotion_animations = data.get("emotion_animations", {})
-    if emotion_animations:
-        set_custom_animations(emotion_animations)
-        await websocket.send_json({
-            "type": "emotion_animations_set",
-            "success": True,
-            "emotions": list(emotion_animations.keys()),
-        })
-    else:
-        await websocket.send_json({
-            "type": "error",
-            "message": "No emotion_animations provided",
-        })
-
-
-async def _handle_upload_website(websocket: WebSocket, data: dict) -> None:
-    """Handle the upload_website command."""
-    try:
-        website_id = data.get("website_id", "")
-        html_content = data.get("html_content", "")
-        title = data.get("title", "Generated Website")
-        description = data.get("description", "")
-        
-        # Validate required fields
-        if not website_id:
-            logger.error("upload_website: Missing website_id")
-            await websocket.send_json({
-                "type": "error",
-                "message": "website_id is required",
-            })
-            return
-        
-        if not html_content:
-            logger.error("upload_website: Missing html_content")
-            await websocket.send_json({
-                "type": "error",
-                "message": "html_content is required",
-            })
-            return
-        
-        # Log upload size for debugging
-        logger.info(f"📤 Receiving website upload: {website_id} ({len(html_content)} bytes)")
-        
-        # Save the website to robot storage
-        result = await save_website_from_ios(
-            website_id=website_id,
-            html_content=html_content,
-            title=title,
-            description=description,
-        )
-        
-        if result.get("success"):
-            logger.info(f"💾 Website uploaded from iOS: {website_id}")
-            await websocket.send_json({
-                "type": "website_uploaded",
-                "website_id": website_id,
-                "url": result.get("url"),
-                "title": title,
-                "success": True,
-            })
-            
-            # Broadcast to all clients that website is ready
-            await safe_broadcast({
-                "type": "website_ready",
-                "website_id": website_id,
-                "url": result.get("url"),
-                "title": title,
-                "is_edit": data.get("is_edit", False),
-            })
-        else:
-            error_msg = result.get("error", "Failed to save website")
-            logger.error(f"upload_website failed: {error_msg}")
-            await websocket.send_json({
-                "type": "error",
-                "message": error_msg,
-            })
-    except Exception as e:
-        logger.error(f"Error handling upload_website: {e}", exc_info=True)
-        await websocket.send_json({
-            "type": "error",
-            "message": f"Upload failed: {str(e)}",
-        })
-
-
-async def _handle_reminder_result(websocket: WebSocket, data: dict) -> None:
-    """Handle the reminder_result command from iOS."""
-    try:
-        request_id = data.get("request_id", "")
-        result = data.get("result", {})
-        
-        if not request_id:
-            logger.error("reminder_result: Missing request_id")
-            await websocket.send_json({
-                "type": "error",
-                "message": "request_id is required",
-            })
-            return
-        
-        logger.info(f"📱 Received reminder result: {request_id} (success: {result.get('success', False)})")
-        
-        # Pass the result to the reminders module to resolve the pending future
-        handle_reminder_result(request_id, result)
-        
-        # Acknowledge receipt
-        await websocket.send_json({
-            "type": "reminder_result_received",
-            "request_id": request_id,
-            "success": True,
-        })
-        
-    except Exception as e:
-        logger.error(f"Error handling reminder_result: {e}", exc_info=True)
-        await websocket.send_json({
-            "type": "error",
-            "message": f"Reminder result failed: {str(e)}",
-        })
-
-
-async def _handle_contacts_result(websocket: WebSocket, data: dict) -> None:
-    """Handle the contacts_result command from iOS."""
-    try:
-        request_id = data.get("request_id", "")
-        result = data.get("result", {})
-        
-        if not request_id:
-            logger.error("contacts_result: Missing request_id")
-            await websocket.send_json({
-                "type": "error",
-                "message": "request_id is required",
-            })
-            return
-        
-        logger.info(f"📇 Received contacts result: {request_id} (success: {result.get('success', False)})")
-        
-        # Pass the result to the contacts module to resolve the pending future
-        handle_contacts_result(request_id, result)
-        
-        # Acknowledge receipt
-        await websocket.send_json({
-            "type": "contacts_result_received",
-            "request_id": request_id,
-            "success": True,
-        })
-        
-    except Exception as e:
-        logger.error(f"Error handling contacts_result: {e}", exc_info=True)
-        await websocket.send_json({
-            "type": "error",
-            "message": f"Contacts result failed: {str(e)}",
-        })
-
-
-async def _handle_scheduled_message_result(websocket: WebSocket, data: dict) -> None:
-    """Handle the scheduled_message_result command from iOS."""
-    try:
-        request_id = data.get("request_id", "")
-        result = data.get("result", {})
-        
-        if not request_id:
-            logger.error("scheduled_message_result: Missing request_id")
-            await websocket.send_json({
-                "type": "error",
-                "message": "request_id is required",
-            })
-            return
-        
-        logger.info(f"📬 Received scheduled message result: {request_id} (success: {result.get('success', False)})")
-        
-        # Pass the result to the scheduled_messages module to resolve the pending future
-        handle_scheduled_message_result(request_id, result)
-        
-        # Acknowledge receipt
-        await websocket.send_json({
-            "type": "scheduled_message_result_received",
-            "request_id": request_id,
-            "success": True,
-        })
-        
-    except Exception as e:
-        logger.error(f"Error handling scheduled_message_result: {e}", exc_info=True)
-        await websocket.send_json({
-            "type": "error",
-            "message": f"Scheduled message result failed: {str(e)}",
-        })

reachys_brain/routes/conversation/__init__.py

@@ -0,0 +1,115 @@
+"""WebSocket endpoint for real-time conversation with iOS app.
+
+This package provides the WebSocket endpoint for voice conversations,
+delegating to specialized modules for:
+- broadcast_manager: Client connection management and broadcasting
+- conversation_services: Service lifecycle management
+- audio_manager: Audio streaming and buffering
+- animation_manager: Pre-speech animations and gestures
+"""
+
+import logging
+
+from ...tools.reminders import set_reminder_request_callback
+from ...tools.contacts import set_contacts_request_callback
+from ...tools.scheduled_messages import set_scheduled_message_callback
+from ...tools.website_generator import set_website_request_callback
+
+from ..conversation_services import (
+    get_services,
+    get_state,
+    init_services as _init_conversation_services,
+    cleanup_services as _cleanup_conversation_services,
+    wire_openai_callbacks,
+)
+
+from ..audio_manager import handle_audio_delta
+from ..task_tracker import cancel_all_tracked_tasks
+
+from .websocket import router
+from .callbacks import (
+    on_connection_state,
+    on_speaking_state,
+    on_response_state,
+    on_transcript_update,
+    on_response_text,
+    on_error,
+    on_app_change,
+    on_tool_usage,
+    on_website_ready,
+)
+from .meeting_callbacks import (
+    on_meeting_started,
+    on_meeting_stopped,
+    on_meeting_transcript_update,
+)
+from .request_handlers import (
+    on_website_request,
+    on_reminder_request,
+    on_contacts_request,
+    on_scheduled_message_request,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def init_services() -> None:
+    """Initialize conversation services and wire up callbacks."""
+    services = _init_conversation_services()
+    
+    # Wire up OpenAI callbacks
+    wire_openai_callbacks(
+        on_connection_state=on_connection_state,
+        on_speaking_state=on_speaking_state,
+        on_response_state=on_response_state,
+        on_transcript_update=on_transcript_update,
+        on_response_text=on_response_text,
+        on_audio_delta=handle_audio_delta,
+        on_error=on_error,
+        on_app_change=on_app_change,
+        on_tool_usage=on_tool_usage,
+        on_website_ready=on_website_ready,
+    )
+    
+    # Wire up meeting callbacks
+    if services.openai:
+        services.openai.on_meeting_started = on_meeting_started
+        services.openai.on_meeting_stopped = on_meeting_stopped
+        services.openai.on_meeting_transcript_update = on_meeting_transcript_update
+    
+    # Wire up website request callback to delegate generation to iOS
+    set_website_request_callback(on_website_request)
+    
+    # Wire up reminder request callback to delegate operations to iOS
+    set_reminder_request_callback(on_reminder_request)
+    
+    # Wire up contacts request callback to delegate operations to iOS
+    set_contacts_request_callback(on_contacts_request)
+    
+    # Wire up scheduled message request callback to delegate operations to iOS
+    set_scheduled_message_callback(on_scheduled_message_request)
+    
+    logger.info("Conversation services initialized")
+
+
+async def cleanup_services() -> None:
+    """Clean up conversation services.
+    
+    This is async to properly await all cleanup operations and prevent
+    the app from hanging during shutdown.
+    """
+    # Cancel all tracked tasks first
+    cancel_all_tracked_tasks()
+    # Await the async cleanup
+    await _cleanup_conversation_services()
+
+
+# Re-export for backwards compatibility
+__all__ = [
+    "router",
+    "init_services",
+    "cleanup_services",
+    "get_services",
+    "get_state",
+]
+

reachys_brain/routes/conversation/animation.py

@@ -0,0 +1,22 @@
+"""Re-exports from animation_manager for backwards compatibility.
+
+This module provides a bridge to the existing animation_manager module,
+making it accessible from within the conversation package.
+"""
+
+from ..animation_manager import (
+    handle_pre_speech_animation,
+    send_greeting,
+    send_goodbye,
+    set_custom_animations,
+    clear_custom_animations,
+)
+
+__all__ = [
+    "handle_pre_speech_animation",
+    "send_greeting",
+    "send_goodbye",
+    "set_custom_animations",
+    "clear_custom_animations",
+]
+

reachys_brain/routes/conversation/audio.py

@@ -0,0 +1,24 @@
+"""Re-exports from audio_manager for backwards compatibility.
+
+This module provides a bridge to the existing audio_manager module,
+making it accessible from within the conversation package.
+"""
+
+from ..audio_manager import (
+    handle_audio_delta,
+    delayed_resume_microphone,
+    start_audio_streaming,
+    stop_audio_streaming,
+    flush_audio_buffer,
+    stream_audio_to_openai,
+)
+
+__all__ = [
+    "handle_audio_delta",
+    "delayed_resume_microphone",
+    "start_audio_streaming",
+    "stop_audio_streaming",
+    "flush_audio_buffer",
+    "stream_audio_to_openai",
+]
+

reachys_brain/routes/conversation/callbacks.py

@@ -0,0 +1,252 @@
+"""OpenAI state callbacks for conversation handling.
+
+Handles connection state, speaking state, response state, and transcript updates.
+"""
+
+import logging
+
+from ...openai_realtime import ConnectionState, SpeakingState, ResponseState
+from ..task_tracker import create_tracked_task
+from ..broadcast_manager import broadcast
+from .services import get_services, get_state
+from .audio import delayed_resume_microphone, stop_audio_streaming
+from .animation import handle_pre_speech_animation, clear_custom_animations, set_custom_animations
+from .messages import STOP_COMMANDS
+from .history import get_history
+
+logger = logging.getLogger(__name__)
+
+
+def on_connection_state(state: ConnectionState) -> None:
+    """Handle OpenAI connection state changes."""
+    create_tracked_task(broadcast({
+        "type": "connection_state",
+        "state": state.value,
+    }))
+
+
+def on_speaking_state(state: SpeakingState) -> None:
+    """Handle OpenAI speaking state changes."""
+    services = get_services()
+    conv_state = get_state()
+    
+    # Pause/resume audio capture based on speaking state
+    if services.audio_capture:
+        if state == SpeakingState.SPEAKING:
+            services.audio_capture.pause_capture()
+            logger.info("⏸️ Paused microphone (AI speaking)")
+            
+            # Reset buffering state for new response
+            conv_state.reset_for_new_response()
+            
+            # Start subtle speaking gestures while talking
+            if services.speaking_gestures:
+                create_tracked_task(services.speaking_gestures.start())
+            
+            # Clear OpenAI's audio buffer to prevent echo from interrupting
+            if services.openai:
+                create_tracked_task(services.openai.clear_audio_buffer())
+                logger.info("🗑️ Cleared OpenAI audio buffer (preventing echo)")
+        else:
+            # AI finished speaking - stop gestures
+            if services.speaking_gestures:
+                create_tracked_task(services.speaking_gestures.stop())
+            
+            conv_state.response_count += 1
+            
+            # Reset buffering state for next response
+            conv_state.is_buffering_audio = True
+            conv_state.animation_played_for_response = False
+            
+            # Delay resuming microphone to let audio buffer drain (prevent echo)
+            create_tracked_task(delayed_resume_microphone())
+    
+    create_tracked_task(broadcast({
+        "type": "speaking_state",
+        "state": state.value,
+    }))
+
+
+def on_response_state(state: ResponseState) -> None:
+    """Handle OpenAI response lifecycle state changes.
+    
+    This is the key callback for preventing audio cutoff:
+    - WAITING: Request sent, pause microphone immediately
+    - GENERATING: Audio being received, mic stays paused
+    - COMPLETE: Audio done, wait for buffer drain then resume
+    - IDLE: Buffer drained, mic can be active
+    """
+    services = get_services()
+    
+    if state == ResponseState.WAITING:
+        # Immediately pause microphone when a request is sent
+        # This prevents VAD from detecting noise/echo before response starts
+        if services.audio_capture:
+            services.audio_capture.pause_capture()
+            logger.info("⏸️ Paused microphone (waiting for AI response)")
+        
+        # Clear OpenAI's audio buffer to prevent any buffered audio
+        if services.openai:
+            create_tracked_task(services.openai.clear_audio_buffer())
+    
+    elif state == ResponseState.GENERATING:
+        # Audio is being generated - ensure mic stays paused
+        if services.audio_capture and not services.audio_capture.is_paused:
+            services.audio_capture.pause_capture()
+            logger.info("⏸️ Paused microphone (AI generating audio)")
+    
+    elif state == ResponseState.COMPLETE:
+        # Response complete - schedule microphone resume after buffer drains
+        # The actual resume happens via delayed_resume_microphone
+        logger.info("📊 Response complete - waiting for audio buffer to drain")
+    
+    elif state == ResponseState.IDLE:
+        # Response cycle complete - microphone can be resumed
+        # This is called after buffer has drained
+        logger.info("📊 Response cycle idle - microphone can resume")
+    
+    # Broadcast state change to iOS
+    create_tracked_task(broadcast({
+        "type": "response_state",
+        "state": state.value,
+    }))
+
+
+def _is_stop_command(transcript: str, language: str = "en") -> bool:
+    """Check if the transcript is a stop command."""
+    text = transcript.strip().lower()
+    
+    # Check stop commands for current language
+    stop_words = STOP_COMMANDS.get(language, STOP_COMMANDS["en"])
+    for stop in stop_words:
+        if text == stop or text.startswith(stop + " ") or text.endswith(" " + stop):
+            return True
+    
+    # Always check English stop commands as fallback
+    if language != "en":
+        for stop in STOP_COMMANDS["en"]:
+            if text == stop or text.startswith(stop + " ") or text.endswith(" " + stop):
+                return True
+    
+    return False
+
+
+def on_transcript_update(transcript: str) -> None:
+    """Handle user transcript updates."""
+    from .commands import handle_stop_command
+    
+    services = get_services()
+    
+    # Check for stop command
+    lang = services.openai.language if services.openai else "en"
+    if _is_stop_command(transcript, lang):
+        logger.info(f"🛑 Stop command detected: '{transcript}'")
+        create_tracked_task(handle_stop_command())
+        return
+    
+    # Record to conversation history for context persistence
+    if transcript and transcript.strip():
+        history = get_history()
+        history.add_user_message(transcript)
+    
+    create_tracked_task(broadcast({
+        "type": "transcript_update",
+        "transcript": transcript,
+    }))
+
+
+def on_response_text(text: str) -> None:
+    """Handle AI response text - triggers pre-speech animation."""
+    conv_state = get_state()
+    conv_state.last_response_text = text
+    
+    # Record to conversation history for context persistence
+    if text and text.strip():
+        history = get_history()
+        history.add_assistant_message(text)
+    
+    # Trigger pre-speech animation workflow
+    create_tracked_task(handle_pre_speech_animation(text))
+    
+    create_tracked_task(broadcast({
+        "type": "response_text",
+        "text": text,
+    }))
+
+
+def on_error(error: str) -> None:
+    """Handle OpenAI errors."""
+    create_tracked_task(broadcast({
+        "type": "error",
+        "message": error,
+    }))
+
+
+def on_tool_usage(tool_name: str, status: str) -> None:
+    """Handle tool usage notifications."""
+    logger.info(f"🔧 Tool usage: {tool_name} ({status})")
+    create_tracked_task(broadcast({
+        "type": "tool_usage",
+        "tool": tool_name if status == "started" else None,
+        "status": status,
+    }))
+
+
+def on_website_ready(data: dict) -> None:
+    """Handle website generation completion."""
+    from ..broadcast_manager import safe_broadcast
+    
+    try:
+        website_id = data.get("website_id", "")
+        url = data.get("url", "")
+        title = data.get("title", "Generated Website")
+        is_edit = data.get("is_edit", False)
+        
+        if not website_id:
+            logger.error("on_website_ready: Missing website_id")
+            return
+        
+        action = "updated" if is_edit else "created"
+        logger.info(f"🌐 Website {action}: {title} ({website_id})")
+        
+        create_tracked_task(safe_broadcast({
+            "type": "website_ready",
+            "website_id": website_id,
+            "url": url,
+            "title": title,
+            "is_edit": is_edit,
+        }))
+    except Exception as e:
+        logger.error(f"Error in on_website_ready: {e}", exc_info=True)
+
+
+def on_app_change(data: dict) -> None:
+    """Handle app activation/deactivation changes from voice commands."""
+    event_type = data.get("type", "")
+    
+    if event_type == "app_activated":
+        app = data.get("app", {})
+        logger.info(f"🚀 Voice-activated app: {app.get('name', 'Unknown')}")
+        
+        # Update emotion animations if the app has custom ones
+        emotion_animations = app.get("emotion_animations", {})
+        if emotion_animations:
+            set_custom_animations(emotion_animations)
+        
+        create_tracked_task(broadcast({
+            "type": "app_activated",
+            "app": {
+                "id": app.get("id"),
+                "name": app.get("name"),
+                "description": app.get("description", ""),
+            }
+        }))
+    
+    elif event_type == "app_deactivated":
+        logger.info("🛑 Voice-deactivated app - reverting to default")
+        clear_custom_animations()
+        
+        create_tracked_task(broadcast({
+            "type": "app_deactivated"
+        }))
+

reachys_brain/routes/conversation/commands.py

@@ -0,0 +1,434 @@
+"""Command handlers for conversation WebSocket.
+
+Handles all commands received from the iOS app via WebSocket.
+"""
+
+import asyncio
+import logging
+import os
+from typing import Optional
+
+from fastapi import WebSocket
+
+from ..broadcast_manager import broadcast
+from ..task_tracker import create_tracked_task
+from .services import get_services, get_state
+from .audio import stop_audio_streaming, start_audio_streaming, delayed_resume_microphone
+from .animation import clear_custom_animations, set_custom_animations
+from .greeting import send_greeting_and_start_streaming, goodbye_and_disconnect
+from .history import get_history
+
+logger = logging.getLogger(__name__)
+
+
+async def reset_openai_session(keep_listening: bool) -> None:
+    """Hard reset OpenAI session by disconnecting and reconnecting.
+
+    OpenAI Realtime rejects changing voice via `session.update` once assistant
+    audio has been produced in the current session. To apply a new voice/language
+    reliably, we must create a new session.
+
+    If `keep_listening` is True, we restore listening + audio streaming so the
+    next user turn works without user-visible reconnect steps.
+    
+    Conversation context is preserved and restored after reconnection.
+    """
+    services = get_services()
+
+    if not services.openai:
+        return
+
+    # Get conversation history BEFORE disconnecting
+    history = get_history()
+    restore_messages = history.get_restore_messages() if history.has_history else []
+    
+    if restore_messages:
+        logger.info(f"📚 Will restore {len(restore_messages)} messages after reconnect")
+
+    # Stop any local playback/gestures
+    if services.audio_player:
+        services.audio_player.cancel()
+
+    if services.speaking_gestures:
+        await services.speaking_gestures.stop()
+
+    # Stop audio streaming task (depends on openai.is_connected)
+    stop_audio_streaming()
+
+    # Pause capture while we reset, to avoid buffering user audio into nowhere
+    if services.audio_capture:
+        services.audio_capture.pause_capture()
+
+    # Best-effort: cancel any in-flight response and clear input buffer
+    try:
+        await services.openai.cancel_response()
+        await services.openai.clear_audio_buffer()
+    except Exception:
+        pass
+
+    # Fully disconnect and reconnect (new session)
+    try:
+        await services.openai.disconnect()
+    except Exception:
+        pass
+
+    # connect() reads OPENAI_API_KEY from env (set by iOS connect command)
+    await services.openai.connect()
+    
+    # Restore conversation context after reconnection
+    if restore_messages:
+        await services.openai.restore_conversation_context(restore_messages)
+
+    if keep_listening:
+        services.openai.start_listening()
+        start_audio_streaming()
+
+        # Resume capture with normal echo-avoidance delay
+        create_tracked_task(delayed_resume_microphone())
+    else:
+        if services.audio_capture:
+            services.audio_capture.stop_capture()
+
+
+async def handle_stop_command() -> None:
+    """Handle a voice stop command - immediately end the conversation."""
+    services = get_services()
+    state = get_state()
+    
+    try:
+        # Cancel any current AI response
+        if services.audio_player:
+            services.audio_player.cancel()
+        
+        if services.openai:
+            await services.openai.cancel_response()
+        
+        # Stop speaking gestures if running
+        if services.speaking_gestures:
+            await services.speaking_gestures.stop()
+        
+        # Stop the audio stream task
+        stop_audio_streaming()
+        
+        # Stop audio capture
+        if services.audio_capture:
+            services.audio_capture.stop_capture()
+        
+        # Stop listening on OpenAI
+        if services.openai:
+            services.openai.stop_listening()
+
+            # Enforce: next conversation is always a new OpenAI session
+            try:
+                await services.openai.disconnect()
+            except Exception:
+                pass
+        
+        # Mark conversation as ended (allows idle movements to resume)
+        state.end_conversation()
+        
+        # Broadcast to iOS that listening has stopped
+        await broadcast({
+            "type": "listening_state",
+            "listening": False,
+        })
+        
+        # Also notify of the transcript that caused the stop
+        await broadcast({
+            "type": "conversation_stopped",
+            "reason": "voice_command",
+        })
+        
+        logger.info("✅ Conversation stopped via voice command")
+        
+    except Exception as e:
+        logger.error(f"Error handling stop command: {e}")
+        # Broadcast error to clients
+        await broadcast({
+            "type": "error",
+            "message": "Failed to stop conversation",
+        })
+
+
+async def handle_connect(websocket: WebSocket, data: dict) -> None:
+    """Handle the connect command."""
+    services = get_services()
+    
+    api_key = data.get("api_key") or os.environ.get("OPENAI_API_KEY")
+    
+    if not api_key:
+        await websocket.send_json({
+            "type": "error",
+            "message": "API key required",
+        })
+        return
+    
+    if data.get("api_key"):
+        # Log masked key for debugging
+        key_preview = f"***{api_key[-4:]}" if len(api_key) > 4 else "***"
+        logger.info(f"API key provided ({key_preview})")
+        os.environ["OPENAI_API_KEY"] = data["api_key"]
+    
+    await services.openai.connect(api_key)
+    
+    if services.audio_player:
+        services.audio_player.start_stream()
+
+
+async def handle_disconnect() -> None:
+    """Handle the disconnect command."""
+    services = get_services()
+    
+    stop_audio_streaming()
+    
+    if services.audio_capture:
+        services.audio_capture.stop_capture()
+    
+    if services.audio_player:
+        services.audio_player.cancel()
+    
+    await services.openai.disconnect()
+
+
+async def handle_start_listening(websocket: WebSocket) -> None:
+    """Handle the start_listening command."""
+    services = get_services()
+    state = get_state()
+    history = get_history()
+    
+    if not services.openai.is_connected:
+        # Auto-connect so that "stop => new session next time" doesn't require
+        # a separate iOS connect step.
+        try:
+            await services.openai.connect()
+        except Exception as e:
+            logger.error(f"Cannot start listening: not connected to OpenAI ({e})")
+            await websocket.send_json({
+                "type": "error",
+                "message": "Not connected to OpenAI",
+            })
+            return
+    
+    # Reset conversation state and start fresh history
+    state.reset_for_new_conversation()
+    history.clear()
+    history.start_session()
+    logger.info("🎬 New conversation started - animation state reset, history cleared")
+    
+    # Start audio capture
+    if services.audio_capture:
+        if not services.audio_capture.is_available:
+            logger.error("Audio capture not available - no microphone detected!")
+            await websocket.send_json({
+                "type": "error",
+                "message": "Microphone not available on Reachy",
+            })
+            return
+        
+        capture_started = await services.audio_capture.start_capture()
+        if not capture_started:
+            logger.error("❌ Failed to start audio capture")
+            await websocket.send_json({
+                "type": "error",
+                "message": "Failed to start microphone capture",
+            })
+            return
+        
+        logger.info("✅ Audio capture started successfully")
+    else:
+        logger.error("Audio capture service not initialized")
+        await websocket.send_json({
+            "type": "error",
+            "message": "Audio capture service not initialized",
+        })
+        return
+    
+    services.openai.start_listening()
+    logger.info("✅ OpenAI listening mode enabled")
+    
+    # IMPORTANT: Do NOT start audio streaming here!
+    # Audio streaming will be started AFTER the greeting completes.
+    # This prevents motor noise from the welcome animation and ambient
+    # noise from triggering VAD and interrupting the greeting.
+    
+    # Pause audio capture immediately - it will be resumed after greeting
+    if services.audio_capture:
+        services.audio_capture.pause_capture()
+        logger.info("⏸️ Audio capture paused until greeting completes")
+    
+    await websocket.send_json({
+        "type": "listening_state",
+        "listening": True,
+    })
+    
+    # Send greeting - audio streaming will start after it completes
+    create_tracked_task(send_greeting_and_start_streaming())
+
+
+async def handle_stop_listening(websocket: WebSocket) -> None:
+    """Handle the stop_listening command."""
+    services = get_services()
+    
+    # Stop capturing new audio input
+    stop_audio_streaming()
+    
+    if services.audio_capture:
+        services.audio_capture.stop_capture()
+    
+    services.openai.stop_listening()
+    
+    # Broadcast listening stopped immediately for UI responsiveness
+    await websocket.send_json({
+        "type": "listening_state",
+        "listening": False,
+    })
+    
+    # Send goodbye and wait for it to be spoken before disconnecting
+    # This runs in the background so we don't block the WebSocket response
+    create_tracked_task(goodbye_and_disconnect())
+
+
+async def handle_interrupt(websocket: WebSocket) -> None:
+    """Handle the interrupt_response command."""
+    services = get_services()
+    
+    logger.info("🛑 Interrupt command received from iOS!")
+    
+    # Cancel audio playback immediately
+    if services.audio_player:
+        services.audio_player.cancel()
+    
+    # Cancel the AI response
+    if services.openai:
+        await services.openai.cancel_response()
+    
+    # Stop speaking gestures
+    if services.speaking_gestures:
+        await services.speaking_gestures.stop()
+    
+    # Resume microphone capture so user can speak
+    if services.audio_capture:
+        services.audio_capture.resume_capture()
+        logger.info("▶️ Microphone resumed after interrupt")
+    
+    # Clear any buffered audio to prevent echo
+    if services.openai:
+        await services.openai.clear_audio_buffer()
+    
+    # Notify iOS that interrupt was successful
+    await websocket.send_json({
+        "type": "interrupt_complete",
+        "success": True,
+    })
+    
+    logger.info("✅ Interrupt complete - listening to user")
+
+
+async def handle_set_language(websocket: WebSocket, data: dict) -> None:
+    """Handle the set_language command."""
+    services = get_services()
+    
+    language = data.get("language", "en")
+    # Persist language; immediately reset OpenAI session to apply new settings.
+    from ..voice import set_preferred_language
+    success = set_preferred_language(language)
+    confirmed = False
+
+    if success and services.openai and services.openai.is_connected:
+        # Immediately disconnect and reconnect with new language
+        keep_listening = bool(services.openai.is_listening)
+        await reset_openai_session(keep_listening=keep_listening)
+        confirmed = services.openai.is_connected
+        logger.info(f"🌍 Language switched to {language}, session reset, confirmed={confirmed}")
+
+    await websocket.send_json({
+        "type": "language_set",
+        "language": language,
+        "success": success,
+        "confirmed": confirmed,
+    })
+
+
+async def handle_set_voice(websocket: WebSocket, data: dict) -> None:
+    """Handle the set_voice command."""
+    services = get_services()
+    
+    voice_id = data.get("voice_id", "")
+    if voice_id:
+        # Persist voice; immediately reset OpenAI session to apply new settings.
+        from ..voice import set_current_voice
+        success = set_current_voice(voice_id)
+        confirmed = False
+
+        if success and services.openai and services.openai.is_connected:
+            # Immediately disconnect and reconnect with new voice
+            keep_listening = bool(services.openai.is_listening)
+            await reset_openai_session(keep_listening=keep_listening)
+            confirmed = services.openai.is_connected
+            logger.info(f"🔊 Voice switched to {voice_id}, session reset, confirmed={confirmed}")
+
+        await websocket.send_json({
+            "type": "voice_set",
+            "voice_id": voice_id,
+            "language": services.openai.language,
+            "success": success,
+            "confirmed": confirmed,
+        })
+
+
+async def handle_set_system_prompt(websocket: WebSocket, data: dict) -> None:
+    """Handle the set_system_prompt command."""
+    services = get_services()
+    
+    system_prompt = data.get("system_prompt", "")
+    if system_prompt:
+        services.openai.set_custom_personality(system_prompt)
+        logger.info(f"🎭 Custom personality set ({len(system_prompt)} chars)")
+        await websocket.send_json({
+            "type": "personality_set",
+            "success": True,
+        })
+    else:
+        await websocket.send_json({
+            "type": "error",
+            "message": "No system_prompt provided",
+        })
+
+
+async def handle_clear_system_prompt(websocket: WebSocket) -> None:
+    """Handle the clear_system_prompt command."""
+    services = get_services()
+    
+    services.openai.clear_custom_personality()
+    logger.info("🎭 Reverted to default Reachy personality")
+    await websocket.send_json({
+        "type": "personality_cleared",
+        "success": True,
+    })
+
+
+async def handle_set_emotion_animations(websocket: WebSocket, data: dict) -> None:
+    """Handle the set_emotion_animations command."""
+    emotion_animations = data.get("emotion_animations", {})
+    if emotion_animations:
+        set_custom_animations(emotion_animations)
+        await websocket.send_json({
+            "type": "emotion_animations_set",
+            "success": True,
+            "emotions": list(emotion_animations.keys()),
+        })
+    else:
+        await websocket.send_json({
+            "type": "error",
+            "message": "No emotion_animations provided",
+        })
+
+
+async def handle_clear_emotion_animations(websocket: WebSocket) -> None:
+    """Handle the clear_emotion_animations command."""
+    clear_custom_animations()
+    await websocket.send_json({
+        "type": "emotion_animations_cleared",
+        "success": True,
+    })
+

reachys_brain/routes/conversation/greeting.py

@@ -0,0 +1,147 @@
+"""Greeting and goodbye flow for conversations.
+
+Handles the greeting sequence when a conversation starts and goodbye when it ends.
+"""
+
+import asyncio
+import logging
+
+from ..audio_stream_manager import ConversationTimings
+from .services import get_services
+from .audio import start_audio_streaming
+from .animation import send_greeting, send_goodbye
+
+logger = logging.getLogger(__name__)
+
+
+async def send_greeting_and_start_streaming() -> None:
+    """Send greeting and start audio streaming after it completes.
+    
+    This ensures that:
+    1. No audio is sent to OpenAI during the welcome animation
+    2. The greeting plays completely without VAD interruption
+    3. Audio streaming only starts after greeting finishes
+    
+    Flow:
+    1. send_greeting() sends text -> ResponseState.WAITING
+    2. Audio arrives -> ResponseState.GENERATING
+    3. response.audio.done -> ResponseState.COMPLETE
+    4. We wait for COMPLETE (audio sent by OpenAI)
+    5. Wait for audio buffer to drain (audio played by speaker)
+    6. Start streaming and resume microphone
+    """
+    from ...openai_realtime import ResponseState
+    
+    services = get_services()
+    
+    try:
+        # Send the greeting (this will set ResponseState.WAITING -> GENERATING -> COMPLETE)
+        await send_greeting()
+        
+        # Wait for the greeting response to be COMPLETE or IDLE
+        # COMPLETE = OpenAI finished sending audio
+        # IDLE = Response cycle fully complete
+        max_wait = 15.0  # Maximum wait for greeting
+        wait_interval = 0.2
+        waited = 0.0
+        
+        while waited < max_wait:
+            if services.openai:
+                state = services.openai.response_state
+                if state in (ResponseState.COMPLETE, ResponseState.IDLE):
+                    break
+            await asyncio.sleep(wait_interval)
+            waited += wait_interval
+        
+        if waited >= max_wait:
+            logger.warning("⚠️ Greeting response timeout - starting streaming anyway")
+        else:
+            logger.info(f"✅ Greeting response complete (waited {waited:.1f}s)")
+        
+        # Wait for audio to finish playing through speaker
+        if services.audio_player and services.audio_player.is_playing:
+            extra_wait = 0.0
+            max_extra = 8.0
+            while services.audio_player.is_playing and extra_wait < max_extra:
+                await asyncio.sleep(wait_interval)
+                extra_wait += wait_interval
+            if extra_wait > 0:
+                logger.info(f"⏳ Waited {extra_wait:.1f}s for greeting audio to finish")
+        
+        # Additional buffer drain time
+        await asyncio.sleep(ConversationTimings.MICROPHONE_RESUME_DELAY_SECONDS)
+        
+        # Now start audio streaming
+        if services.openai and services.openai.is_listening:
+            start_audio_streaming()
+            logger.info("✅ Audio streaming started after greeting")
+            
+            # Clear any buffered audio
+            await services.openai.clear_audio_buffer()
+            
+            # Mark response cycle as complete
+            services.openai.mark_response_complete()
+            
+            # Resume audio capture
+            if services.audio_capture:
+                services.audio_capture.resume_capture()
+                logger.info("▶️ Microphone resumed after greeting")
+        
+    except Exception as e:
+        logger.error(f"Error in greeting flow: {e}")
+        # Start streaming anyway to not leave the system in a broken state
+        if services.openai and services.openai.is_listening:
+            start_audio_streaming()
+            if services.audio_capture:
+                services.audio_capture.resume_capture()
+
+
+async def goodbye_and_disconnect() -> None:
+    """Send goodbye and wait for it to be spoken before disconnecting.
+    
+    This runs in the background so we don't block the WebSocket response.
+    """
+    from .state import get_state
+    
+    services = get_services()
+    state = get_state()
+    
+    try:
+        # Send the goodbye prompt
+        await send_goodbye()
+        
+        # Wait for the AI to generate and speak the goodbye
+        # Give it enough time to respond and speak (typical goodbye is ~3-5 seconds)
+        max_wait = 8.0  # Maximum seconds to wait
+        wait_interval = 0.2
+        waited = 0.0
+        
+        # Wait for speech to start
+        await asyncio.sleep(0.5)
+        
+        # Wait for speech to finish
+        while waited < max_wait:
+            if services.tts and services.tts.is_speaking:
+                # Speech is ongoing, keep waiting
+                await asyncio.sleep(wait_interval)
+                waited += wait_interval
+            elif waited > 1.0:
+                # Speech has finished (or never started after initial delay)
+                break
+            else:
+                # Give it a moment to start
+                await asyncio.sleep(wait_interval)
+                waited += wait_interval
+        
+    except Exception as e:
+        logger.error(f"Error in goodbye sequence: {e}")
+    finally:
+        # Now disconnect the OpenAI session
+        try:
+            await services.openai.disconnect()
+        except Exception:
+            pass
+        
+        # Mark conversation as ended (allows idle movements to resume)
+        state.end_conversation()
+

reachys_brain/routes/conversation/history.py

@@ -0,0 +1,324 @@
+"""Conversation history management for context persistence.
+
+Tracks conversation messages and can restore context after session resets.
+This ensures continuity when voice/language changes force a session reconnect.
+
+Also provides long conversation management with automatic summarization
+when conversations exceed token limits.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Maximum messages to keep in active history
+MAX_HISTORY_MESSAGES = 30
+
+# Maximum messages to restore on session reset
+MAX_RESTORE_MESSAGES = 10
+
+# Approximate tokens per message (conservative estimate for voice conversations)
+APPROX_TOKENS_PER_MESSAGE = 50
+
+# Token threshold before triggering summarization
+TOKEN_THRESHOLD_FOR_SUMMARY = 1500
+
+# Messages to keep after summarization (most recent)
+MESSAGES_TO_KEEP_AFTER_SUMMARY = 8
+
+
+@dataclass
+class HistoryMessage:
+    """A message in the conversation history."""
+    role: str  # "user" or "assistant"
+    content: str
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    token_estimate: int = 0
+    
+    def __post_init__(self):
+        # Estimate tokens: ~4 chars per token for English
+        if self.token_estimate == 0:
+            self.token_estimate = max(1, len(self.content) // 4)
+
+
+class ConversationHistory:
+    """Manages conversation history for context persistence.
+    
+    Stores user and assistant messages during a conversation,
+    can generate context restoration messages for session resets,
+    and automatically manages long conversations through summarization.
+    """
+    
+    def __init__(self, max_messages: int = MAX_HISTORY_MESSAGES):
+        """Initialize conversation history.
+        
+        Args:
+            max_messages: Maximum messages to keep in active history.
+        """
+        self._messages: list[HistoryMessage] = []
+        self._max_messages = max_messages
+        self._session_start: Optional[datetime] = None
+        
+        # Summary of older conversation (when history is compressed)
+        self._conversation_summary: Optional[str] = None
+        self._summarized_message_count: int = 0
+        
+        # Token tracking
+        self._total_token_estimate: int = 0
+    
+    def start_session(self) -> None:
+        """Mark the start of a new session (but keep history)."""
+        self._session_start = datetime.utcnow()
+        logger.info(f"📚 Conversation session started (history: {len(self._messages)} messages)")
+    
+    def clear(self) -> None:
+        """Clear all conversation history."""
+        self._messages = []
+        self._session_start = None
+        self._conversation_summary = None
+        self._summarized_message_count = 0
+        self._total_token_estimate = 0
+        logger.info("📚 Conversation history cleared")
+    
+    def add_user_message(self, content: str) -> None:
+        """Add a user message to history.
+        
+        Args:
+            content: The user's transcribed message.
+        """
+        if not content or not content.strip():
+            return
+        
+        msg = HistoryMessage(role="user", content=content.strip())
+        self._messages.append(msg)
+        self._total_token_estimate += msg.token_estimate
+        
+        self._check_and_summarize()
+        self._trim_history()
+        logger.debug(f"📚 Added user message (total: {len(self._messages)}, ~{self._total_token_estimate} tokens)")
+    
+    def add_assistant_message(self, content: str) -> None:
+        """Add an assistant message to history.
+        
+        Args:
+            content: The assistant's response.
+        """
+        if not content or not content.strip():
+            return
+        
+        msg = HistoryMessage(role="assistant", content=content.strip())
+        self._messages.append(msg)
+        self._total_token_estimate += msg.token_estimate
+        
+        self._check_and_summarize()
+        self._trim_history()
+        logger.debug(f"📚 Added assistant message (total: {len(self._messages)}, ~{self._total_token_estimate} tokens)")
+    
+    def _check_and_summarize(self) -> None:
+        """Check if we need to summarize older messages to manage context size."""
+        if self._total_token_estimate < TOKEN_THRESHOLD_FOR_SUMMARY:
+            return
+        
+        if len(self._messages) <= MESSAGES_TO_KEEP_AFTER_SUMMARY:
+            return
+        
+        # Number of messages to summarize
+        messages_to_summarize = self._messages[:-MESSAGES_TO_KEEP_AFTER_SUMMARY]
+        
+        if len(messages_to_summarize) < 4:
+            return  # Not enough to summarize
+        
+        logger.info(f"📚 Summarizing {len(messages_to_summarize)} older messages (token threshold reached)")
+        
+        # Generate a simple summary of older messages
+        summary_parts = []
+        
+        # Track topics discussed
+        topics = set()
+        for msg in messages_to_summarize:
+            # Simple topic extraction (first few words of user messages)
+            if msg.role == "user" and len(msg.content) > 10:
+                words = msg.content.split()[:5]
+                if len(words) >= 2:
+                    topics.add(" ".join(words[:3]))
+        
+        # Build summary
+        user_msgs = [m for m in messages_to_summarize if m.role == "user"]
+        assistant_msgs = [m for m in messages_to_summarize if m.role == "assistant"]
+        
+        if topics:
+            topic_list = list(topics)[:5]  # Max 5 topics
+            summary_parts.append(f"Earlier topics: {', '.join(topic_list)}")
+        
+        summary_parts.append(
+            f"({len(user_msgs)} user messages, {len(assistant_msgs)} assistant responses summarized)"
+        )
+        
+        # Update summary
+        new_summary = ". ".join(summary_parts)
+        if self._conversation_summary:
+            self._conversation_summary = f"{self._conversation_summary} | {new_summary}"
+        else:
+            self._conversation_summary = new_summary
+        
+        # Update counters
+        summarized_tokens = sum(m.token_estimate for m in messages_to_summarize)
+        self._summarized_message_count += len(messages_to_summarize)
+        self._total_token_estimate -= summarized_tokens
+        
+        # Keep only recent messages
+        self._messages = self._messages[-MESSAGES_TO_KEEP_AFTER_SUMMARY:]
+        
+        logger.info(f"📚 Summarized conversation. Kept {len(self._messages)} recent messages. Summary: {new_summary[:100]}...")
+    
+    def _trim_history(self) -> None:
+        """Trim history to max messages, keeping most recent."""
+        if len(self._messages) > self._max_messages:
+            removed = len(self._messages) - self._max_messages
+            removed_tokens = sum(m.token_estimate for m in self._messages[:removed])
+            self._messages = self._messages[-self._max_messages:]
+            self._total_token_estimate -= removed_tokens
+            logger.debug(f"📚 Trimmed {removed} old messages from history")
+    
+    @property
+    def message_count(self) -> int:
+        """Get number of active messages in history."""
+        return len(self._messages)
+    
+    @property
+    def total_message_count(self) -> int:
+        """Get total messages including summarized ones."""
+        return len(self._messages) + self._summarized_message_count
+    
+    @property
+    def has_history(self) -> bool:
+        """Check if there's any conversation history."""
+        return len(self._messages) > 0 or self._conversation_summary is not None
+    
+    @property
+    def has_summary(self) -> bool:
+        """Check if there's a summary of older messages."""
+        return self._conversation_summary is not None
+    
+    @property
+    def estimated_tokens(self) -> int:
+        """Get estimated token count of active history."""
+        return self._total_token_estimate
+    
+    def get_restore_messages(self, max_messages: int = MAX_RESTORE_MESSAGES) -> list[dict]:
+        """Get messages formatted for OpenAI conversation.item.create.
+        
+        Returns recent messages that can be sent to OpenAI to restore context
+        after a session reset. Includes summary context if available.
+        
+        Args:
+            max_messages: Maximum messages to include.
+            
+        Returns:
+            List of message dicts for OpenAI API.
+        """
+        formatted = []
+        
+        # If we have a summary, include it as context
+        if self._conversation_summary:
+            formatted.append({
+                "type": "message",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": f"[Context from earlier in our conversation: {self._conversation_summary}]",
+                    }
+                ],
+            })
+        
+        if not self._messages:
+            return formatted
+        
+        # Get the most recent messages
+        recent = self._messages[-max_messages:]
+        
+        # Format for OpenAI Realtime API
+        for msg in recent:
+            formatted.append({
+                "type": "message",
+                "role": msg.role,
+                "content": [
+                    {
+                        "type": "input_text" if msg.role == "user" else "text",
+                        "text": msg.content,
+                    }
+                ],
+            })
+        
+        return formatted
+    
+    def get_context_summary(self) -> str:
+        """Get a brief summary of conversation context.
+        
+        Useful for debugging or injecting as context note.
+        
+        Returns:
+            Summary string.
+        """
+        if not self._messages and not self._conversation_summary:
+            return "No previous conversation."
+        
+        parts = []
+        
+        if self._conversation_summary:
+            parts.append(f"Summary: {self._conversation_summary[:150]}")
+        
+        msg_count = len(self._messages)
+        if msg_count > 0:
+            user_count = sum(1 for m in self._messages if m.role == "user")
+            assistant_count = msg_count - user_count
+            parts.append(f"Active: {msg_count} messages ({user_count} user, {assistant_count} assistant)")
+        
+        if self._summarized_message_count > 0:
+            parts.append(f"Summarized: {self._summarized_message_count} older messages")
+        
+        parts.append(f"Est. tokens: ~{self._total_token_estimate}")
+        
+        return " | ".join(parts)
+    
+    def get_stats(self) -> dict:
+        """Get conversation statistics.
+        
+        Returns:
+            Dictionary with conversation stats.
+        """
+        return {
+            "active_messages": len(self._messages),
+            "summarized_messages": self._summarized_message_count,
+            "total_messages": self.total_message_count,
+            "estimated_tokens": self._total_token_estimate,
+            "has_summary": self.has_summary,
+            "session_start": self._session_start.isoformat() if self._session_start else None,
+        }
+
+
+# Global instance
+_history: Optional[ConversationHistory] = None
+
+
+def get_history() -> ConversationHistory:
+    """Get the global conversation history instance.
+    
+    Returns:
+        The ConversationHistory singleton.
+    """
+    global _history
+    if _history is None:
+        _history = ConversationHistory()
+    return _history
+
+
+def clear_history() -> None:
+    """Clear the global conversation history."""
+    global _history
+    if _history:
+        _history.clear()

reachys_brain/routes/conversation/meeting_callbacks.py

@@ -0,0 +1,45 @@
+"""Meeting-specific callbacks for conversation handling.
+
+Handles meeting started, stopped, and transcript update events.
+"""
+
+import logging
+
+from ..broadcast_manager import safe_broadcast
+from ..task_tracker import create_tracked_task
+
+logger = logging.getLogger(__name__)
+
+
+def on_meeting_started(meeting_id: str, title: str) -> None:
+    """Handle meeting recording started."""
+    logger.info(f"📝 Meeting started: {title} ({meeting_id})")
+    create_tracked_task(safe_broadcast({
+        "type": "meeting_started",
+        "meeting_id": meeting_id,
+        "title": title,
+    }))
+
+
+def on_meeting_stopped(meeting_id: str) -> None:
+    """Handle meeting recording stopped."""
+    logger.info(f"📝 Meeting stopped: {meeting_id}")
+    create_tracked_task(safe_broadcast({
+        "type": "meeting_stopped",
+        "meeting_id": meeting_id,
+    }))
+
+
+def on_meeting_transcript_update(meeting_id: str, transcript: str) -> None:
+    """Handle meeting transcript update."""
+    # Only send the last portion for live updates (full transcript can be large)
+    # Get last 500 characters for preview
+    preview = transcript[-500:] if len(transcript) > 500 else transcript
+    
+    create_tracked_task(safe_broadcast({
+        "type": "meeting_transcript_update",
+        "meeting_id": meeting_id,
+        "transcript_preview": preview,
+        "total_length": len(transcript),
+    }))
+

reachys_brain/routes/conversation/messages.py

@@ -0,0 +1,10 @@
+"""Message constants and utilities for conversation handling.
+
+Contains stop commands and other conversation-related message patterns.
+"""
+
+# Re-export from existing conversation_messages module
+from ..conversation_messages import STOP_COMMANDS
+
+__all__ = ["STOP_COMMANDS"]
+

reachys_brain/routes/conversation/request_handlers.py

@@ -0,0 +1,301 @@
+"""iOS request handlers for conversation WebSocket.
+
+Handles request/response patterns for reminders, contacts, websites,
+and scheduled messages delegated to iOS.
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import WebSocket
+
+from ..broadcast_manager import safe_broadcast
+from ..task_tracker import create_tracked_task
+from ...tools.reminders import handle_reminder_result
+from ...tools.contacts import handle_contacts_result
+from ...tools.scheduled_messages import handle_scheduled_message_result
+from ...tools.website_generator import save_website_from_ios
+
+logger = logging.getLogger(__name__)
+
+
+# MARK: - Request Callbacks (called by tools to request iOS action)
+
+def on_website_request(
+    website_id: str,
+    description: str,
+    is_edit: bool,
+    existing_html: Optional[str],
+) -> None:
+    """Handle website generation request - delegates to iOS."""
+    try:
+        if not website_id:
+            logger.error("on_website_request: Missing website_id")
+            return
+        
+        if not description:
+            logger.error("on_website_request: Missing description")
+            return
+        
+        action = "Editing" if is_edit else "Creating"
+        desc_preview = description[:50] if description else ""
+        logger.info(f"📱 Requesting iOS to generate website {website_id}: {desc_preview}...")
+        
+        # Limit existing_html size for broadcast to prevent WebSocket issues
+        broadcast_existing_html = existing_html
+        if existing_html and len(existing_html) > 100000:
+            logger.warning(f"Truncating existing_html for broadcast ({len(existing_html)} chars)")
+            broadcast_existing_html = existing_html[:100000]
+        
+        create_tracked_task(safe_broadcast({
+            "type": "website_request",
+            "website_id": website_id,
+            "description": description,
+            "is_edit": is_edit,
+            "existing_html": broadcast_existing_html,
+        }))
+    except Exception as e:
+        logger.error(f"Error in on_website_request: {e}", exc_info=True)
+
+
+def on_reminder_request(
+    request_id: str,
+    action: str,
+    params: dict,
+) -> None:
+    """Handle reminder operation request - delegates to iOS."""
+    try:
+        if not request_id:
+            logger.error("on_reminder_request: Missing request_id")
+            return
+        
+        logger.info(f"📱 Requesting iOS to {action} reminder: {request_id}")
+        
+        create_tracked_task(safe_broadcast({
+            "type": "reminder_request",
+            "request_id": request_id,
+            "action": action,
+            "params": params,
+        }))
+    except Exception as e:
+        logger.error(f"Error in on_reminder_request: {e}", exc_info=True)
+
+
+def on_contacts_request(
+    request_id: str,
+    action: str,
+    params: dict,
+) -> None:
+    """Handle contacts operation request - delegates to iOS."""
+    try:
+        if not request_id:
+            logger.error("on_contacts_request: Missing request_id")
+            return
+        
+        logger.info(f"📇 Requesting iOS to {action} contacts: {request_id}")
+        
+        create_tracked_task(safe_broadcast({
+            "type": "contacts_request",
+            "request_id": request_id,
+            "action": action,
+            "params": params,
+        }))
+    except Exception as e:
+        logger.error(f"Error in on_contacts_request: {e}", exc_info=True)
+
+
+def on_scheduled_message_request(
+    request_id: str,
+    action: str,
+    params: dict,
+) -> None:
+    """Handle scheduled message operation request - delegates to iOS."""
+    try:
+        if not request_id:
+            logger.error("on_scheduled_message_request: Missing request_id")
+            return
+        
+        logger.info(f"📬 Requesting iOS to {action} scheduled message: {request_id}")
+        
+        create_tracked_task(safe_broadcast({
+            "type": "scheduled_message_request",
+            "request_id": request_id,
+            "action": action,
+            "params": params,
+        }))
+    except Exception as e:
+        logger.error(f"Error in on_scheduled_message_request: {e}", exc_info=True)
+
+
+# MARK: - WebSocket Command Handlers (handle responses from iOS)
+
+async def handle_upload_website(websocket: WebSocket, data: dict) -> None:
+    """Handle the upload_website command."""
+    try:
+        website_id = data.get("website_id", "")
+        html_content = data.get("html_content", "")
+        title = data.get("title", "Generated Website")
+        description = data.get("description", "")
+        
+        # Validate required fields
+        if not website_id:
+            logger.error("upload_website: Missing website_id")
+            await websocket.send_json({
+                "type": "error",
+                "message": "website_id is required",
+            })
+            return
+        
+        if not html_content:
+            logger.error("upload_website: Missing html_content")
+            await websocket.send_json({
+                "type": "error",
+                "message": "html_content is required",
+            })
+            return
+        
+        # Log upload size for debugging
+        logger.info(f"📤 Receiving website upload: {website_id} ({len(html_content)} bytes)")
+        
+        # Save the website to robot storage
+        result = await save_website_from_ios(
+            website_id=website_id,
+            html_content=html_content,
+            title=title,
+            description=description,
+        )
+        
+        if result.get("success"):
+            logger.info(f"💾 Website uploaded from iOS: {website_id}")
+            await websocket.send_json({
+                "type": "website_uploaded",
+                "website_id": website_id,
+                "url": result.get("url"),
+                "title": title,
+                "success": True,
+            })
+            
+            # Broadcast to all clients that website is ready
+            await safe_broadcast({
+                "type": "website_ready",
+                "website_id": website_id,
+                "url": result.get("url"),
+                "title": title,
+                "is_edit": data.get("is_edit", False),
+            })
+        else:
+            error_msg = result.get("error", "Failed to save website")
+            logger.error(f"upload_website failed: {error_msg}")
+            await websocket.send_json({
+                "type": "error",
+                "message": error_msg,
+            })
+    except Exception as e:
+        logger.error(f"Error handling upload_website: {e}", exc_info=True)
+        await websocket.send_json({
+            "type": "error",
+            "message": f"Upload failed: {str(e)}",
+        })
+
+
+async def handle_reminder_result_cmd(websocket: WebSocket, data: dict) -> None:
+    """Handle the reminder_result command from iOS."""
+    try:
+        request_id = data.get("request_id", "")
+        result = data.get("result", {})
+        
+        if not request_id:
+            logger.error("reminder_result: Missing request_id")
+            await websocket.send_json({
+                "type": "error",
+                "message": "request_id is required",
+            })
+            return
+        
+        logger.info(f"📱 Received reminder result: {request_id} (success: {result.get('success', False)})")
+        
+        # Pass the result to the reminders module to resolve the pending future
+        handle_reminder_result(request_id, result)
+        
+        # Acknowledge receipt
+        await websocket.send_json({
+            "type": "reminder_result_received",
+            "request_id": request_id,
+            "success": True,
+        })
+        
+    except Exception as e:
+        logger.error(f"Error handling reminder_result: {e}", exc_info=True)
+        await websocket.send_json({
+            "type": "error",
+            "message": f"Reminder result failed: {str(e)}",
+        })
+
+
+async def handle_contacts_result_cmd(websocket: WebSocket, data: dict) -> None:
+    """Handle the contacts_result command from iOS."""
+    try:
+        request_id = data.get("request_id", "")
+        result = data.get("result", {})
+        
+        if not request_id:
+            logger.error("contacts_result: Missing request_id")
+            await websocket.send_json({
+                "type": "error",
+                "message": "request_id is required",
+            })
+            return
+        
+        logger.info(f"📇 Received contacts result: {request_id} (success: {result.get('success', False)})")
+        
+        # Pass the result to the contacts module to resolve the pending future
+        handle_contacts_result(request_id, result)
+        
+        # Acknowledge receipt
+        await websocket.send_json({
+            "type": "contacts_result_received",
+            "request_id": request_id,
+            "success": True,
+        })
+        
+    except Exception as e:
+        logger.error(f"Error handling contacts_result: {e}", exc_info=True)
+        await websocket.send_json({
+            "type": "error",
+            "message": f"Contacts result failed: {str(e)}",
+        })
+
+
+async def handle_scheduled_message_result_cmd(websocket: WebSocket, data: dict) -> None:
+    """Handle the scheduled_message_result command from iOS."""
+    try:
+        request_id = data.get("request_id", "")
+        result = data.get("result", {})
+        
+        if not request_id:
+            logger.error("scheduled_message_result: Missing request_id")
+            await websocket.send_json({
+                "type": "error",
+                "message": "request_id is required",
+            })
+            return
+        
+        logger.info(f"📬 Received scheduled message result: {request_id} (success: {result.get('success', False)})")
+        
+        # Pass the result to the scheduled_messages module to resolve the pending future
+        handle_scheduled_message_result(request_id, result)
+        
+        # Acknowledge receipt
+        await websocket.send_json({
+            "type": "scheduled_message_result_received",
+            "request_id": request_id,
+            "success": True,
+        })
+        
+    except Exception as e:
+        logger.error(f"Error handling scheduled_message_result: {e}", exc_info=True)
+        await websocket.send_json({
+            "type": "error",
+            "message": f"Scheduled message result failed: {str(e)}",
+        })
+

reachys_brain/routes/conversation/services.py

@@ -0,0 +1,24 @@
+"""Re-exports from conversation_services for backwards compatibility.
+
+This module provides a bridge to the existing conversation_services module,
+making it accessible from within the conversation package.
+"""
+
+from ..conversation_services import (
+    ConversationServices,
+    ConversationState,
+    get_services,
+    get_state,
+    init_services as _init_services,
+    cleanup_services as _cleanup_services,
+    wire_openai_callbacks,
+)
+
+__all__ = [
+    "ConversationServices",
+    "ConversationState",
+    "get_services",
+    "get_state",
+    "wire_openai_callbacks",
+]
+

reachys_brain/routes/conversation/state.py

@@ -0,0 +1,9 @@
+"""Re-exports state from conversation_services.
+
+Provides access to conversation state from within the package.
+"""
+
+from ..conversation_services import get_state, ConversationState
+
+__all__ = ["get_state", "ConversationState"]
+

reachys_brain/routes/conversation/websocket.py

@@ -0,0 +1,158 @@
+"""WebSocket endpoint for real-time conversation with iOS app.
+
+This module provides the WebSocket endpoint for voice conversations.
+"""
+
+import logging
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from ..broadcast_manager import add_client, remove_client
+from .services import get_services, get_state
+from . import commands
+from . import request_handlers
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["Conversation"])
+
+
+@router.websocket("/ws/conversation")
+async def conversation_websocket(websocket: WebSocket) -> None:
+    """WebSocket endpoint for iOS conversation app.
+    
+    Accepts commands from iOS and relays events from OpenAI.
+    
+    Commands:
+        - connect: Connect to OpenAI (requires api_key)
+        - disconnect: Disconnect from OpenAI
+        - start_listening: Start microphone capture
+        - stop_listening: Stop microphone capture
+        - set_language: Set conversation language
+        - set_voice: Set voice ID (also updates language)
+        - send_text: Send a text message
+        - set_system_prompt: Set custom personality (requires system_prompt)
+        - clear_system_prompt: Clear custom personality, revert to default
+        - cancel_response: Cancel current AI response
+        - clear_audio_buffer: Clear the input audio buffer
+    
+    Events (sent to iOS):
+        - connection_state: OpenAI connection state
+        - speaking_state: AI speaking state
+        - transcript_update: User transcript (real-time)
+        - response_text: AI response text
+        - personality_set: Custom personality was set
+        - personality_cleared: Reverted to default personality
+        - error: Error messages
+    """
+    await websocket.accept()
+    count = add_client(websocket)
+    logger.info(f"iOS client connected ({count} total)")
+    
+    services = get_services()
+    
+    # Send current state
+    if services.openai:
+        await websocket.send_json({
+            "type": "connection_state",
+            "state": services.openai.connection_state.value,
+        })
+    
+    try:
+        while True:
+            data = await websocket.receive_json()
+            command = data.get("command", "")
+            await _handle_command(websocket, command, data)
+    
+    except WebSocketDisconnect:
+        logger.info("iOS client disconnected")
+    except Exception as e:
+        logger.error(f"WebSocket error: {e}")
+    finally:
+        count = remove_client(websocket)
+        logger.info(f"iOS client removed ({count} remaining)")
+
+
+async def _handle_command(websocket: WebSocket, command: str, data: dict) -> None:
+    """Handle a command from the iOS app."""
+    from . import init_services
+    
+    services = get_services()
+    
+    if not services.is_initialized:
+        init_services()
+        services = get_services()
+    
+    try:
+        if command == "connect":
+            await commands.handle_connect(websocket, data)
+        
+        elif command == "disconnect":
+            await commands.handle_disconnect()
+        
+        elif command == "start_listening":
+            await commands.handle_start_listening(websocket)
+        
+        elif command == "stop_listening":
+            await commands.handle_stop_listening(websocket)
+        
+        elif command == "set_language":
+            await commands.handle_set_language(websocket, data)
+        
+        elif command == "set_voice":
+            await commands.handle_set_voice(websocket, data)
+        
+        elif command == "send_text":
+            text = data.get("text", "")
+            if text:
+                await services.openai.send_text_message(text)
+        
+        elif command == "cancel_response":
+            if services.audio_player:
+                services.audio_player.cancel()
+            await services.openai.cancel_response()
+        
+        elif command == "interrupt_response":
+            await commands.handle_interrupt(websocket)
+        
+        elif command == "clear_audio_buffer":
+            await services.openai.clear_audio_buffer()
+        
+        elif command == "set_system_prompt":
+            await commands.handle_set_system_prompt(websocket, data)
+        
+        elif command == "clear_system_prompt":
+            await commands.handle_clear_system_prompt(websocket)
+        
+        elif command == "set_emotion_animations":
+            await commands.handle_set_emotion_animations(websocket, data)
+        
+        elif command == "clear_emotion_animations":
+            await commands.handle_clear_emotion_animations(websocket)
+        
+        elif command == "upload_website":
+            await request_handlers.handle_upload_website(websocket, data)
+        
+        elif command == "reminder_result":
+            await request_handlers.handle_reminder_result_cmd(websocket, data)
+        
+        elif command == "contacts_result":
+            await request_handlers.handle_contacts_result_cmd(websocket, data)
+        
+        elif command == "scheduled_message_result":
+            await request_handlers.handle_scheduled_message_result_cmd(websocket, data)
+        
+        else:
+            logger.warning(f"Unknown command: {command}")
+            await websocket.send_json({
+                "type": "error",
+                "message": f"Unknown command: {command}",
+            })
+    
+    except Exception as e:
+        logger.error(f"Error handling command {command}: {e}")
+        await websocket.send_json({
+            "type": "error",
+            "message": str(e),
+        })
+

reachys_brain/routes/voice.py

@@ -1,1139 +0,0 @@
-"""Voice configuration endpoints for OpenAI Realtime voices."""
-
-import asyncio
-import io
-import logging
-import os
-import subprocess
-import tempfile
-from typing import Optional
-
-from fastapi import APIRouter, HTTPException
-import httpx
-
-from ..models import Voice, VoiceRequest, VoiceResponse, VoicesListResponse
-from ..audio_playback import is_kids_mode_enabled, set_kids_mode, KIDS_MODE_PITCH_CENTS, KIDS_MODE_TEMPO
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(tags=["Voice"])
-
-# Database keys for voice settings
-VOICE_ID_KEY = "voice_id"
-PREFERRED_LANGUAGE_KEY = "preferred_language"
-KIDS_MODE_KEY = "kids_mode_enabled"
-
-# Database keys for VAD (Voice Activity Detection) settings
-VAD_THRESHOLD_KEY = "vad_threshold"
-VAD_SILENCE_MS_KEY = "vad_silence_ms"
-VAD_PREFIX_MS_KEY = "vad_prefix_ms"
-
-# Default VAD values
-# Increased threshold to reduce sensitivity to background noise and echo
-DEFAULT_VAD_THRESHOLD = 0.8  # 0.0-1.0, higher = less sensitive (increased from 0.7)
-DEFAULT_VAD_SILENCE_MS = 800  # Silence duration before responding (ms) (increased from 700)
-DEFAULT_VAD_PREFIX_MS = 300  # Audio padding before speech detection (ms)
-
-# VAD Presets for different environments
-VAD_PRESETS = {
-    "quiet_room": {
-        "id": "quiet_room",
-        "name": "Quiet Room",
-        "description": "More sensitive, responds faster. Best for quiet environments.",
-        "threshold": 0.5,
-        "silence_ms": 500,
-        "prefix_ms": 300,
-    },
-    "normal": {
-        "id": "normal",
-        "name": "Normal",
-        "description": "Balanced settings for typical use.",
-        "threshold": 0.8,
-        "silence_ms": 800,
-        "prefix_ms": 300,
-    },
-    "noisy": {
-        "id": "noisy",
-        "name": "Noisy Environment",
-        "description": "Less sensitive, ignores background noise better.",
-        "threshold": 0.85,
-        "silence_ms": 1000,
-        "prefix_ms": 400,
-    },
-    "conference": {
-        "id": "conference",
-        "name": "Conference Room",
-        "description": "Very strict, ignores most background voices.",
-        "threshold": 0.9,
-        "silence_ms": 1200,
-        "prefix_ms": 500,
-    },
-}
-
-# OpenAI TTS API endpoint
-OPENAI_TTS_URL = "https://api.openai.com/v1/audio/speech"
-
-# Reachy audio device
-AUDIO_DEVICE = "plug:reachymini_audio_sink"
-
-# Available OpenAI Realtime voices with their characteristics
-OPENAI_VOICES = [
-    {
-        "id": "alloy",
-        "name": "Alloy",
-        "description": "Neutral, balanced voice",
-        "gender": "neutral",
-    },
-    {
-        "id": "ash",
-        "name": "Ash",
-        "description": "Soft, warm voice",
-        "gender": "male",
-    },
-    {
-        "id": "ballad",
-        "name": "Ballad",
-        "description": "Expressive, storytelling voice",
-        "gender": "male",
-    },
-    {
-        "id": "coral",
-        "name": "Coral",
-        "description": "Clear, friendly voice",
-        "gender": "female",
-    },
-    {
-        "id": "echo",
-        "name": "Echo",
-        "description": "Deep, resonant voice",
-        "gender": "male",
-    },
-    {
-        "id": "sage",
-        "name": "Sage",
-        "description": "Calm, wise voice",
-        "gender": "female",
-    },
-    {
-        "id": "shimmer",
-        "name": "Shimmer",
-        "description": "Bright, energetic voice",
-        "gender": "female",
-    },
-    {
-        "id": "verse",
-        "name": "Verse",
-        "description": "Dynamic, engaging voice",
-        "gender": "male",
-    },
-]
-
-# MARK: - Voice Settings Manager
-
-class VoiceSettings:
-    """Encapsulates voice and language settings for the application.
-    
-    Settings are persisted to the database for survival across restarts.
-    """
-    
-    def __init__(self):
-        self._current_voice: str = "alloy"
-        self._current_language: str = "en"
-        self._preferred_language: str = "en"
-        self._initialized: bool = False
-        
-        # VAD settings
-        self._vad_threshold: float = DEFAULT_VAD_THRESHOLD
-        self._vad_silence_ms: int = DEFAULT_VAD_SILENCE_MS
-        self._vad_prefix_ms: int = DEFAULT_VAD_PREFIX_MS
-        
-        # Callback for VAD settings changes (set by OpenAIRealtimeService)
-        self.on_vad_settings_changed: Optional[callable] = None
-    
-    @property
-    def current_voice(self) -> str:
-        return self._current_voice
-    
-    @property
-    def current_language(self) -> str:
-        return self._current_language
-    
-    @property
-    def preferred_language(self) -> str:
-        return self._preferred_language
-    
-    @property
-    def kids_mode(self) -> bool:
-        """Check if kids mode (pitch shifting) is enabled."""
-        return is_kids_mode_enabled()
-    
-    @property
-    def vad_threshold(self) -> float:
-        """Get the VAD threshold (0.0-1.0, higher = less sensitive)."""
-        return self._vad_threshold
-    
-    @property
-    def vad_silence_ms(self) -> int:
-        """Get the VAD silence duration in milliseconds."""
-        return self._vad_silence_ms
-    
-    @property
-    def vad_prefix_ms(self) -> int:
-        """Get the VAD prefix padding in milliseconds."""
-        return self._vad_prefix_ms
-    
-    def set_voice(self, voice_id: str) -> bool:
-        """Set the current OpenAI voice. Returns True if successful."""
-        valid_ids = [v["id"] for v in OPENAI_VOICES]
-        if voice_id not in valid_ids:
-            return False
-        self._current_voice = voice_id
-        logger.info(f"🔊 Voice changed to: {voice_id}")
-        # Persist to database in background
-        self._persist_setting(VOICE_ID_KEY, voice_id)
-        return True
-    
-    def set_language(self, language: str) -> None:
-        """Set the current language for the conversation."""
-        self._current_language = language
-        logger.info(f"🌍 Language changed to: {language}")
-    
-    def set_preferred_language(self, language: str) -> bool:
-        """Set the user's preferred language. Returns True if successful."""
-        valid_codes = [lang["code"] for lang in SUPPORTED_LANGUAGES]
-        if language not in valid_codes:
-            return False
-        self._preferred_language = language
-        self._current_language = language
-        logger.info(f"🌍 Preferred language set to: {language}")
-        # Persist to database in background
-        self._persist_setting(PREFERRED_LANGUAGE_KEY, language)
-        return True
-    
-    def set_kids_mode(self, enabled: bool) -> None:
-        """Enable or disable kids mode (pitch shifting for younger voice)."""
-        set_kids_mode(enabled)
-        logger.info(f"🧒 Kids mode {'enabled' if enabled else 'disabled'}")
-        # Persist to database in background
-        self._persist_setting(KIDS_MODE_KEY, str(enabled).lower())
-    
-    def set_vad_threshold(self, threshold: float) -> bool:
-        """Set the VAD threshold (0.0-1.0, higher = less sensitive).
-        
-        Returns True if successful.
-        """
-        if not 0.0 <= threshold <= 1.0:
-            return False
-        self._vad_threshold = threshold
-        logger.info(f"🎤 VAD threshold set to: {threshold}")
-        self._persist_setting(VAD_THRESHOLD_KEY, str(threshold))
-        self._notify_vad_change()
-        return True
-    
-    def set_vad_silence_ms(self, silence_ms: int) -> bool:
-        """Set the VAD silence duration in milliseconds (200-3000).
-        
-        Returns True if successful.
-        """
-        if not 200 <= silence_ms <= 3000:
-            return False
-        self._vad_silence_ms = silence_ms
-        logger.info(f"🎤 VAD silence duration set to: {silence_ms}ms")
-        self._persist_setting(VAD_SILENCE_MS_KEY, str(silence_ms))
-        self._notify_vad_change()
-        return True
-    
-    def set_vad_prefix_ms(self, prefix_ms: int) -> bool:
-        """Set the VAD prefix padding in milliseconds (100-1000).
-        
-        Returns True if successful.
-        """
-        if not 100 <= prefix_ms <= 1000:
-            return False
-        self._vad_prefix_ms = prefix_ms
-        logger.info(f"🎤 VAD prefix padding set to: {prefix_ms}ms")
-        self._persist_setting(VAD_PREFIX_MS_KEY, str(prefix_ms))
-        self._notify_vad_change()
-        return True
-    
-    def set_vad_settings(
-        self,
-        threshold: Optional[float] = None,
-        silence_ms: Optional[int] = None,
-        prefix_ms: Optional[int] = None,
-    ) -> bool:
-        """Set multiple VAD settings at once.
-        
-        Only provided values are updated. Returns True if all valid.
-        """
-        success = True
-        changed = False
-        
-        if threshold is not None:
-            if 0.0 <= threshold <= 1.0:
-                self._vad_threshold = threshold
-                self._persist_setting(VAD_THRESHOLD_KEY, str(threshold))
-                changed = True
-            else:
-                success = False
-        
-        if silence_ms is not None:
-            if 200 <= silence_ms <= 3000:
-                self._vad_silence_ms = silence_ms
-                self._persist_setting(VAD_SILENCE_MS_KEY, str(silence_ms))
-                changed = True
-            else:
-                success = False
-        
-        if prefix_ms is not None:
-            if 100 <= prefix_ms <= 1000:
-                self._vad_prefix_ms = prefix_ms
-                self._persist_setting(VAD_PREFIX_MS_KEY, str(prefix_ms))
-                changed = True
-            else:
-                success = False
-        
-        if changed:
-            logger.info(
-                f"🎤 VAD settings updated: threshold={self._vad_threshold}, "
-                f"silence={self._vad_silence_ms}ms, prefix={self._vad_prefix_ms}ms"
-            )
-            self._notify_vad_change()
-        
-        return success
-    
-    def apply_vad_preset(self, preset_id: str) -> bool:
-        """Apply a VAD preset by ID.
-        
-        Available presets: quiet_room, normal, noisy, conference
-        """
-        preset = VAD_PRESETS.get(preset_id)
-        if not preset:
-            return False
-        
-        self._vad_threshold = preset["threshold"]
-        self._vad_silence_ms = preset["silence_ms"]
-        self._vad_prefix_ms = preset["prefix_ms"]
-        
-        # Persist all settings
-        self._persist_setting(VAD_THRESHOLD_KEY, str(preset["threshold"]))
-        self._persist_setting(VAD_SILENCE_MS_KEY, str(preset["silence_ms"]))
-        self._persist_setting(VAD_PREFIX_MS_KEY, str(preset["prefix_ms"]))
-        
-        logger.info(f"🎤 Applied VAD preset: {preset['name']}")
-        self._notify_vad_change()
-        return True
-    
-    def _notify_vad_change(self) -> None:
-        """Notify listeners that VAD settings have changed."""
-        if self.on_vad_settings_changed:
-            try:
-                self.on_vad_settings_changed()
-            except Exception as e:
-                logger.error(f"Error in VAD change callback: {e}")
-    
-    def _persist_setting(self, key: str, value: str) -> None:
-        """Persist a setting to the database in a background task."""
-        try:
-            loop = asyncio.get_running_loop()
-            loop.create_task(self._save_to_database(key, value))
-        except RuntimeError:
-            # No running event loop - this can happen during initialization
-            # Settings will be persisted on the next change
-            logger.debug(f"No event loop for persisting {key}, will persist later")
-    
-    async def _save_to_database(self, key: str, value: str) -> None:
-        """Save a setting to the database."""
-        try:
-            from ..database import get_database
-            db = get_database()
-            await db.set_user_setting(key, value)
-            logger.debug(f"💾 Persisted voice setting: {key}={value}")
-        except Exception as e:
-            logger.warning(f"Failed to persist voice setting {key}: {e}")
-
-
-# Singleton instance
-_voice_settings = VoiceSettings()
-
-
-async def init_voice_settings() -> None:
-    """Initialize voice settings from the database.
-    
-    Should be called after database initialization during app startup.
-    """
-    global _voice_settings
-    
-    try:
-        from ..database import get_database
-        db = get_database()
-        
-        # Load voice ID
-        voice_id = await db.get_user_setting(VOICE_ID_KEY)
-        if voice_id:
-            valid_ids = [v["id"] for v in OPENAI_VOICES]
-            if voice_id in valid_ids:
-                _voice_settings._current_voice = voice_id
-                logger.info(f"🔊 Loaded voice from database: {voice_id}")
-        
-        # Load preferred language
-        language = await db.get_user_setting(PREFERRED_LANGUAGE_KEY)
-        if language:
-            _voice_settings._preferred_language = language
-            _voice_settings._current_language = language
-            logger.info(f"🌍 Loaded language from database: {language}")
-        
-        # Load kids mode
-        kids_mode_str = await db.get_user_setting(KIDS_MODE_KEY)
-        if kids_mode_str:
-            kids_mode_enabled = kids_mode_str.lower() == "true"
-            set_kids_mode(kids_mode_enabled)
-            logger.info(f"🧒 Loaded kids mode from database: {kids_mode_enabled}")
-        
-        # Load VAD settings
-        vad_threshold = await db.get_user_setting(VAD_THRESHOLD_KEY)
-        if vad_threshold:
-            try:
-                threshold = float(vad_threshold)
-                if 0.0 <= threshold <= 1.0:
-                    _voice_settings._vad_threshold = threshold
-                    logger.info(f"🎤 Loaded VAD threshold from database: {threshold}")
-            except ValueError:
-                pass
-        
-        vad_silence = await db.get_user_setting(VAD_SILENCE_MS_KEY)
-        if vad_silence:
-            try:
-                silence_ms = int(vad_silence)
-                if 200 <= silence_ms <= 3000:
-                    _voice_settings._vad_silence_ms = silence_ms
-                    logger.info(f"🎤 Loaded VAD silence duration from database: {silence_ms}ms")
-            except ValueError:
-                pass
-        
-        vad_prefix = await db.get_user_setting(VAD_PREFIX_MS_KEY)
-        if vad_prefix:
-            try:
-                prefix_ms = int(vad_prefix)
-                if 100 <= prefix_ms <= 1000:
-                    _voice_settings._vad_prefix_ms = prefix_ms
-                    logger.info(f"🎤 Loaded VAD prefix from database: {prefix_ms}ms")
-            except ValueError:
-                pass
-        
-        _voice_settings._initialized = True
-        logger.info("✅ Voice settings initialized from database")
-        
-    except Exception as e:
-        logger.warning(f"Failed to load voice settings from database: {e}")
-        logger.info("Using default voice settings")
-
-
-# Supported languages with display names
-SUPPORTED_LANGUAGES = [
-    {"code": "en", "name": "English", "flag": "🇺🇸"},
-    {"code": "nl", "name": "Dutch", "flag": "🇳🇱"},
-    {"code": "de", "name": "German", "flag": "🇩🇪"},
-    {"code": "fr", "name": "French", "flag": "🇫🇷"},
-    {"code": "es", "name": "Spanish", "flag": "🇪🇸"},
-    {"code": "it", "name": "Italian", "flag": "🇮🇹"},
-    {"code": "pt", "name": "Portuguese", "flag": "🇵🇹"},
-    {"code": "ja", "name": "Japanese", "flag": "🇯🇵"},
-    {"code": "ko", "name": "Korean", "flag": "🇰🇷"},
-    {"code": "zh", "name": "Chinese", "flag": "🇨🇳"},
-    {"code": "ar", "name": "Arabic", "flag": "🇸🇦"},
-    {"code": "hi", "name": "Hindi", "flag": "🇮🇳"},
-    {"code": "ru", "name": "Russian", "flag": "🇷🇺"},
-    {"code": "pl", "name": "Polish", "flag": "🇵🇱"},
-    {"code": "tr", "name": "Turkish", "flag": "🇹🇷"},
-    {"code": "sv", "name": "Swedish", "flag": "🇸🇪"},
-    {"code": "da", "name": "Danish", "flag": "🇩🇰"},
-    {"code": "no", "name": "Norwegian", "flag": "🇳🇴"},
-    {"code": "fi", "name": "Finnish", "flag": "🇫🇮"},
-]
-
-
-# MARK: - Public API Functions (delegate to VoiceSettings)
-
-def get_current_voice() -> str:
-    """Get the currently selected OpenAI voice."""
-    return _voice_settings.current_voice
-
-
-def get_current_language() -> str:
-    """Get the currently selected language."""
-    return _voice_settings.current_language
-
-
-def set_current_voice(voice_id: str) -> bool:
-    """Set the current OpenAI voice.
-    
-    Returns True if successful, False if voice not found.
-    """
-    return _voice_settings.set_voice(voice_id)
-
-
-def set_current_language(language: str) -> None:
-    """Set the current language for the conversation."""
-    _voice_settings.set_language(language)
-
-
-def get_preferred_language() -> str:
-    """Get the user's preferred language setting."""
-    return _voice_settings.preferred_language
-
-
-def set_preferred_language(language: str) -> bool:
-    """Set the user's preferred language.
-    
-    Returns True if successful, False if language not supported.
-    """
-    return _voice_settings.set_preferred_language(language)
-
-
-# MARK: - VAD Settings Public API Functions
-
-def get_vad_threshold() -> float:
-    """Get the current VAD threshold."""
-    return _voice_settings.vad_threshold
-
-
-def get_vad_silence_ms() -> int:
-    """Get the current VAD silence duration in ms."""
-    return _voice_settings.vad_silence_ms
-
-
-def get_vad_prefix_ms() -> int:
-    """Get the current VAD prefix padding in ms."""
-    return _voice_settings.vad_prefix_ms
-
-
-def get_vad_settings() -> dict:
-    """Get all VAD settings as a dictionary."""
-    return {
-        "threshold": _voice_settings.vad_threshold,
-        "silence_ms": _voice_settings.vad_silence_ms,
-        "prefix_ms": _voice_settings.vad_prefix_ms,
-    }
-
-
-def set_vad_settings_callback(callback: callable) -> None:
-    """Set the callback for VAD settings changes.
-    
-    Called when VAD settings are updated so OpenAI session can be reconfigured.
-    """
-    _voice_settings.on_vad_settings_changed = callback
-
-
-@router.get("/voices", response_model=VoicesListResponse)
-async def get_voices() -> VoicesListResponse:
-    """Get available OpenAI Realtime voices and current selection.
-    
-    OpenAI's Realtime API supports these voices that can speak any language:
-    - alloy: Neutral, balanced voice
-    - ash: Soft, warm voice  
-    - ballad: Expressive, storytelling voice
-    - coral: Clear, friendly voice
-    - echo: Deep, resonant voice
-    - sage: Calm, wise voice
-    - shimmer: Bright, energetic voice
-    - verse: Dynamic, engaging voice
-    """
-    voices = [
-        Voice(
-            id=v["id"],
-            name=v["name"],
-            language="multilingual",  # All OpenAI voices support all languages
-        )
-        for v in OPENAI_VOICES
-    ]
-    
-    logger.info(f"Returning {len(voices)} OpenAI voices, current: {_voice_settings.current_voice}, language: {_voice_settings.preferred_language}")
-    
-    return VoicesListResponse(
-        voices=voices,
-        current_voice=_voice_settings.current_voice,
-        preferred_language=_voice_settings.preferred_language,
-    )
-
-
-@router.get("/voice", response_model=VoiceResponse)
-async def get_current_voice_endpoint() -> VoiceResponse:
-    """Get the currently selected OpenAI voice."""
-    return VoiceResponse(
-        success=True,
-        current_voice=_voice_settings.current_voice,
-    )
-
-
-@router.post("/voice", response_model=VoiceResponse)
-async def set_voice(request: VoiceRequest) -> VoiceResponse:
-    """Set the OpenAI Realtime voice.
-    
-    Available voices:
-    - alloy: Neutral, balanced voice
-    - ash: Soft, warm voice
-    - ballad: Expressive, storytelling voice
-    - coral: Clear, friendly voice
-    - echo: Deep, resonant voice
-    - sage: Calm, wise voice
-    - shimmer: Bright, energetic voice
-    - verse: Dynamic, engaging voice
-    """
-    if set_current_voice(request.voice_id):
-        return VoiceResponse(
-            success=True,
-            current_voice=request.voice_id,
-            message=f"Voice set to {request.voice_id}",
-        )
-    else:
-        valid_voices = [v["id"] for v in OPENAI_VOICES]
-        return VoiceResponse(
-            success=False,
-            current_voice=_voice_settings.current_voice,
-            message=f"Invalid voice. Available: {', '.join(valid_voices)}",
-        )
-
-
-@router.get("/voice/info")
-async def get_voice_info() -> dict:
-    """Get detailed information about all available OpenAI voices."""
-    return {
-        "provider": "openai",
-        "voices": OPENAI_VOICES,
-        "current_voice": _voice_settings.current_voice,
-        "current_language": _voice_settings.current_language,
-        "note": "All OpenAI voices support any language. The language is set separately.",
-    }
-
-
-@router.post("/voice/language")
-async def set_language(language: str = "en") -> dict:
-    """Set the conversation language.
-    
-    This affects the system prompt for OpenAI Realtime.
-    All OpenAI voices natively support all languages.
-    """
-    set_current_language(language)
-    
-    return {
-        "success": True,
-        "language": language,
-        "message": f"Language set to {language}",
-    }
-
-
-@router.get("/voice/preferred-language")
-async def get_preferred_language_endpoint() -> dict:
-    """Get the user's preferred language setting.
-    
-    Returns the preferred language code and all supported languages.
-    """
-    return {
-        "preferred_language": _voice_settings.preferred_language,
-        "supported_languages": SUPPORTED_LANGUAGES,
-    }
-
-
-@router.post("/voice/preferred-language")
-async def set_preferred_language_endpoint(language: str = "en") -> dict:
-    """Set the user's preferred language.
-    
-    This sets both the preferred language and the current conversation language.
-    All OpenAI voices support all languages natively.
-    
-    Args:
-        language: Language code (e.g., 'en', 'nl', 'de', 'fr')
-    """
-    if set_preferred_language(language):
-        # Find language name for message
-        lang_info = next((l for l in SUPPORTED_LANGUAGES if l["code"] == language), None)
-        lang_name = lang_info["name"] if lang_info else language
-        
-        return {
-            "success": True,
-            "preferred_language": language,
-            "message": f"Preferred language set to {lang_name}",
-        }
-    else:
-        valid_codes = [l["code"] for l in SUPPORTED_LANGUAGES]
-        return {
-            "success": False,
-            "preferred_language": _voice_settings.preferred_language,
-            "message": f"Invalid language. Supported: {', '.join(valid_codes)}",
-        }
-
-
-# MARK: - Kids Mode Endpoints
-
-@router.get("/voice/kids-mode")
-async def get_kids_mode() -> dict:
-    """Get the current kids mode setting.
-    
-    Kids mode pitch-shifts Reachy's voice to sound younger/child-like.
-    
-    Returns:
-        kids_mode: Boolean indicating if kids mode is enabled.
-    """
-    return {
-        "kids_mode": _voice_settings.kids_mode,
-    }
-
-
-@router.post("/voice/kids-mode")
-async def set_kids_mode_endpoint(enabled: bool = False) -> dict:
-    """Enable or disable kids mode.
-    
-    Kids mode pitch-shifts Reachy's voice to sound younger/child-like.
-    This applies a pitch shift to the audio output making the voice
-    sound more suitable for conversations with children.
-    
-    Args:
-        enabled: True to enable kids mode, False to disable.
-        
-    Returns:
-        Success status and current kids mode state.
-    """
-    _voice_settings.set_kids_mode(enabled)
-    
-    return {
-        "success": True,
-        "kids_mode": enabled,
-        "message": f"Kids mode {'enabled' if enabled else 'disabled'}",
-    }
-
-
-# MARK: - VAD Settings Endpoints
-
-@router.get("/voice/vad-settings")
-async def get_vad_settings_endpoint() -> dict:
-    """Get the current VAD (Voice Activity Detection) settings.
-    
-    VAD settings control how Reachy detects when you're speaking:
-    - threshold: Sensitivity (0.0-1.0, higher = less sensitive to background noise)
-    - silence_ms: How long to wait after you stop speaking before responding
-    - prefix_ms: How much audio to buffer before speech is detected
-    
-    Returns:
-        Current VAD settings and available presets.
-    """
-    return {
-        "threshold": _voice_settings.vad_threshold,
-        "silence_ms": _voice_settings.vad_silence_ms,
-        "prefix_ms": _voice_settings.vad_prefix_ms,
-        "presets": list(VAD_PRESETS.values()),
-    }
-
-
-@router.post("/voice/vad-settings")
-async def set_vad_settings_endpoint(
-    threshold: Optional[float] = None,
-    silence_ms: Optional[int] = None,
-    prefix_ms: Optional[int] = None,
-) -> dict:
-    """Update VAD (Voice Activity Detection) settings.
-    
-    Adjust these settings to help Reachy work better in different environments:
-    
-    - In quiet rooms: Use lower threshold (0.5) and shorter silence (500ms)
-    - In noisy environments: Use higher threshold (0.85-0.9) and longer silence (1000-1200ms)
-    
-    Args:
-        threshold: Sensitivity 0.0-1.0 (higher = less sensitive to background)
-        silence_ms: Wait time before responding (200-3000ms)
-        prefix_ms: Audio buffer before speech (100-1000ms)
-        
-    Returns:
-        Success status and current settings.
-    """
-    success = _voice_settings.set_vad_settings(
-        threshold=threshold,
-        silence_ms=silence_ms,
-        prefix_ms=prefix_ms,
-    )
-    
-    if success:
-        return {
-            "success": True,
-            "threshold": _voice_settings.vad_threshold,
-            "silence_ms": _voice_settings.vad_silence_ms,
-            "prefix_ms": _voice_settings.vad_prefix_ms,
-            "message": "VAD settings updated",
-        }
-    else:
-        return {
-            "success": False,
-            "threshold": _voice_settings.vad_threshold,
-            "silence_ms": _voice_settings.vad_silence_ms,
-            "prefix_ms": _voice_settings.vad_prefix_ms,
-            "message": "Invalid values. threshold: 0.0-1.0, silence_ms: 200-3000, prefix_ms: 100-1000",
-        }
-
-
-@router.post("/voice/vad-preset")
-async def apply_vad_preset_endpoint(preset_id: str) -> dict:
-    """Apply a VAD preset for a specific environment.
-    
-    Available presets:
-    - quiet_room: More sensitive, faster responses (for quiet environments)
-    - normal: Balanced default settings
-    - noisy: Less sensitive, ignores background noise
-    - conference: Very strict, ignores most background voices
-    
-    Args:
-        preset_id: ID of the preset to apply.
-        
-    Returns:
-        Success status and applied settings.
-    """
-    if _voice_settings.apply_vad_preset(preset_id):
-        preset = VAD_PRESETS[preset_id]
-        return {
-            "success": True,
-            "preset": preset,
-            "threshold": _voice_settings.vad_threshold,
-            "silence_ms": _voice_settings.vad_silence_ms,
-            "prefix_ms": _voice_settings.vad_prefix_ms,
-            "message": f"Applied preset: {preset['name']}",
-        }
-    else:
-        return {
-            "success": False,
-            "available_presets": list(VAD_PRESETS.keys()),
-            "message": f"Unknown preset '{preset_id}'",
-        }
-
-
-@router.get("/voice/vad-presets")
-async def get_vad_presets_endpoint() -> dict:
-    """Get all available VAD presets.
-    
-    Returns:
-        List of available presets with their settings.
-    """
-    return {
-        "presets": list(VAD_PRESETS.values()),
-        "current_threshold": _voice_settings.vad_threshold,
-        "current_silence_ms": _voice_settings.vad_silence_ms,
-        "current_prefix_ms": _voice_settings.vad_prefix_ms,
-    }
-
-
-# Sample phrases by language for voice testing
-VOICE_SAMPLE_PHRASES = {
-    "en": {
-        "alloy": "Hello! I'm Alloy, a balanced and versatile voice.",
-        "ash": "Hi there. I'm Ash, with a soft and warm tone.",
-        "ballad": "Greetings! I'm Ballad, ready to tell you a story.",
-        "coral": "Hey! I'm Coral, clear and friendly!",
-        "echo": "Hello. I'm Echo, with a deep and resonant voice.",
-        "sage": "Welcome. I'm Sage, calm and thoughtful.",
-        "shimmer": "Hi! I'm Shimmer, bright and full of energy!",
-        "verse": "Hello! I'm Verse, dynamic and engaging.",
-    },
-    "nl": {
-        "alloy": "Hallo! Ik ben Alloy, een evenwichtige en veelzijdige stem.",
-        "ash": "Hoi! Ik ben Ash, met een zachte en warme toon.",
-        "ballad": "Goedendag! Ik ben Ballad, klaar om je een verhaal te vertellen.",
-        "coral": "Hey! Ik ben Coral, helder en vriendelijk!",
-        "echo": "Hallo. Ik ben Echo, met een diepe en resonante stem.",
-        "sage": "Welkom. Ik ben Sage, kalm en bedachtzaam.",
-        "shimmer": "Hoi! Ik ben Shimmer, vol energie!",
-        "verse": "Hallo! Ik ben Verse, dynamisch en boeiend.",
-    },
-    "de": {
-        "alloy": "Hallo! Ich bin Alloy, eine ausgewogene und vielseitige Stimme.",
-        "ash": "Hallo! Ich bin Ash, mit einem sanften und warmen Ton.",
-        "ballad": "Guten Tag! Ich bin Ballad, bereit dir eine Geschichte zu erzählen.",
-        "coral": "Hey! Ich bin Coral, klar und freundlich!",
-        "echo": "Hallo. Ich bin Echo, mit einer tiefen und resonanten Stimme.",
-        "sage": "Willkommen. Ich bin Sage, ruhig und nachdenklich.",
-        "shimmer": "Hallo! Ich bin Shimmer, voller Energie!",
-        "verse": "Hallo! Ich bin Verse, dynamisch und fesselnd.",
-    },
-    "fr": {
-        "alloy": "Bonjour! Je suis Alloy, une voix équilibrée et polyvalente.",
-        "ash": "Salut! Je suis Ash, avec un ton doux et chaleureux.",
-        "ballad": "Bonjour! Je suis Ballad, prêt à vous raconter une histoire.",
-        "coral": "Hey! Je suis Coral, claire et amicale!",
-        "echo": "Bonjour. Je suis Echo, avec une voix profonde et résonnante.",
-        "sage": "Bienvenue. Je suis Sage, calme et réfléchi.",
-        "shimmer": "Salut! Je suis Shimmer, pleine d'énergie!",
-        "verse": "Bonjour! Je suis Verse, dynamique et captivant.",
-    },
-    "es": {
-        "alloy": "¡Hola! Soy Alloy, una voz equilibrada y versátil.",
-        "ash": "¡Hola! Soy Ash, con un tono suave y cálido.",
-        "ballad": "¡Hola! Soy Ballad, listo para contarte una historia.",
-        "coral": "¡Hey! Soy Coral, clara y amigable!",
-        "echo": "Hola. Soy Echo, con una voz profunda y resonante.",
-        "sage": "Bienvenido. Soy Sage, tranquilo y reflexivo.",
-        "shimmer": "¡Hola! Soy Shimmer, llena de energía!",
-        "verse": "¡Hola! Soy Verse, dinámico y cautivador.",
-    },
-    "it": {
-        "alloy": "Ciao! Sono Alloy, una voce equilibrata e versatile.",
-        "ash": "Ciao! Sono Ash, con un tono morbido e caldo.",
-        "ballad": "Salve! Sono Ballad, pronto a raccontarti una storia.",
-        "coral": "Hey! Sono Coral, chiara e amichevole!",
-        "echo": "Ciao. Sono Echo, con una voce profonda e risonante.",
-        "sage": "Benvenuto. Sono Sage, calmo e riflessivo.",
-        "shimmer": "Ciao! Sono Shimmer, piena di energia!",
-        "verse": "Ciao! Sono Verse, dinamico e coinvolgente.",
-    },
-    "pt": {
-        "alloy": "Olá! Eu sou Alloy, uma voz equilibrada e versátil.",
-        "ash": "Oi! Eu sou Ash, com um tom suave e caloroso.",
-        "ballad": "Olá! Eu sou Ballad, pronto para contar uma história.",
-        "coral": "Hey! Eu sou Coral, clara e amigável!",
-        "echo": "Olá. Eu sou Echo, com uma voz profunda e ressonante.",
-        "sage": "Bem-vindo. Eu sou Sage, calmo e reflexivo.",
-        "shimmer": "Oi! Eu sou Shimmer, cheia de energia!",
-        "verse": "Olá! Eu sou Verse, dinâmico e envolvente.",
-    },
-    "ja": {
-        "alloy": "こんにちは！私はAlloyです。バランスの取れた多用途な声です。",
-        "ash": "こんにちは！私はAshです。柔らかく温かみのある声です。",
-        "ballad": "こんにちは！私はBalladです。物語を語る準備ができています。",
-        "coral": "ハイ！私はCoralです。明るくフレンドリーな声です！",
-        "echo": "こんにちは。私はEchoです。深く響く声です。",
-        "sage": "ようこそ。私はSageです。穏やかで思慮深い声です。",
-        "shimmer": "こんにちは！私はShimmerです。エネルギッシュな声です！",
-        "verse": "こんにちは！私はVerseです。ダイナミックで魅力的な声です。",
-    },
-    "ko": {
-        "alloy": "안녕하세요! 저는 Alloy입니다. 균형 잡힌 다재다능한 목소리예요.",
-        "ash": "안녕하세요! 저는 Ash입니다. 부드럽고 따뜻한 톤이에요.",
-        "ballad": "안녕하세요! 저는 Ballad입니다. 이야기를 들려드릴 준비가 됐어요.",
-        "coral": "안녕! 저는 Coral이에요. 맑고 친근한 목소리예요!",
-        "echo": "안녕하세요. 저는 Echo입니다. 깊고 울림 있는 목소리예요.",
-        "sage": "환영합니다. 저는 Sage입니다. 차분하고 사려 깊은 목소리예요.",
-        "shimmer": "안녕하세요! 저는 Shimmer예요. 활기찬 목소리예요!",
-        "verse": "안녕하세요! 저는 Verse입니다. 역동적이고 매력적인 목소리예요.",
-    },
-    "zh": {
-        "alloy": "你好！我是Alloy，一个平衡且多功能的声音。",
-        "ash": "你好！我是Ash，声音柔和温暖。",
-        "ballad": "你好！我是Ballad，准备给你讲故事。",
-        "coral": "嗨！我是Coral，清晰又友好！",
-        "echo": "你好。我是Echo，声音深沉有共鸣。",
-        "sage": "欢迎。我是Sage，冷静而深思熟虑。",
-        "shimmer": "你好！我是Shimmer，充满活力！",
-        "verse": "你好！我是Verse，充满活力和魅力。",
-    },
-}
-
-
-def _get_voice_sample_phrase(voice: str, language: str) -> str:
-    """Get a sample phrase for voice testing in the specified language.
-    
-    Args:
-        voice: Voice ID (e.g., 'alloy', 'coral')
-        language: Language code (e.g., 'en', 'nl', 'de')
-    
-    Returns:
-        Sample phrase in the specified language.
-    """
-    # Get phrases for the language, fallback to English
-    phrases = VOICE_SAMPLE_PHRASES.get(language, VOICE_SAMPLE_PHRASES["en"])
-    return phrases.get(voice, phrases.get("alloy", f"Hello! I'm testing the {voice} voice."))
-
-
-@router.post("/voice/test")
-async def test_voice(request: Optional[VoiceRequest] = None) -> dict:
-    """Test an OpenAI voice by playing a sample phrase.
-    
-    Uses OpenAI's TTS API to generate audio with the specified voice,
-    then plays it through Reachy's speaker in the user's preferred language.
-    
-    Args:
-        request: VoiceRequest with voice_id to test. If not provided, uses current voice.
-        
-    Returns:
-        Success status and message.
-    """
-    # Get API key from environment
-    api_key = os.environ.get("OPENAI_API_KEY")
-    if not api_key:
-        raise HTTPException(
-            status_code=503, 
-            detail="OpenAI API key not set. Start a conversation first or configure the API key in Settings."
-        )
-    
-    # Use provided voice or current voice
-    voice = (request.voice_id if request else None) or _voice_settings.current_voice
-    
-    # Validate voice
-    valid_ids = [v["id"] for v in OPENAI_VOICES]
-    if voice not in valid_ids:
-        raise HTTPException(
-            status_code=400, 
-            detail=f"Invalid voice '{voice}'. Available: {', '.join(valid_ids)}"
-        )
-    
-    # TTS API supports different voices than Realtime API
-    # Map Realtime-only voices to similar TTS voices for preview
-    TTS_VOICE_MAP = {
-        "alloy": "alloy",
-        "ash": "ash", 
-        "ballad": "fable",    # ballad -> fable (expressive, storytelling)
-        "coral": "coral",
-        "echo": "echo",
-        "sage": "sage",
-        "shimmer": "shimmer",
-        "verse": "nova",      # verse -> nova (dynamic, engaging)
-    }
-    
-    tts_voice = TTS_VOICE_MAP.get(voice, "alloy")
-    is_mapped = tts_voice != voice
-    
-    # Get sample phrase in user's preferred language
-    language = _voice_settings.preferred_language
-    sample_text = _get_voice_sample_phrase(voice, language)
-    
-    logger.info(f"🎤 Testing voice '{voice}' (TTS: {tts_voice}) with OpenAI TTS API")
-    
-    try:
-        # Call OpenAI TTS API
-        async with httpx.AsyncClient() as client:
-            response = await client.post(
-                OPENAI_TTS_URL,
-                headers={
-                    "Authorization": f"Bearer {api_key}",
-                    "Content-Type": "application/json",
-                },
-                json={
-                    "model": "tts-1",
-                    "input": sample_text,
-                    "voice": tts_voice,  # Use mapped TTS voice
-                    "response_format": "pcm",  # Raw PCM for direct playback
-                },
-                timeout=30.0,
-            )
-            
-            if response.status_code != 200:
-                error_detail = response.text
-                logger.error(f"OpenAI TTS API error: {response.status_code} - {error_detail}")
-                raise HTTPException(
-                    status_code=response.status_code,
-                    detail=f"OpenAI TTS error: {error_detail}"
-                )
-            
-            audio_data = response.content
-            logger.info(f"✅ Received {len(audio_data)} bytes of audio from OpenAI")
-        
-        # Play audio using aplay (OpenAI TTS PCM is 24kHz 16-bit mono)
-        await _play_pcm_audio(audio_data)
-        
-        logger.info(f"✅ Voice test complete for '{voice}' (TTS: {tts_voice})")
-        
-        message = f"Played sample for {voice}"
-        if is_mapped:
-            message += f" (preview uses {tts_voice})"
-        
-        return {
-            "success": True,
-            "voice": voice,
-            "tts_voice": tts_voice,
-            "message": message,
-        }
-        
-    except httpx.TimeoutException:
-        logger.error("OpenAI TTS API timeout")
-        raise HTTPException(status_code=504, detail="OpenAI TTS API timeout")
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Error testing voice: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-async def _play_pcm_audio(audio_data: bytes) -> None:
-    """Play PCM audio data through Reachy's speaker.
-    
-    Applies pitch shifting if kids mode is enabled.
-    
-    Args:
-        audio_data: Raw PCM16 audio at 24kHz mono.
-    """
-    import shutil
-    
-    # Check if kids mode is enabled
-    use_pitch_shift = is_kids_mode_enabled() and shutil.which("sox") is not None
-    
-    if is_kids_mode_enabled() and not shutil.which("sox"):
-        logger.warning("🧒 Kids mode enabled but sox not found, using normal playback")
-    
-    # OpenAI TTS PCM format: 24kHz, 16-bit signed little-endian, mono
-    aplay_cmd = [
-        "aplay",
-        "-r", "24000",
-        "-f", "S16_LE",
-        "-t", "raw",
-        "-c", "1",
-        "-D", AUDIO_DEVICE,
-        "-q",
-    ]
-    
-    loop = asyncio.get_event_loop()
-    
-    def _run_playback():
-        if use_pitch_shift:
-            # Pitch shift with sox, then pipe to aplay
-            # Sox command: read raw PCM, pitch shift, output raw PCM
-            sox_cmd = [
-                "sox",
-                "-t", "raw",
-                "-r", "24000",
-                "-e", "signed",
-                "-b", "16",
-                "-c", "1",
-                "-",  # Input from stdin
-                "-t", "raw",
-                "-",  # Output to stdout
-                "pitch", str(KIDS_MODE_PITCH_CENTS),
-                "tempo", str(KIDS_MODE_TEMPO),
-            ]
-            
-            # Create sox process
-            sox_process = subprocess.Popen(
-                sox_cmd,
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-            )
-            
-            # Create aplay process reading from sox output
-            aplay_process = subprocess.Popen(
-                aplay_cmd,
-                stdin=sox_process.stdout,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-            )
-            
-            # Close sox stdout in parent
-            sox_process.stdout.close()
-            
-            # Write audio to sox
-            sox_process.stdin.write(audio_data)
-            sox_process.stdin.close()
-            
-            # Wait for both processes
-            sox_process.wait(timeout=30)
-            aplay_process.wait(timeout=30)
-            
-            logger.info("🧒 Played audio with kids mode pitch shift")
-        else:
-            # Normal playback without pitch shifting
-            process = subprocess.Popen(
-                aplay_cmd,
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-            )
-            stdout, stderr = process.communicate(input=audio_data, timeout=30)
-            if process.returncode != 0:
-                error_msg = stderr.decode() if stderr else "Unknown error"
-                raise RuntimeError(f"aplay failed: {error_msg}")
-    
-    await loop.run_in_executor(None, _run_playback)

reachys_brain/routes/voice/__init__.py

@@ -0,0 +1,70 @@
+"""Voice settings management for the iOS Bridge.
+
+This package provides voice, language, and VAD configuration:
+- constants: Voice definitions, languages, and database keys
+- settings: VoiceSettings class with database persistence
+- vad: VAD presets for different environments
+- samples: Voice sample phrases for testing
+- playback: Audio playback utilities
+- endpoints: FastAPI REST endpoints
+"""
+
+from .constants import (
+    OPENAI_VOICES,
+    SUPPORTED_LANGUAGES,
+)
+from .settings import (
+    VoiceSettings,
+    get_voice_settings,
+    init_voice_settings,
+    get_current_voice,
+    set_current_voice,
+    get_preferred_language,
+    set_preferred_language,
+    get_kids_mode_enabled,
+    set_kids_mode_enabled,
+    get_vad_threshold,
+    get_vad_silence_ms,
+    get_vad_prefix_ms,
+    set_vad_settings_callback,
+)
+from .vad import VAD_PRESETS
+from .samples import get_voice_sample_phrase
+from .endpoints import router
+
+__all__ = [
+    # Router
+    "router",
+    
+    # Constants
+    "OPENAI_VOICES",
+    "SUPPORTED_LANGUAGES",
+    "VAD_PRESETS",
+    
+    # Settings class
+    "VoiceSettings",
+    "get_voice_settings",
+    "init_voice_settings",
+    
+    # Voice functions
+    "get_current_voice",
+    "set_current_voice",
+    
+    # Language functions
+    "get_preferred_language",
+    "set_preferred_language",
+    
+    # Kids mode functions
+    "get_kids_mode_enabled",
+    "set_kids_mode_enabled",
+    
+    # VAD functions
+    "get_vad_threshold",
+    "get_vad_silence_ms",
+    "get_vad_prefix_ms",
+    "set_vad_settings_callback",
+    
+    # Sample utilities
+    "get_voice_sample_phrase",
+]
+

reachys_brain/routes/voice/constants.py

@@ -0,0 +1,101 @@
+"""Constants for voice configuration.
+
+Contains OpenAI voice definitions, supported languages, and database keys.
+"""
+
+# Database keys for voice settings
+VOICE_ID_KEY = "voice_id"
+PREFERRED_LANGUAGE_KEY = "preferred_language"
+KIDS_MODE_KEY = "kids_mode_enabled"
+
+# Database keys for VAD (Voice Activity Detection) settings
+VAD_THRESHOLD_KEY = "vad_threshold"
+VAD_SILENCE_MS_KEY = "vad_silence_ms"
+VAD_PREFIX_MS_KEY = "vad_prefix_ms"
+
+# Default VAD values
+DEFAULT_VAD_THRESHOLD = 0.8
+DEFAULT_VAD_SILENCE_MS = 800
+DEFAULT_VAD_PREFIX_MS = 300
+
+# OpenAI TTS API endpoint
+OPENAI_TTS_URL = "https://api.openai.com/v1/audio/speech"
+
+# Reachy audio device
+AUDIO_DEVICE = "plug:reachymini_audio_sink"
+
+# Available OpenAI Realtime voices with their characteristics
+OPENAI_VOICES = [
+    {
+        "id": "alloy",
+        "name": "Alloy",
+        "description": "Neutral, balanced voice",
+        "gender": "neutral",
+    },
+    {
+        "id": "ash",
+        "name": "Ash",
+        "description": "Soft, warm voice",
+        "gender": "male",
+    },
+    {
+        "id": "ballad",
+        "name": "Ballad",
+        "description": "Expressive, storytelling voice",
+        "gender": "male",
+    },
+    {
+        "id": "coral",
+        "name": "Coral",
+        "description": "Clear, friendly voice",
+        "gender": "female",
+    },
+    {
+        "id": "echo",
+        "name": "Echo",
+        "description": "Deep, resonant voice",
+        "gender": "male",
+    },
+    {
+        "id": "sage",
+        "name": "Sage",
+        "description": "Calm, wise voice",
+        "gender": "female",
+    },
+    {
+        "id": "shimmer",
+        "name": "Shimmer",
+        "description": "Bright, energetic voice",
+        "gender": "female",
+    },
+    {
+        "id": "verse",
+        "name": "Verse",
+        "description": "Dynamic, engaging voice",
+        "gender": "male",
+    },
+]
+
+# Supported languages with display names
+SUPPORTED_LANGUAGES = [
+    {"code": "en", "name": "English", "flag": "🇺🇸"},
+    {"code": "nl", "name": "Dutch", "flag": "🇳🇱"},
+    {"code": "de", "name": "German", "flag": "🇩🇪"},
+    {"code": "fr", "name": "French", "flag": "🇫🇷"},
+    {"code": "es", "name": "Spanish", "flag": "🇪🇸"},
+    {"code": "it", "name": "Italian", "flag": "🇮🇹"},
+    {"code": "pt", "name": "Portuguese", "flag": "🇵🇹"},
+    {"code": "ja", "name": "Japanese", "flag": "🇯🇵"},
+    {"code": "ko", "name": "Korean", "flag": "🇰🇷"},
+    {"code": "zh", "name": "Chinese", "flag": "🇨🇳"},
+    {"code": "ar", "name": "Arabic", "flag": "🇸🇦"},
+    {"code": "hi", "name": "Hindi", "flag": "🇮🇳"},
+    {"code": "ru", "name": "Russian", "flag": "🇷🇺"},
+    {"code": "pl", "name": "Polish", "flag": "🇵🇱"},
+    {"code": "tr", "name": "Turkish", "flag": "🇹🇷"},
+    {"code": "sv", "name": "Swedish", "flag": "🇸🇪"},
+    {"code": "da", "name": "Danish", "flag": "🇩🇰"},
+    {"code": "no", "name": "Norwegian", "flag": "🇳🇴"},
+    {"code": "fi", "name": "Finnish", "flag": "🇫🇮"},
+]
+

reachys_brain/routes/voice/endpoints.py

@@ -0,0 +1,250 @@
+"""FastAPI endpoints for voice settings.
+
+Provides REST API endpoints for managing voice, language, and VAD settings.
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from .constants import OPENAI_VOICES, SUPPORTED_LANGUAGES
+from .vad import VAD_PRESETS
+from .samples import get_voice_sample_phrase
+from .settings import (
+    get_voice_settings,
+    get_current_voice,
+    set_current_voice,
+    get_preferred_language,
+    set_preferred_language,
+    get_kids_mode_enabled,
+    set_kids_mode_enabled,
+)
+from .playback import test_voice
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/voice", tags=["Voice"])
+
+
+# MARK: - Request/Response Models
+
+class SetVoiceRequest(BaseModel):
+    """Request to set the OpenAI voice."""
+    voice_id: str
+
+
+class SetVoiceResponse(BaseModel):
+    """Response from setting the voice."""
+    success: bool
+    voice_id: str
+
+
+class SetLanguageRequest(BaseModel):
+    """Request to set preferred language."""
+    language: str
+
+
+class SetLanguageResponse(BaseModel):
+    """Response from setting language."""
+    success: bool
+    language: str
+
+
+class TestVoiceRequest(BaseModel):
+    """Request to test a voice with sample text."""
+    voice_id: str
+    language: str = "en"
+    pitch_shift: float = 0
+
+
+class TestVoiceResponse(BaseModel):
+    """Response from voice test."""
+    success: bool
+    voice_id: str
+    language: str
+
+
+class SetKidsModeRequest(BaseModel):
+    """Request to set kids mode."""
+    enabled: bool
+
+
+class SetKidsModeResponse(BaseModel):
+    """Response from setting kids mode."""
+    success: bool
+    enabled: bool
+
+
+class VADSettingsRequest(BaseModel):
+    """Request to set VAD settings."""
+    threshold: Optional[float] = None
+    silence_ms: Optional[int] = None
+    prefix_ms: Optional[int] = None
+
+
+class VADSettingsResponse(BaseModel):
+    """Response with current VAD settings."""
+    threshold: float
+    silence_ms: int
+    prefix_ms: int
+
+
+# MARK: - Voice Endpoints
+
+@router.get("/voices")
+async def get_voices():
+    """Get available OpenAI voices."""
+    current_voice = get_current_voice()
+    return {
+        "voices": OPENAI_VOICES,
+        "current_voice": current_voice,
+    }
+
+
+@router.get("/current")
+async def get_current_voice_endpoint():
+    """Get the current voice ID."""
+    return {
+        "voice_id": get_current_voice(),
+    }
+
+
+@router.post("/set", response_model=SetVoiceResponse)
+async def set_voice(request: SetVoiceRequest):
+    """Set the OpenAI voice."""
+    success = set_current_voice(request.voice_id)
+    if not success:
+        raise HTTPException(status_code=400, detail=f"Invalid voice ID: {request.voice_id}")
+    
+    return SetVoiceResponse(success=True, voice_id=request.voice_id)
+
+
+@router.post("/test", response_model=TestVoiceResponse)
+async def test_voice_endpoint(request: TestVoiceRequest):
+    """Test a voice by playing a sample phrase."""
+    # Validate voice ID
+    valid_voices = [v["id"] for v in OPENAI_VOICES]
+    if request.voice_id not in valid_voices:
+        raise HTTPException(status_code=400, detail=f"Invalid voice ID: {request.voice_id}")
+    
+    # Get sample phrase
+    text = get_voice_sample_phrase(request.voice_id, request.language)
+    
+    # Test the voice
+    success = await test_voice(request.voice_id, text, request.pitch_shift)
+    
+    return TestVoiceResponse(
+        success=success,
+        voice_id=request.voice_id,
+        language=request.language,
+    )
+
+
+# MARK: - Language Endpoints
+
+@router.get("/languages")
+async def get_languages():
+    """Get supported languages."""
+    current_language = get_preferred_language()
+    return {
+        "languages": SUPPORTED_LANGUAGES,
+        "current_language": current_language,
+    }
+
+
+@router.get("/language")
+async def get_language_endpoint():
+    """Get the current preferred language."""
+    return {
+        "language": get_preferred_language(),
+    }
+
+
+@router.post("/language", response_model=SetLanguageResponse)
+async def set_language_endpoint(request: SetLanguageRequest):
+    """Set the preferred language."""
+    success = set_preferred_language(request.language)
+    if not success:
+        raise HTTPException(status_code=400, detail=f"Invalid language: {request.language}")
+    
+    return SetLanguageResponse(success=True, language=request.language)
+
+
+# MARK: - Kids Mode Endpoints
+
+@router.get("/kids-mode")
+async def get_kids_mode():
+    """Get kids mode status."""
+    return {
+        "enabled": get_kids_mode_enabled(),
+    }
+
+
+@router.post("/kids-mode", response_model=SetKidsModeResponse)
+async def set_kids_mode_endpoint(request: SetKidsModeRequest):
+    """Set kids mode enabled/disabled."""
+    set_kids_mode_enabled(request.enabled)
+    
+    return SetKidsModeResponse(success=True, enabled=request.enabled)
+
+
+# MARK: - VAD Endpoints
+
+@router.get("/vad/settings", response_model=VADSettingsResponse)
+async def get_vad_settings():
+    """Get current VAD settings."""
+    settings = get_voice_settings()
+    return VADSettingsResponse(
+        threshold=settings.vad_threshold,
+        silence_ms=settings.vad_silence_ms,
+        prefix_ms=settings.vad_prefix_ms,
+    )
+
+
+@router.post("/vad/settings", response_model=VADSettingsResponse)
+async def set_vad_settings(request: VADSettingsRequest):
+    """Set VAD settings."""
+    settings = get_voice_settings()
+    settings.set_vad_settings(
+        threshold=request.threshold,
+        silence_ms=request.silence_ms,
+        prefix_ms=request.prefix_ms,
+    )
+    
+    return VADSettingsResponse(
+        threshold=settings.vad_threshold,
+        silence_ms=settings.vad_silence_ms,
+        prefix_ms=settings.vad_prefix_ms,
+    )
+
+
+@router.get("/vad/presets")
+async def get_vad_presets():
+    """Get available VAD presets."""
+    return {
+        "presets": list(VAD_PRESETS.values()),
+    }
+
+
+@router.post("/vad/preset/{preset_id}", response_model=VADSettingsResponse)
+async def apply_vad_preset(preset_id: str):
+    """Apply a VAD preset."""
+    preset = VAD_PRESETS.get(preset_id)
+    if not preset:
+        raise HTTPException(status_code=404, detail=f"Unknown preset: {preset_id}")
+    
+    settings = get_voice_settings()
+    settings.set_vad_settings(
+        threshold=preset["threshold"],
+        silence_ms=preset["silence_ms"],
+        prefix_ms=preset["prefix_ms"],
+    )
+    
+    return VADSettingsResponse(
+        threshold=settings.vad_threshold,
+        silence_ms=settings.vad_silence_ms,
+        prefix_ms=settings.vad_prefix_ms,
+    )
+

reachys_brain/routes/voice/playback.py

@@ -0,0 +1,192 @@
+"""Audio playback utilities for voice testing.
+
+Provides functions for playing audio samples through Reachy's speakers.
+"""
+
+import asyncio
+import logging
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+from .constants import OPENAI_TTS_URL, AUDIO_DEVICE
+
+logger = logging.getLogger(__name__)
+
+
+async def generate_voice_sample(voice: str, text: str) -> Optional[bytes]:
+    """Generate a voice sample using OpenAI TTS API.
+    
+    Args:
+        voice: Voice ID (e.g., 'alloy', 'coral').
+        text: Text to speak.
+        
+    Returns:
+        Audio data as bytes, or None on failure.
+    """
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        logger.error("OPENAI_API_KEY not set")
+        return None
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                OPENAI_TTS_URL,
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": "tts-1",
+                    "voice": voice,
+                    "input": text,
+                    "response_format": "mp3",
+                },
+                timeout=30.0,
+            )
+            
+            if response.status_code == 200:
+                return response.content
+            else:
+                logger.error(f"TTS API error: {response.status_code} - {response.text}")
+                return None
+    
+    except Exception as e:
+        logger.error(f"Error generating voice sample: {e}")
+        return None
+
+
+def apply_pitch_shift(audio_data: bytes, semitones: float) -> Optional[bytes]:
+    """Apply pitch shift to audio data.
+    
+    Uses sox to shift pitch. Positive semitones = higher pitch.
+    
+    Args:
+        audio_data: MP3 audio data.
+        semitones: Number of semitones to shift (positive = higher).
+        
+    Returns:
+        Pitch-shifted audio data, or None on failure.
+    """
+    if semitones == 0:
+        return audio_data
+    
+    try:
+        # Create temp files for sox processing
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as in_file:
+            in_file.write(audio_data)
+            in_path = in_file.name
+        
+        out_path = in_path.replace(".mp3", "_shifted.mp3")
+        
+        # Calculate pitch ratio (semitones to ratio)
+        # 12 semitones = 2x frequency
+        pitch_ratio = 2 ** (semitones / 12)
+        
+        # Run sox with pitch shift
+        result = subprocess.run(
+            ["sox", in_path, out_path, "pitch", str(int(semitones * 100))],
+            capture_output=True,
+            timeout=10,
+        )
+        
+        if result.returncode != 0:
+            logger.error(f"sox pitch shift failed: {result.stderr.decode()}")
+            os.unlink(in_path)
+            return None
+        
+        # Read output file
+        with open(out_path, "rb") as f:
+            shifted_audio = f.read()
+        
+        # Cleanup temp files
+        os.unlink(in_path)
+        os.unlink(out_path)
+        
+        return shifted_audio
+    
+    except FileNotFoundError:
+        logger.warning("sox not found - skipping pitch shift")
+        return audio_data
+    except subprocess.TimeoutExpired:
+        logger.error("sox pitch shift timed out")
+        return None
+    except Exception as e:
+        logger.error(f"Error applying pitch shift: {e}")
+        return None
+
+
+async def play_audio_on_reachy(audio_data: bytes) -> bool:
+    """Play audio through Reachy's speakers.
+    
+    Args:
+        audio_data: MP3 audio data to play.
+        
+    Returns:
+        True if playback succeeded.
+    """
+    try:
+        # Write to temp file
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
+            f.write(audio_data)
+            audio_path = f.name
+        
+        try:
+            # Play using aplay with Reachy's audio device
+            process = await asyncio.create_subprocess_exec(
+                "mpv",
+                "--no-video",
+                f"--audio-device=alsa/{AUDIO_DEVICE}",
+                audio_path,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+            await asyncio.wait_for(process.wait(), timeout=30.0)
+            return process.returncode == 0
+        finally:
+            # Cleanup temp file
+            os.unlink(audio_path)
+    
+    except asyncio.TimeoutError:
+        logger.error("Audio playback timed out")
+        return False
+    except FileNotFoundError:
+        logger.error("mpv not found - cannot play audio")
+        return False
+    except Exception as e:
+        logger.error(f"Error playing audio: {e}")
+        return False
+
+
+async def test_voice(voice: str, text: str, pitch_shift: float = 0) -> bool:
+    """Test a voice by generating and playing a sample.
+    
+    Args:
+        voice: Voice ID to test.
+        text: Text to speak.
+        pitch_shift: Optional pitch shift in semitones.
+        
+    Returns:
+        True if test succeeded.
+    """
+    logger.info(f"🔊 Testing voice: {voice} (pitch: {pitch_shift})")
+    
+    # Generate audio
+    audio_data = await generate_voice_sample(voice, text)
+    if not audio_data:
+        return False
+    
+    # Apply pitch shift if needed
+    if pitch_shift != 0:
+        audio_data = apply_pitch_shift(audio_data, pitch_shift)
+        if not audio_data:
+            return False
+    
+    # Play on Reachy
+    return await play_audio_on_reachy(audio_data)
+

reachys_brain/routes/voice/samples.py

@@ -0,0 +1,123 @@
+"""Voice sample phrases for testing voices.
+
+Contains sample phrases in multiple languages for voice testing.
+"""
+
+# Sample phrases by language for voice testing
+VOICE_SAMPLE_PHRASES = {
+    "en": {
+        "alloy": "Hello! I'm Alloy, a balanced and versatile voice.",
+        "ash": "Hi there. I'm Ash, with a soft and warm tone.",
+        "ballad": "Greetings! I'm Ballad, ready to tell you a story.",
+        "coral": "Hey! I'm Coral, clear and friendly!",
+        "echo": "Hello. I'm Echo, with a deep and resonant voice.",
+        "sage": "Welcome. I'm Sage, calm and thoughtful.",
+        "shimmer": "Hi! I'm Shimmer, bright and full of energy!",
+        "verse": "Hello! I'm Verse, dynamic and engaging.",
+    },
+    "nl": {
+        "alloy": "Hallo! Ik ben Alloy, een evenwichtige en veelzijdige stem.",
+        "ash": "Hoi! Ik ben Ash, met een zachte en warme toon.",
+        "ballad": "Goedendag! Ik ben Ballad, klaar om je een verhaal te vertellen.",
+        "coral": "Hey! Ik ben Coral, helder en vriendelijk!",
+        "echo": "Hallo. Ik ben Echo, met een diepe en resonante stem.",
+        "sage": "Welkom. Ik ben Sage, kalm en bedachtzaam.",
+        "shimmer": "Hoi! Ik ben Shimmer, vol energie!",
+        "verse": "Hallo! Ik ben Verse, dynamisch en boeiend.",
+    },
+    "de": {
+        "alloy": "Hallo! Ich bin Alloy, eine ausgewogene und vielseitige Stimme.",
+        "ash": "Hallo! Ich bin Ash, mit einem sanften und warmen Ton.",
+        "ballad": "Guten Tag! Ich bin Ballad, bereit dir eine Geschichte zu erzählen.",
+        "coral": "Hey! Ich bin Coral, klar und freundlich!",
+        "echo": "Hallo. Ich bin Echo, mit einer tiefen und resonanten Stimme.",
+        "sage": "Willkommen. Ich bin Sage, ruhig und nachdenklich.",
+        "shimmer": "Hallo! Ich bin Shimmer, voller Energie!",
+        "verse": "Hallo! Ich bin Verse, dynamisch und fesselnd.",
+    },
+    "fr": {
+        "alloy": "Bonjour! Je suis Alloy, une voix équilibrée et polyvalente.",
+        "ash": "Salut! Je suis Ash, avec un ton doux et chaleureux.",
+        "ballad": "Bonjour! Je suis Ballad, prêt à vous raconter une histoire.",
+        "coral": "Hey! Je suis Coral, claire et amicale!",
+        "echo": "Bonjour. Je suis Echo, avec une voix profonde et résonnante.",
+        "sage": "Bienvenue. Je suis Sage, calme et réfléchi.",
+        "shimmer": "Salut! Je suis Shimmer, pleine d'énergie!",
+        "verse": "Bonjour! Je suis Verse, dynamique et captivant.",
+    },
+    "es": {
+        "alloy": "¡Hola! Soy Alloy, una voz equilibrada y versátil.",
+        "ash": "¡Hola! Soy Ash, con un tono suave y cálido.",
+        "ballad": "¡Hola! Soy Ballad, listo para contarte una historia.",
+        "coral": "¡Hey! Soy Coral, clara y amigable!",
+        "echo": "Hola. Soy Echo, con una voz profunda y resonante.",
+        "sage": "Bienvenido. Soy Sage, tranquilo y reflexivo.",
+        "shimmer": "¡Hola! Soy Shimmer, llena de energía!",
+        "verse": "¡Hola! Soy Verse, dinámico y cautivador.",
+    },
+    "it": {
+        "alloy": "Ciao! Sono Alloy, una voce equilibrata e versatile.",
+        "ash": "Ciao! Sono Ash, con un tono morbido e caldo.",
+        "ballad": "Salve! Sono Ballad, pronto a raccontarti una storia.",
+        "coral": "Hey! Sono Coral, chiara e amichevole!",
+        "echo": "Ciao. Sono Echo, con una voce profonda e risonante.",
+        "sage": "Benvenuto. Sono Sage, calmo e riflessivo.",
+        "shimmer": "Ciao! Sono Shimmer, piena di energia!",
+        "verse": "Ciao! Sono Verse, dinamico e coinvolgente.",
+    },
+    "pt": {
+        "alloy": "Olá! Eu sou Alloy, uma voz equilibrada e versátil.",
+        "ash": "Oi! Eu sou Ash, com um tom suave e caloroso.",
+        "ballad": "Olá! Eu sou Ballad, pronto para contar uma história.",
+        "coral": "Hey! Eu sou Coral, clara e amigável!",
+        "echo": "Olá. Eu sou Echo, com uma voz profunda e ressonante.",
+        "sage": "Bem-vindo. Eu sou Sage, calmo e reflexivo.",
+        "shimmer": "Oi! Eu sou Shimmer, cheia de energia!",
+        "verse": "Olá! Eu sou Verse, dinâmico e envolvente.",
+    },
+    "ja": {
+        "alloy": "こんにちは！私はAlloyです。バランスの取れた多用途な声です。",
+        "ash": "こんにちは！私はAshです。柔らかく温かみのある声です。",
+        "ballad": "こんにちは！私はBalladです。物語を語る準備ができています。",
+        "coral": "ハイ！私はCoralです。明るくフレンドリーな声です！",
+        "echo": "こんにちは。私はEchoです。深く響く声です。",
+        "sage": "ようこそ。私はSageです。穏やかで思慮深い声です。",
+        "shimmer": "こんにちは！私はShimmerです。エネルギッシュな声です！",
+        "verse": "こんにちは！私はVerseです。ダイナミックで魅力的な声です。",
+    },
+    "ko": {
+        "alloy": "안녕하세요! 저는 Alloy입니다. 균형 잡힌 다재다능한 목소리���요.",
+        "ash": "안녕하세요! 저는 Ash입니다. 부드럽고 따뜻한 톤이에요.",
+        "ballad": "안녕하세요! 저는 Ballad입니다. 이야기를 들려드릴 준비가 됐어요.",
+        "coral": "안녕! 저는 Coral이에요. 맑고 친근한 목소리예요!",
+        "echo": "안녕하세요. 저는 Echo입니다. 깊고 울림 있는 목소리예요.",
+        "sage": "환영합니다. 저는 Sage입니다. 차분하고 사려 깊은 목소리예요.",
+        "shimmer": "안녕하세요! 저는 Shimmer예요. 활기찬 목소리예요!",
+        "verse": "안녕하세요! 저는 Verse입니다. 역동적이고 매력적인 목소리예요.",
+    },
+    "zh": {
+        "alloy": "你好！我是Alloy，一个平衡且多功能的声音。",
+        "ash": "你好！我是Ash，声音柔和温暖。",
+        "ballad": "你好！我是Ballad，准备给你讲故事。",
+        "coral": "嗨！我是Coral，清晰又友好！",
+        "echo": "你好。我是Echo，声音深沉有共鸣。",
+        "sage": "欢迎。我是Sage，冷静而深思熟虑。",
+        "shimmer": "你好！我是Shimmer，充满活力！",
+        "verse": "你好！我是Verse，充满活力和魅力。",
+    },
+}
+
+
+def get_voice_sample_phrase(voice: str, language: str) -> str:
+    """Get a sample phrase for voice testing in the specified language.
+    
+    Args:
+        voice: Voice ID (e.g., 'alloy', 'coral')
+        language: Language code (e.g., 'en', 'nl', 'de')
+    
+    Returns:
+        Sample phrase in the specified language.
+    """
+    phrases = VOICE_SAMPLE_PHRASES.get(language, VOICE_SAMPLE_PHRASES["en"])
+    return phrases.get(voice, phrases.get("alloy", f"Hello! I'm testing the {voice} voice."))
+

reachys_brain/routes/voice/settings.py

@@ -0,0 +1,344 @@
+"""Voice settings management.
+
+Provides the VoiceSettings class for managing voice configuration including
+voice selection, language, kids mode, and VAD settings.
+"""
+
+import asyncio
+import logging
+from typing import Callable, Optional
+
+from ...database import get_database
+from .constants import (
+    VOICE_ID_KEY,
+    PREFERRED_LANGUAGE_KEY,
+    KIDS_MODE_KEY,
+    VAD_THRESHOLD_KEY,
+    VAD_SILENCE_MS_KEY,
+    VAD_PREFIX_MS_KEY,
+    DEFAULT_VAD_THRESHOLD,
+    DEFAULT_VAD_SILENCE_MS,
+    DEFAULT_VAD_PREFIX_MS,
+    OPENAI_VOICES,
+    SUPPORTED_LANGUAGES,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class VoiceSettings:
+    """Manages voice, language, and VAD settings with database persistence.
+    
+    This class provides a centralized way to manage all voice-related settings.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize with default values."""
+        self._voice_id = "coral"  # Default voice
+        self._language = "en"  # Default language
+        self._kids_mode_enabled = False  # Default kids mode
+        self._vad_threshold = DEFAULT_VAD_THRESHOLD
+        self._vad_silence_ms = DEFAULT_VAD_SILENCE_MS
+        self._vad_prefix_ms = DEFAULT_VAD_PREFIX_MS
+        
+        # Callback for VAD settings changes
+        self._vad_changed_callback: Optional[Callable[[], None]] = None
+    
+    # MARK: - Voice Settings
+    
+    @property
+    def voice_id(self) -> str:
+        """Get current voice ID."""
+        return self._voice_id
+    
+    def set_voice(self, voice_id: str) -> bool:
+        """Set the current voice.
+        
+        Args:
+            voice_id: OpenAI voice ID.
+            
+        Returns:
+            True if voice was valid and set.
+        """
+        valid_voices = [v["id"] for v in OPENAI_VOICES]
+        if voice_id not in valid_voices:
+            logger.warning(f"Invalid voice ID: {voice_id}")
+            return False
+        
+        if voice_id != self._voice_id:
+            self._voice_id = voice_id
+            self._persist_setting(VOICE_ID_KEY, voice_id)
+            logger.info(f"🔊 Voice set to: {voice_id}")
+        
+        return True
+    
+    # MARK: - Language Settings
+    
+    @property
+    def language(self) -> str:
+        """Get current language code."""
+        return self._language
+    
+    def set_language(self, language: str) -> bool:
+        """Set the preferred language.
+        
+        Args:
+            language: Language code (e.g., 'en', 'nl').
+            
+        Returns:
+            True if language was valid and set.
+        """
+        valid_languages = [lang["code"] for lang in SUPPORTED_LANGUAGES]
+        if language not in valid_languages:
+            logger.warning(f"Invalid language: {language}")
+            return False
+        
+        if language != self._language:
+            self._language = language
+            self._persist_setting(PREFERRED_LANGUAGE_KEY, language)
+            logger.info(f"🌍 Language set to: {language}")
+        
+        return True
+    
+    # MARK: - Kids Mode
+    
+    @property
+    def kids_mode_enabled(self) -> bool:
+        """Get kids mode enabled state."""
+        return self._kids_mode_enabled
+    
+    def set_kids_mode(self, enabled: bool) -> None:
+        """Set kids mode enabled state.
+        
+        Args:
+            enabled: Whether kids mode is enabled.
+        """
+        if enabled != self._kids_mode_enabled:
+            self._kids_mode_enabled = enabled
+            self._persist_setting(KIDS_MODE_KEY, "true" if enabled else "false")
+            logger.info(f"👶 Kids mode: {'enabled' if enabled else 'disabled'}")
+            
+            # Also update the audio playback module's kids mode state
+            from ...audio_playback import set_kids_mode as set_audio_kids_mode
+            set_audio_kids_mode(enabled)
+    
+    # MARK: - VAD Settings
+    
+    @property
+    def vad_threshold(self) -> float:
+        """Get VAD threshold."""
+        return self._vad_threshold
+    
+    @property
+    def vad_silence_ms(self) -> int:
+        """Get VAD silence duration in milliseconds."""
+        return self._vad_silence_ms
+    
+    @property
+    def vad_prefix_ms(self) -> int:
+        """Get VAD prefix padding in milliseconds."""
+        return self._vad_prefix_ms
+    
+    def set_vad_settings(
+        self,
+        threshold: Optional[float] = None,
+        silence_ms: Optional[int] = None,
+        prefix_ms: Optional[int] = None,
+    ) -> None:
+        """Set VAD settings.
+        
+        Args:
+            threshold: VAD activation threshold (0.0 - 1.0).
+            silence_ms: Silence duration before speech end (ms).
+            prefix_ms: Prefix padding before speech start (ms).
+        """
+        changed = False
+        
+        if threshold is not None:
+            threshold = max(0.0, min(1.0, threshold))
+            if threshold != self._vad_threshold:
+                self._vad_threshold = threshold
+                self._persist_setting(VAD_THRESHOLD_KEY, str(threshold))
+                changed = True
+        
+        if silence_ms is not None:
+            silence_ms = max(100, min(5000, silence_ms))
+            if silence_ms != self._vad_silence_ms:
+                self._vad_silence_ms = silence_ms
+                self._persist_setting(VAD_SILENCE_MS_KEY, str(silence_ms))
+                changed = True
+        
+        if prefix_ms is not None:
+            prefix_ms = max(100, min(2000, prefix_ms))
+            if prefix_ms != self._vad_prefix_ms:
+                self._vad_prefix_ms = prefix_ms
+                self._persist_setting(VAD_PREFIX_MS_KEY, str(prefix_ms))
+                changed = True
+        
+        if changed:
+            logger.info(
+                f"🎤 VAD settings updated: threshold={self._vad_threshold}, "
+                f"silence={self._vad_silence_ms}ms, prefix={self._vad_prefix_ms}ms"
+            )
+            if self._vad_changed_callback:
+                self._vad_changed_callback()
+    
+    def set_vad_callback(self, callback: Optional[Callable[[], None]]) -> None:
+        """Set callback for VAD settings changes.
+        
+        Args:
+            callback: Function to call when VAD settings change.
+        """
+        self._vad_changed_callback = callback
+    
+    # MARK: - Persistence
+    
+    def _persist_setting(self, key: str, value: str) -> None:
+        """Persist a setting to the database asynchronously."""
+        asyncio.create_task(self._persist_setting_async(key, value))
+    
+    async def _persist_setting_async(self, key: str, value: str) -> None:
+        """Persist a setting to the database."""
+        try:
+            db = get_database()
+            await db.set_user_setting(key, value)
+        except Exception as e:
+            logger.error(f"Failed to persist setting {key}: {e}")
+    
+    async def load_from_database(self) -> None:
+        """Load settings from database."""
+        try:
+            db = get_database()
+            
+            # Load voice ID
+            voice_id = await db.get_user_setting(VOICE_ID_KEY)
+            if voice_id:
+                valid_voices = [v["id"] for v in OPENAI_VOICES]
+                if voice_id in valid_voices:
+                    self._voice_id = voice_id
+                    logger.info(f"📀 Loaded voice ID from database: {voice_id}")
+            
+            # Load language
+            language = await db.get_user_setting(PREFERRED_LANGUAGE_KEY)
+            if language:
+                valid_languages = [lang["code"] for lang in SUPPORTED_LANGUAGES]
+                if language in valid_languages:
+                    self._language = language
+                    logger.info(f"📀 Loaded language from database: {language}")
+            
+            # Load kids mode
+            kids_mode = await db.get_user_setting(KIDS_MODE_KEY)
+            if kids_mode:
+                self._kids_mode_enabled = kids_mode.lower() == "true"
+                logger.info(f"📀 Loaded kids mode from database: {self._kids_mode_enabled}")
+                
+                # Sync audio_playback module
+                from ...audio_playback import set_kids_mode as set_audio_kids_mode
+                set_audio_kids_mode(self._kids_mode_enabled)
+            
+            # Load VAD settings
+            threshold_str = await db.get_user_setting(VAD_THRESHOLD_KEY)
+            if threshold_str:
+                try:
+                    self._vad_threshold = float(threshold_str)
+                    logger.info(f"📀 Loaded VAD threshold: {self._vad_threshold}")
+                except ValueError:
+                    pass
+            
+            silence_str = await db.get_user_setting(VAD_SILENCE_MS_KEY)
+            if silence_str:
+                try:
+                    self._vad_silence_ms = int(silence_str)
+                    logger.info(f"📀 Loaded VAD silence: {self._vad_silence_ms}ms")
+                except ValueError:
+                    pass
+            
+            prefix_str = await db.get_user_setting(VAD_PREFIX_MS_KEY)
+            if prefix_str:
+                try:
+                    self._vad_prefix_ms = int(prefix_str)
+                    logger.info(f"📀 Loaded VAD prefix: {self._vad_prefix_ms}ms")
+                except ValueError:
+                    pass
+            
+        except Exception as e:
+            logger.error(f"Failed to load settings from database: {e}")
+
+
+# Global settings instance
+_voice_settings: Optional[VoiceSettings] = None
+
+
+def get_voice_settings() -> VoiceSettings:
+    """Get the global VoiceSettings instance.
+    
+    Returns:
+        The VoiceSettings singleton.
+    """
+    global _voice_settings
+    if _voice_settings is None:
+        _voice_settings = VoiceSettings()
+    return _voice_settings
+
+
+async def init_voice_settings() -> VoiceSettings:
+    """Initialize voice settings from database.
+    
+    Returns:
+        The initialized VoiceSettings instance.
+    """
+    settings = get_voice_settings()
+    await settings.load_from_database()
+    return settings
+
+
+# Convenience functions
+def get_current_voice() -> str:
+    """Get the current voice ID."""
+    return get_voice_settings().voice_id
+
+
+def set_current_voice(voice_id: str) -> bool:
+    """Set the current voice ID."""
+    return get_voice_settings().set_voice(voice_id)
+
+
+def get_preferred_language() -> str:
+    """Get the preferred language code."""
+    return get_voice_settings().language
+
+
+def set_preferred_language(language: str) -> bool:
+    """Set the preferred language."""
+    return get_voice_settings().set_language(language)
+
+
+def get_kids_mode_enabled() -> bool:
+    """Get kids mode enabled state."""
+    return get_voice_settings().kids_mode_enabled
+
+
+def set_kids_mode_enabled(enabled: bool) -> None:
+    """Set kids mode enabled state."""
+    get_voice_settings().set_kids_mode(enabled)
+
+
+def get_vad_threshold() -> float:
+    """Get VAD threshold."""
+    return get_voice_settings().vad_threshold
+
+
+def get_vad_silence_ms() -> int:
+    """Get VAD silence duration in milliseconds."""
+    return get_voice_settings().vad_silence_ms
+
+
+def get_vad_prefix_ms() -> int:
+    """Get VAD prefix padding in milliseconds."""
+    return get_voice_settings().vad_prefix_ms
+
+
+def set_vad_settings_callback(callback: Optional[Callable[[], None]]) -> None:
+    """Set callback for VAD settings changes."""
+    get_voice_settings().set_vad_callback(callback)
+

reachys_brain/routes/voice/vad.py

@@ -0,0 +1,41 @@
+"""VAD (Voice Activity Detection) settings and presets.
+
+Provides VAD presets for different environments and helper functions.
+"""
+
+# VAD Presets for different environments
+VAD_PRESETS = {
+    "quiet_room": {
+        "id": "quiet_room",
+        "name": "Quiet Room",
+        "description": "More sensitive, responds faster. Best for quiet environments.",
+        "threshold": 0.5,
+        "silence_ms": 500,
+        "prefix_ms": 300,
+    },
+    "normal": {
+        "id": "normal",
+        "name": "Normal",
+        "description": "Balanced settings for typical use.",
+        "threshold": 0.8,
+        "silence_ms": 800,
+        "prefix_ms": 300,
+    },
+    "noisy": {
+        "id": "noisy",
+        "name": "Noisy Environment",
+        "description": "Less sensitive, ignores background noise better.",
+        "threshold": 0.85,
+        "silence_ms": 1000,
+        "prefix_ms": 400,
+    },
+    "conference": {
+        "id": "conference",
+        "name": "Conference Room",
+        "description": "Very strict, ignores most background voices.",
+        "threshold": 0.9,
+        "silence_ms": 1200,
+        "prefix_ms": 500,
+    },
+}
+

reachys_brain/tools/datetime_tool.py

@@ -20,12 +20,9 @@ DATETIME_TOOL_DEFINITION = {
     "type": "function",
     "name": "get_current_datetime",
     "description": (
-        "Get the current date and time. Use this to give time-appropriate greetings "
-        "(e.g., 'Good morning', 'Good afternoon', 'Good evening'), to know what day it is, "
-        "or when the user asks about the current time or date. "
-        "Call this at the start of conversations to greet the user appropriately. "
-        "IMPORTANT: Do NOT ask for a timezone - just call this tool without parameters. "
-        "The timezone is automatically determined from the user's saved preferred location."
+        "Get current date/time for greetings or time queries. "
+        "No announcement needed - just use directly. "
+        "Don't ask for timezone - it's auto-detected from user's country."
     ),
     "parameters": {
         "type": "object",

reachys_brain/tools/reminders.py

@@ -58,9 +58,8 @@ ADD_REMINDER_TOOL_DEFINITION = {
     "type": "function",
     "name": "add_reminder",
     "description": (
-        "Add a new reminder to the user's iOS Reminders app. "
-        "Use this when the user asks to be reminded of something. "
-        "The reminder will appear in their default Reminders list."
+        "Add a reminder to user's iOS Reminders. Quick tool - no announcement needed. "
+        "Just add it and confirm it was added."
     ),
     "parameters": {
         "type": "object",