Deploy new version

README.md

@@ -6,7 +6,7 @@ colorTo: yellow
 sdk: static
 pinned: false
 short_description: iOS voice assistant with TTS, animations & vision
-thumbnail: https://huggingface.co/spaces/robertkeus/reachy_ios_bridge/resolve/main/logo.png
+thumbnail: https://huggingface.co/spaces/robertkeus/reachys_brain/resolve/main/logo.png
 tags:
   - reachy_mini
   - reachy_mini_python_app
@@ -39,7 +39,7 @@ A Reachy Mini app that provides an HTTP API for iOS voice assistant integration.
 
 ```bash
 # Navigate to the app directory
-cd reachy_ios_bridge
+cd reachys_brain
 
 # Install in development mode
 pip install -e .
@@ -64,7 +64,7 @@ The TTS and voice conversation features require an OpenAI API key. You can confi
 
 2. Open your browser to [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
 
-3. Select "Reachy iOS Bridge" from the installed applications
+3. Select "Reachy's Brain" from the installed applications
 
 4. The HTTP server will start on port 8080
 
@@ -74,7 +74,7 @@ The TTS and voice conversation features require an OpenAI API key. You can confi
 
 ```bash
 # Run without Reachy connected
-reachy-ios-bridge
+reachys-brain
 ```
 
 ## API Endpoints

pyproject.toml

@@ -3,9 +3,9 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "reachy_ios_bridge"
+name = "reachys_brain"
 version = "0.1.0"
-description = "iOS Bridge for Reachy Mini - HTTP server for voice assistant integration"
+description = "Reachy's Brain - Voice assistant and AI integration for Reachy Mini"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
@@ -25,8 +25,8 @@ dependencies = [
 ]
 
 [project.entry-points."reachy_mini_apps"]
-reachys_brain = "reachy_ios_bridge.main:ReachyIosBridge"
+reachys_brain = "reachys_brain.main:ReachyIosBridge"
 
 [project.scripts]
-reachy-ios-bridge = "reachy_ios_bridge.server:run_server"
+reachys-brain = "reachys_brain.server:run_server"
 

reachys_brain/__init__.py

@@ -0,0 +1,4 @@
+"""Reachy iOS Bridge - HTTP server for voice assistant integration."""
+
+__version__ = "0.1.0"
+

reachys_brain/animation_coordinator.py

@@ -0,0 +1,543 @@
+"""Animation coordinator for speech.
+
+Plays a single emotion animation BEFORE speech starts, based on
+sentiment analysis of the text. Animations have sounds, so they
+must complete before TTS begins.
+"""
+
+import asyncio
+import logging
+import random
+from dataclasses import dataclass
+from typing import Optional
+
+from .motion_service import MotionService
+from .routes.audio_stream_manager import ConversationTimings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AnimationResult:
+    """Result of playing a pre-speech animation."""
+    
+    played: bool  # Whether an animation was played
+    sentiment: str  # Detected sentiment
+    animation: str  # Animation name (empty if not played)
+    duration: float  # Duration in seconds (0 if not played)
+
+
+# Emotion animations grouped by sentiment/context
+# These are played ONCE before speech, based on text analysis
+
+GREETING_EMOTIONS = [
+    "welcoming1", "welcoming2", "cheerful1", "attentive1"
+]
+
+HAPPY_EMOTIONS = [
+    "cheerful1", "enthusiastic1", "enthusiastic2", "grateful1", 
+    "proud1", "success1", "loving1"
+]
+
+SAD_EMOTIONS = [
+    "sad1", "sad2", "understanding1", "calming1", "lonely1"
+]
+
+EXCITED_EMOTIONS = [
+    "amazed1", "surprised1", "surprised2", "enthusiastic1"
+]
+
+QUESTION_EMOTIONS = [
+    "inquiring1", "inquiring2", "inquiring3", "curious1", "attentive1"
+]
+
+THINKING_EMOTIONS = [
+    "thoughtful1", "thoughtful2", "uncertain1", "confused1"
+]
+
+APOLOGETIC_EMOTIONS = [
+    "oops1", "oops2", "understanding1", "calming1"
+]
+
+HELPFUL_EMOTIONS = [
+    "helpful1", "helpful2", "attentive1", "welcoming1"
+]
+
+NEUTRAL_EMOTIONS = [
+    "attentive1", "attentive2", "serenity1"
+]
+
+
+# Multilingual keyword sets for sentiment detection
+
+GREETING_KEYWORDS = {
+    "en": {"hello", "hi", "hey", "welcome", "greetings", "good morning", "good afternoon", "good evening"},
+    "nl": {"hallo", "hoi", "hey", "welkom", "goedemorgen", "goedemiddag", "goedenavond", "dag"},
+    "de": {"hallo", "hi", "hey", "willkommen", "guten morgen", "guten tag", "guten abend"},
+    "fr": {"bonjour", "salut", "bienvenue", "bonsoir", "coucou"},
+    "es": {"hola", "buenos días", "buenas tardes", "buenas noches", "bienvenido"},
+}
+
+HAPPY_KEYWORDS = {
+    "en": {"happy", "glad", "great", "wonderful", "amazing", "excellent", "love", "fantastic", 
+           "awesome", "delighted", "pleased", "excited", "joy", "thank", "thanks", "grateful"},
+    "nl": {"blij", "gelukkig", "geweldig", "fantastisch", "prachtig", "leuk", "fijn", "super",
+           "bedankt", "dank", "graag", "mooi", "heerlijk", "top"},
+    "de": {"glücklich", "froh", "toll", "wunderbar", "fantastisch", "super", "danke", "freude",
+           "großartig", "herrlich", "schön"},
+    "fr": {"heureux", "content", "merveilleux", "fantastique", "excellent", "merci", "génial",
+           "super", "magnifique", "formidable"},
+    "es": {"feliz", "contento", "maravilloso", "fantástico", "excelente", "gracias", "genial",
+           "increíble", "estupendo"},
+}
+
+SAD_KEYWORDS = {
+    "en": {"sorry", "sad", "unfortunately", "regret", "apologies", "difficult", "hard", 
+           "disappointed", "upset", "bad news"},
+    "nl": {"sorry", "helaas", "jammer", "verdrietig", "spijt", "moeilijk", "teleurgesteld"},
+    "de": {"leider", "traurig", "entschuldigung", "bedaure", "schwierig", "schade"},
+    "fr": {"désolé", "malheureusement", "triste", "regret", "difficile", "dommage"},
+    "es": {"lo siento", "triste", "lamentablemente", "difícil", "desafortunadamente"},
+}
+
+EXCITED_KEYWORDS = {
+    "en": {"wow", "amazing", "incredible", "awesome", "fantastic", "exciting", "unbelievable",
+           "wonderful", "brilliant"},
+    "nl": {"wauw", "geweldig", "ongelooflijk", "fantastisch", "super", "gaaf", "cool"},
+    "de": {"wow", "unglaublich", "fantastisch", "toll", "wahnsinn", "krass"},
+    "fr": {"wow", "incroyable", "fantastique", "génial", "extraordinaire"},
+    "es": {"guau", "increíble", "fantástico", "asombroso", "maravilloso"},
+}
+
+QUESTION_KEYWORDS = {
+    "en": {"what", "how", "why", "when", "where", "who", "which", "could", "would", "can", "?"},
+    "nl": {"wat", "hoe", "waarom", "wanneer", "waar", "wie", "welke", "kun", "zou", "?"},
+    "de": {"was", "wie", "warum", "wann", "wo", "wer", "welche", "können", "würden", "?"},
+    "fr": {"quoi", "comment", "pourquoi", "quand", "où", "qui", "quel", "pouvez", "?"},
+    "es": {"qué", "cómo", "por qué", "cuándo", "dónde", "quién", "cuál", "puede", "?"},
+}
+
+THINKING_KEYWORDS = {
+    "en": {"think", "believe", "maybe", "perhaps", "probably", "might", "consider", "wonder",
+           "hmm", "let me", "i think"},
+    "nl": {"denk", "misschien", "wellicht", "waarschijnlijk", "hmm", "even kijken", "geloof"},
+    "de": {"denke", "vielleicht", "wahrscheinlich", "hmm", "glaube", "möglicherweise"},
+    "fr": {"pense", "peut-être", "probablement", "hmm", "crois", "je pense"},
+    "es": {"creo", "quizás", "probablemente", "hmm", "pienso", "tal vez"},
+}
+
+APOLOGETIC_KEYWORDS = {
+    "en": {"sorry", "apologize", "apologies", "my mistake", "oops", "my bad", "excuse me"},
+    "nl": {"sorry", "excuses", "mijn fout", "oeps", "pardon"},
+    "de": {"entschuldigung", "tut mir leid", "verzeihung", "mein fehler", "ups"},
+    "fr": {"désolé", "pardon", "excusez", "mes excuses", "oups"},
+    "es": {"perdón", "disculpa", "lo siento", "mis disculpas"},
+}
+
+HELPFUL_KEYWORDS = {
+    "en": {"help", "assist", "here is", "let me", "i can", "sure", "of course", "certainly",
+           "absolutely", "no problem", "happy to"},
+    "nl": {"help", "hier is", "ik kan", "natuurlijk", "zeker", "geen probleem", "graag"},
+    "de": {"hilfe", "hier ist", "ich kann", "natürlich", "sicher", "kein problem", "gerne"},
+    "fr": {"aide", "voici", "je peux", "bien sûr", "certainement", "pas de problème"},
+    "es": {"ayuda", "aquí está", "puedo", "por supuesto", "claro", "sin problema"},
+}
+
+
+class AnimationCoordinator:
+    """Coordinates emotion animations before speech.
+    
+    Analyzes text sentiment and plays ONE appropriate emotion animation
+    before speech begins. Animations have their own sounds, so they
+    must complete before TTS starts.
+    
+    Custom apps can override the default animation mappings by calling
+    set_custom_animations() with their own emotion-to-animation mapping.
+    """
+    
+    def __init__(self, motion_service: MotionService):
+        """Initialize the coordinator.
+        
+        Args:
+            motion_service: Service for playing animations.
+        """
+        self._motion = motion_service
+        self._language = "en"
+        self._is_animating = False
+        self._last_emotion: Optional[str] = None
+        
+        # Custom animation overrides from active app
+        # Maps sentiment (e.g., "happy") to animation name (e.g., "dance1")
+        self._custom_animations: dict[str, str] = {}
+        
+        logger.info(f"AnimationCoordinator initialized (language: {self._language})")
+    
+    def set_custom_animations(self, animations: dict[str, str]) -> None:
+        """Set custom animation mappings for the active app.
+        
+        Args:
+            animations: Dict mapping sentiment names to animation names.
+                        e.g., {"happy": "cheerful1", "sad": "calming1"}
+        """
+        self._custom_animations = animations.copy() if animations else {}
+        if animations:
+            logger.info(f"Custom animations set: {list(animations.keys())}")
+        else:
+            logger.info("Custom animations cleared - using defaults")
+    
+    def clear_custom_animations(self) -> None:
+        """Clear custom animation mappings, reverting to defaults."""
+        self._custom_animations = {}
+        logger.info("Custom animations cleared - using defaults")
+    
+    def _normalize_language(self, language: str) -> str:
+        """Normalize language code to base language."""
+        if not language:
+            return "en"
+        # Extract base language (e.g., "nl_NL" -> "nl")
+        base = language.split("_")[0].split("-")[0].lower()
+        # Return base if we have keywords for it, else default to English
+        if base in HAPPY_KEYWORDS:
+            return base
+        return "en"
+    
+    def set_language(self, language: str) -> None:
+        """Set the language for sentiment analysis.
+        
+        Args:
+            language: Language code (e.g., "en", "nl", "nl_NL").
+        """
+        old_lang = self._language
+        self._language = self._normalize_language(language)
+        if old_lang != self._language:
+            logger.info(f"AnimationCoordinator language changed: {old_lang} -> {self._language}")
+    
+    @property
+    def language(self) -> str:
+        """Get the current language code."""
+        return self._language
+    
+    @property
+    def is_animating(self) -> bool:
+        """Check if currently playing an animation."""
+        return self._is_animating
+    
+    def _get_keywords(self, keyword_dict: dict) -> set:
+        """Get keywords for current language with English fallback."""
+        return keyword_dict.get(self._language, keyword_dict.get("en", set()))
+    
+    def _analyze_sentiment(self, text: str) -> str:
+        """Analyze text and return the best emotion category.
+        
+        Args:
+            text: The text to analyze.
+            
+        Returns:
+            Emotion category: "greeting", "happy", "sad", "excited", 
+            "question", "thinking", "apologetic", "helpful", or "neutral".
+        """
+        text_lower = text.lower()
+        words = set(text_lower.split())
+        
+        # Check for question marks first (high priority)
+        if "?" in text:
+            return "question"
+        
+        # Check each category
+        greeting_kw = self._get_keywords(GREETING_KEYWORDS)
+        if words & greeting_kw or any(kw in text_lower for kw in greeting_kw):
+            return "greeting"
+        
+        apologetic_kw = self._get_keywords(APOLOGETIC_KEYWORDS)
+        if words & apologetic_kw or any(kw in text_lower for kw in apologetic_kw):
+            return "apologetic"
+        
+        excited_kw = self._get_keywords(EXCITED_KEYWORDS)
+        if words & excited_kw or any(kw in text_lower for kw in excited_kw):
+            # Check for exclamation mark to confirm excitement
+            if "!" in text:
+                return "excited"
+        
+        happy_kw = self._get_keywords(HAPPY_KEYWORDS)
+        if words & happy_kw or any(kw in text_lower for kw in happy_kw):
+            return "happy"
+        
+        sad_kw = self._get_keywords(SAD_KEYWORDS)
+        if words & sad_kw or any(kw in text_lower for kw in sad_kw):
+            return "sad"
+        
+        # Check helpful BEFORE thinking (both share "let me")
+        helpful_kw = self._get_keywords(HELPFUL_KEYWORDS)
+        if words & helpful_kw or any(kw in text_lower for kw in helpful_kw):
+            return "helpful"
+        
+        thinking_kw = self._get_keywords(THINKING_KEYWORDS)
+        if words & thinking_kw or any(kw in text_lower for kw in thinking_kw):
+            return "thinking"
+        
+        question_kw = self._get_keywords(QUESTION_KEYWORDS)
+        if words & question_kw:
+            return "question"
+        
+        return "neutral"
+    
+    def _get_animation_chance(self, sentiment: str) -> float:
+        """Get the probability of playing an animation for this sentiment.
+        
+        Args:
+            sentiment: The sentiment category.
+            
+        Returns:
+            Probability between 0.0 and 1.0.
+        """
+        if sentiment == "greeting":
+            return ConversationTimings.PRE_SPEECH_CHANCE_GREETING
+        elif sentiment in ("excited", "happy", "sad", "apologetic"):
+            return ConversationTimings.PRE_SPEECH_CHANCE_STRONG
+        elif sentiment in ("question", "thinking"):
+            return ConversationTimings.PRE_SPEECH_CHANCE_THINKING
+        else:
+            return ConversationTimings.PRE_SPEECH_CHANCE_NEUTRAL
+    
+    def _get_animation_duration(self, sentiment: str) -> float:
+        """Get the animation duration for this sentiment.
+        
+        Args:
+            sentiment: The sentiment category.
+            
+        Returns:
+            Duration in seconds.
+        """
+        if sentiment == "greeting":
+            return ConversationTimings.PRE_SPEECH_DURATION_GREETING
+        elif sentiment in ("excited", "happy", "sad", "apologetic"):
+            return ConversationTimings.PRE_SPEECH_DURATION_STRONG
+        else:
+            return ConversationTimings.PRE_SPEECH_DURATION_DEFAULT
+    
+    def _get_emotion_for_sentiment(self, sentiment: str) -> str:
+        """Get an emotion animation for the given sentiment.
+        
+        Checks custom animations first, then falls back to defaults.
+        
+        Args:
+            sentiment: The sentiment category.
+            
+        Returns:
+            An emotion animation name.
+        """
+        # Check for custom animation override first
+        if sentiment in self._custom_animations:
+            return self._custom_animations[sentiment]
+        
+        # Map some sentiments to custom animation keys if they exist
+        # Custom apps might use simpler keys like "happy" instead of "excited"
+        sentiment_to_custom_key = {
+            "excited": "surprised",
+            "apologetic": "sad",
+            "helpful": "happy",
+            "question": "thinking",
+        }
+        custom_key = sentiment_to_custom_key.get(sentiment, sentiment)
+        if custom_key in self._custom_animations:
+            return self._custom_animations[custom_key]
+        
+        # Fall back to default emotion animations
+        emotion_map = {
+            "greeting": GREETING_EMOTIONS,
+            "happy": HAPPY_EMOTIONS,
+            "sad": SAD_EMOTIONS,
+            "excited": EXCITED_EMOTIONS,
+            "question": QUESTION_EMOTIONS,
+            "thinking": THINKING_EMOTIONS,
+            "apologetic": APOLOGETIC_EMOTIONS,
+            "helpful": HELPFUL_EMOTIONS,
+            "neutral": NEUTRAL_EMOTIONS,
+        }
+        
+        emotions = emotion_map.get(sentiment, NEUTRAL_EMOTIONS)
+        
+        # Try to avoid repeating the same emotion twice in a row
+        if len(emotions) > 1 and self._last_emotion in emotions:
+            emotions = [e for e in emotions if e != self._last_emotion]
+        
+        emotion = random.choice(emotions)
+        self._last_emotion = emotion
+        return emotion
+    
+    async def play_emotion_for_text(self, text: str) -> AnimationResult:
+        """Analyze text and maybe play an appropriate emotion animation.
+        
+        This should be called BEFORE speech starts. Uses probability-based
+        selection: strong emotions play more often, neutral less often.
+        
+        Args:
+            text: The text that will be spoken.
+            
+        Returns:
+            AnimationResult with details of what happened.
+        """
+        # Analyze sentiment first (always do this for the result)
+        sentiment = self._analyze_sentiment(text)
+        
+        if self._is_animating:
+            logger.warning("Already animating, skipping")
+            return AnimationResult(
+                played=False,
+                sentiment=sentiment,
+                animation="",
+                duration=0.0
+            )
+        
+        # Check if we should play based on probability
+        chance = self._get_animation_chance(sentiment)
+        if random.random() > chance:
+            logger.debug(f"Skipping animation for '{sentiment}' (chance: {chance:.0%})")
+            return AnimationResult(
+                played=False,
+                sentiment=sentiment,
+                animation="",
+                duration=0.0
+            )
+        
+        self._is_animating = True
+        
+        try:
+            emotion = self._get_emotion_for_sentiment(sentiment)
+            duration = self._get_animation_duration(sentiment)
+            
+            logger.info(f"Playing emotion '{emotion}' for sentiment '{sentiment}' ({duration}s)")
+            
+            # Play the animation
+            success = await self._motion.play_async(
+                animation=emotion,
+                duration=duration
+            )
+            
+            if success:
+                # Wait for animation to complete before returning
+                await asyncio.sleep(duration)
+                logger.info(f"Emotion animation '{emotion}' completed")
+                return AnimationResult(
+                    played=True,
+                    sentiment=sentiment,
+                    animation=emotion,
+                    duration=duration
+                )
+            else:
+                logger.warning(f"Failed to play emotion '{emotion}'")
+                return AnimationResult(
+                    played=False,
+                    sentiment=sentiment,
+                    animation=emotion,
+                    duration=0.0
+                )
+                
+        except Exception as e:
+            logger.error(f"Error playing emotion animation: {e}")
+            return AnimationResult(
+                played=False,
+                sentiment=sentiment,
+                animation="",
+                duration=0.0
+            )
+        finally:
+            self._is_animating = False
+    
+    def get_emotion_for_text_sync(self, text: str) -> tuple[str, str]:
+        """Synchronously analyze text and return sentiment and animation.
+        
+        Use this if you need to know the emotion without playing it.
+        
+        Args:
+            text: The text to analyze.
+            
+        Returns:
+            Tuple of (sentiment, animation_name).
+        """
+        sentiment = self._analyze_sentiment(text)
+        animation = self._get_emotion_for_sentiment(sentiment)
+        return sentiment, animation
+    
+    def analyze_sentiment(self, text: str) -> str:
+        """Public method to analyze text sentiment.
+        
+        Args:
+            text: The text to analyze.
+            
+        Returns:
+            Sentiment category string.
+        """
+        return self._analyze_sentiment(text)
+    
+    async def play_animation(self, animation_name: str, duration: float = 2.0) -> bool:
+        """Play a specific animation by name.
+        
+        Args:
+            animation_name: The name of the animation to play.
+            duration: Duration in seconds.
+            
+        Returns:
+            True if animation was played successfully.
+        """
+        if self._is_animating:
+            logger.warning("Already animating, skipping")
+            return False
+        
+        self._is_animating = True
+        
+        try:
+            logger.info(f"Playing animation '{animation_name}' ({duration}s)")
+            
+            success = await self._motion.play_async(
+                animation=animation_name,
+                duration=duration
+            )
+            
+            if success:
+                await asyncio.sleep(duration)
+                logger.info(f"Animation '{animation_name}' completed")
+                return True
+            else:
+                logger.warning(f"Failed to play animation '{animation_name}'")
+                return False
+                
+        except Exception as e:
+            logger.error(f"Error playing animation: {e}")
+            return False
+        finally:
+            self._is_animating = False
+
+
+# Singleton instance for global access
+_animation_coordinator_instance: Optional["AnimationCoordinator"] = None
+
+
+def get_animation_coordinator() -> Optional["AnimationCoordinator"]:
+    """Get the global AnimationCoordinator instance.
+    
+    Returns the global coordinator set by speech.py, or None if not available.
+    """
+    global _animation_coordinator_instance
+    
+    # If not set, try to get from speech module (which creates it in set_services)
+    if _animation_coordinator_instance is None:
+        try:
+            from .routes.speech import animation_coordinator as speech_coordinator
+            if speech_coordinator:
+                _animation_coordinator_instance = speech_coordinator
+                logger.info("Using AnimationCoordinator from speech module")
+        except ImportError as e:
+            logger.debug(f"Could not get coordinator from speech: {e}")
+    
+    return _animation_coordinator_instance
+
+
+def set_animation_coordinator(coordinator: "AnimationCoordinator") -> None:
+    """Set the global AnimationCoordinator instance.
+    
+    Called by speech.py set_services to share the same instance.
+    """
+    global _animation_coordinator_instance
+    _animation_coordinator_instance = coordinator
+    logger.info("Global AnimationCoordinator instance set")

reachys_brain/app_tools.py

@@ -0,0 +1,892 @@
+"""Voice-activated app management tools for OpenAI Realtime API.
+
+Provides tool functions for creating, activating, and managing custom apps
+via voice commands. These tools are called by OpenAI's function calling feature.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import uuid
+from datetime import datetime
+from difflib import SequenceMatcher
+from typing import Callable, Optional
+
+import aiohttp
+import httpx
+
+from .database import get_database
+
+logger = logging.getLogger(__name__)
+
+
+# Tool definitions for OpenAI Realtime API
+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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "A short, catchy name for the app (e.g., 'English Tutor', 'Cooking Helper')"
+                },
+                "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')"
+                    )
+                },
+                "icon_color": {
+                    "type": "string",
+                    "enum": ["blue", "purple", "pink", "red", "orange", "yellow", "green", "teal", "indigo"],
+                    "description": "The color for the app's icon"
+                }
+            },
+            "required": ["name", "description"]
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "app_name": {
+                    "type": "string",
+                    "description": "The name (or partial name) of the app to activate"
+                }
+            },
+            "required": ["app_name"]
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "The user's name or preferred nickname to remember"
+                }
+            },
+            "required": ["name"]
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "country": {
+                    "type": "string",
+                    "description": "The user's country name (e.g., 'Netherlands', 'Germany', 'United States')"
+                }
+            },
+            "required": ["country"]
+        }
+    },
+    {
+        "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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    }
+]
+
+
+# Country to timezone mapping for common countries
+# Uses primary/capital timezone for countries with multiple zones
+COUNTRY_TIMEZONE_MAP = {
+    # Europe
+    "netherlands": "Europe/Amsterdam",
+    "the netherlands": "Europe/Amsterdam",
+    "holland": "Europe/Amsterdam",
+    "germany": "Europe/Berlin",
+    "france": "Europe/Paris",
+    "united kingdom": "Europe/London",
+    "uk": "Europe/London",
+    "england": "Europe/London",
+    "scotland": "Europe/London",
+    "wales": "Europe/London",
+    "ireland": "Europe/Dublin",
+    "spain": "Europe/Madrid",
+    "italy": "Europe/Rome",
+    "portugal": "Europe/Lisbon",
+    "belgium": "Europe/Brussels",
+    "austria": "Europe/Vienna",
+    "switzerland": "Europe/Zurich",
+    "sweden": "Europe/Stockholm",
+    "norway": "Europe/Oslo",
+    "denmark": "Europe/Copenhagen",
+    "finland": "Europe/Helsinki",
+    "poland": "Europe/Warsaw",
+    "czech republic": "Europe/Prague",
+    "czechia": "Europe/Prague",
+    "greece": "Europe/Athens",
+    "turkey": "Europe/Istanbul",
+    "russia": "Europe/Moscow",
+    "ukraine": "Europe/Kyiv",
+    
+    # North America
+    "united states": "America/New_York",
+    "usa": "America/New_York",
+    "us": "America/New_York",
+    "america": "America/New_York",
+    "canada": "America/Toronto",
+    "mexico": "America/Mexico_City",
+    
+    # South America
+    "brazil": "America/Sao_Paulo",
+    "argentina": "America/Buenos_Aires",
+    "chile": "America/Santiago",
+    "colombia": "America/Bogota",
+    "peru": "America/Lima",
+    
+    # Asia
+    "japan": "Asia/Tokyo",
+    "china": "Asia/Shanghai",
+    "south korea": "Asia/Seoul",
+    "korea": "Asia/Seoul",
+    "india": "Asia/Kolkata",
+    "indonesia": "Asia/Jakarta",
+    "thailand": "Asia/Bangkok",
+    "vietnam": "Asia/Ho_Chi_Minh",
+    "philippines": "Asia/Manila",
+    "malaysia": "Asia/Kuala_Lumpur",
+    "singapore": "Asia/Singapore",
+    "hong kong": "Asia/Hong_Kong",
+    "taiwan": "Asia/Taipei",
+    "pakistan": "Asia/Karachi",
+    "bangladesh": "Asia/Dhaka",
+    "israel": "Asia/Jerusalem",
+    "united arab emirates": "Asia/Dubai",
+    "uae": "Asia/Dubai",
+    "saudi arabia": "Asia/Riyadh",
+    
+    # Oceania
+    "australia": "Australia/Sydney",
+    "new zealand": "Pacific/Auckland",
+    
+    # Africa
+    "south africa": "Africa/Johannesburg",
+    "egypt": "Africa/Cairo",
+    "nigeria": "Africa/Lagos",
+    "kenya": "Africa/Nairobi",
+    "morocco": "Africa/Casablanca",
+}
+
+
+def get_timezone_for_country(country: str) -> str | None:
+    """Get the timezone for a country name.
+    
+    Args:
+        country: Country name (case-insensitive).
+        
+    Returns:
+        IANA timezone string or None if country not found.
+    """
+    if not country:
+        return None
+    return COUNTRY_TIMEZONE_MAP.get(country.lower().strip())
+
+
+async def generate_system_prompt(description: str, name: str, api_key: str) -> str:
+    """Generate a detailed system prompt from a brief description using OpenAI Chat API.
+    
+    Args:
+        description: Brief description of what the app should do.
+        name: Name of the app being created.
+        api_key: OpenAI API key for the Chat API call.
+        
+    Returns:
+        A detailed system prompt for the AI personality.
+    """
+    meta_prompt = f"""Create a detailed system prompt for an AI robot assistant named Reachy with this role: {name} - {description}
+
+The prompt should:
+- Define the assistant's personality and character traits
+- Specify communication style (formal/casual, verbose/concise)
+- Outline areas of expertise and knowledge
+- Include behavior guidelines and boundaries
+- Mention that responses should be conversational and suitable for text-to-speech
+- Keep responses typically 1-3 sentences unless more detail is needed
+- Remember Reachy is a physical robot that can express emotions
+
+Keep the prompt under 400 words. Output ONLY the system prompt text, nothing else."""
+
+    url = "https://api.openai.com/v1/chat/completions"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json"
+    }
+    payload = {
+        "model": "gpt-4o-mini",
+        "messages": [{"role": "user", "content": meta_prompt}],
+        "max_tokens": 600,
+        "temperature": 0.7
+    }
+    
+    async with aiohttp.ClientSession() as session:
+        async with session.post(url, headers=headers, json=payload) as response:
+            if response.status != 200:
+                error_text = await response.text()
+                logger.error(f"OpenAI Chat API error: {error_text}")
+                raise RuntimeError(f"Failed to generate system prompt: {response.status}")
+            
+            data = await response.json()
+            content = data["choices"][0]["message"]["content"]
+            return content.strip()
+
+
+def find_best_matching_app(apps: list[dict], query: str) -> Optional[dict]:
+    """Find the best matching app by name using fuzzy matching.
+    
+    Args:
+        apps: List of app dictionaries from the database.
+        query: The search query (partial or full app name).
+        
+    Returns:
+        The best matching app, or None if no good match found.
+    """
+    if not apps:
+        return None
+    
+    query_lower = query.lower().strip()
+    best_match = None
+    best_score = 0.0
+    
+    for app in apps:
+        app_name_lower = app["name"].lower()
+        
+        # Exact match
+        if app_name_lower == query_lower:
+            return app
+        
+        # Contains match (higher priority)
+        if query_lower in app_name_lower or app_name_lower in query_lower:
+            score = 0.9
+        else:
+            # Fuzzy similarity
+            score = SequenceMatcher(None, query_lower, app_name_lower).ratio()
+        
+        if score > best_score:
+            best_score = score
+            best_match = app
+    
+    # Require at least 50% similarity
+    if best_score >= 0.5:
+        return best_match
+    
+    return None
+
+
+class AppToolsHandler:
+    """Handles execution of app management tools called by OpenAI."""
+    
+    # Type aliases for callback signatures
+    OnPersonalityChange = Callable[[Optional[str], Optional[list[str]]], None]
+    OnAppChange = Callable[[dict], None]
+    
+    def __init__(self):
+        """Initialize the tools handler."""
+        self._active_app: Optional[dict] = None
+        
+        # Callback to update the OpenAI service's personality
+        # Signature: (system_prompt: Optional[str], enabled_tools: Optional[list[str]]) -> None
+        self.on_personality_change: Optional["AppToolsHandler.OnPersonalityChange"] = None
+        # Callback to notify iOS of app changes
+        # Signature: (data: dict) -> None
+        self.on_app_change: Optional["AppToolsHandler.OnAppChange"] = None
+    
+    @property
+    def active_app(self) -> Optional[dict]:
+        """Get the currently active custom app."""
+        return self._active_app
+    
+    async def execute_tool(self, tool_name: str, arguments: dict) -> dict:
+        """Execute a tool and return the result.
+        
+        Args:
+            tool_name: Name of the tool to execute.
+            arguments: Tool arguments from OpenAI.
+            
+        Returns:
+            Tool result dictionary with 'success' and relevant data.
+        """
+        logger.info(f"🔧 Executing tool: {tool_name} with args: {arguments}")
+        
+        try:
+            if tool_name == "create_custom_app":
+                return await self._create_app(
+                    name=arguments.get("name", ""),
+                    description=arguments.get("description", ""),
+                    icon_color=arguments.get("icon_color", "blue")
+                )
+            
+            elif tool_name == "activate_custom_app":
+                return await self._activate_app(
+                    app_name=arguments.get("app_name", "")
+                )
+            
+            elif tool_name == "deactivate_app":
+                return await self._deactivate_app()
+            
+            elif tool_name == "list_custom_apps":
+                return await self._list_apps()
+            
+            elif tool_name == "wake_up":
+                return await self._wake_up()
+            
+            elif tool_name == "go_to_sleep":
+                return await self._go_to_sleep()
+            
+            elif tool_name == "remember_user_name":
+                return await self._remember_user_name(
+                    name=arguments.get("name", "")
+                )
+            
+            elif tool_name == "get_user_name":
+                return await self._get_user_name()
+            
+            elif tool_name == "remember_preferred_country":
+                return await self._remember_preferred_country(
+                    country=arguments.get("country", "")
+                )
+            
+            elif tool_name == "get_preferred_country":
+                return await self._get_preferred_country()
+            
+            else:
+                return {"success": False, "error": f"Unknown tool: {tool_name}"}
+        
+        except Exception as e:
+            logger.error(f"Tool execution error: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _create_app(self, name: str, description: str, icon_color: str = "blue") -> dict:
+        """Create a new custom app and activate it.
+        
+        Args:
+            name: Display name for the app.
+            description: Brief description for prompt generation.
+            icon_color: Icon background color.
+            
+        Returns:
+            Result dictionary with success status and app info.
+        """
+        if not name or not description:
+            return {"success": False, "error": "Name and description are required"}
+        
+        # Get API key for prompt generation
+        api_key = os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            return {"success": False, "error": "OpenAI API key not available"}
+        
+        try:
+            # Generate detailed system prompt
+            logger.info(f"🧠 Generating system prompt for: {name}")
+            system_prompt = await generate_system_prompt(description, name, api_key)
+            
+            # Create app data
+            app_id = str(uuid.uuid4())
+            now = datetime.utcnow().isoformat()
+            
+            app_data = {
+                "id": app_id,
+                "name": name,
+                "description": description,
+                "system_prompt": system_prompt,
+                "voice_id": "",  # Use default voice
+                "emotion_animations": {},  # Use default animations
+                "icon_color": icon_color,
+                "created_at": now,
+            }
+            
+            # Save to database
+            db = get_database()
+            created_app = await db.create_app(app_data)
+            
+            logger.info(f"✅ Created app: {name} ({app_id})")
+            
+            # Activate the new app
+            self._active_app = created_app
+            
+            # Notify personality change with enabled tools
+            if self.on_personality_change:
+                enabled_tools = created_app.get("enabled_tools", [])
+                self.on_personality_change(system_prompt, enabled_tools if enabled_tools else None)
+            
+            # Notify iOS
+            if self.on_app_change:
+                await self.on_app_change({
+                    "type": "app_activated",
+                    "app": created_app
+                })
+            
+            return {
+                "success": True,
+                "message": f"Created and activated '{name}'",
+                "app_name": name,
+                "app_id": app_id
+            }
+        
+        except Exception as e:
+            logger.error(f"Failed to create app: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _activate_app(self, app_name: str) -> dict:
+        """Activate an existing app by name.
+        
+        Args:
+            app_name: Name or partial name of the app to activate.
+            
+        Returns:
+            Result dictionary with success status.
+        """
+        if not app_name:
+            return {"success": False, "error": "App name is required"}
+        
+        try:
+            # Get all apps from database
+            db = get_database()
+            apps = await db.get_all_apps()
+            
+            if not apps:
+                return {"success": False, "error": "No custom apps found. Create one first!"}
+            
+            # Find best matching app
+            app = find_best_matching_app(apps, app_name)
+            
+            if not app:
+                app_names = [a["name"] for a in apps]
+                return {
+                    "success": False,
+                    "error": f"No app found matching '{app_name}'",
+                    "available_apps": app_names
+                }
+            
+            # Activate the app
+            self._active_app = app
+            
+            # Notify personality change with enabled tools
+            if self.on_personality_change:
+                enabled_tools = app.get("enabled_tools", [])
+                self.on_personality_change(
+                    app["system_prompt"],
+                    enabled_tools if enabled_tools else None
+                )
+            
+            # Notify iOS
+            if self.on_app_change:
+                await self.on_app_change({
+                    "type": "app_activated",
+                    "app": app
+                })
+            
+            logger.info(f"✅ Activated app: {app['name']}")
+            
+            return {
+                "success": True,
+                "message": f"Activated '{app['name']}'",
+                "app_name": app["name"]
+            }
+        
+        except Exception as e:
+            logger.error(f"Failed to activate app: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _deactivate_app(self) -> dict:
+        """Deactivate the current app and return to default personality.
+        
+        Returns:
+            Result dictionary with success status.
+        """
+        if not self._active_app:
+            return {
+                "success": True,
+                "message": "Already using default Reachy personality"
+            }
+        
+        app_name = self._active_app["name"]
+        self._active_app = None
+        
+        # Clear personality (return to default)
+        if self.on_personality_change:
+            self.on_personality_change(None)  # None signals default
+        
+        # Notify iOS
+        if self.on_app_change:
+            await self.on_app_change({
+                "type": "app_deactivated"
+            })
+        
+        logger.info(f"✅ Deactivated app: {app_name}")
+        
+        return {
+            "success": True,
+            "message": f"Deactivated '{app_name}'. Now using default Reachy personality."
+        }
+    
+    async def _list_apps(self) -> dict:
+        """List all available custom apps.
+        
+        Returns:
+            Result dictionary with list of apps.
+        """
+        try:
+            db = get_database()
+            apps = await db.get_all_apps()
+            
+            if not apps:
+                return {
+                    "success": True,
+                    "message": "No custom apps found. You can create one by asking me!",
+                    "apps": [],
+                    "count": 0
+                }
+            
+            # Simplify app data for the response
+            app_list = [
+                {
+                    "name": app["name"],
+                    "description": app["description"],
+                    "is_active": self._active_app and self._active_app["id"] == app["id"]
+                }
+                for app in apps
+            ]
+            
+            return {
+                "success": True,
+                "apps": app_list,
+                "count": len(apps),
+                "active_app": self._active_app["name"] if self._active_app else None
+            }
+        
+        except Exception as e:
+            logger.error(f"Failed to list apps: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _wake_up(self) -> dict:
+        """Wake up the robot by enabling motors.
+        
+        Returns:
+            Result dictionary with success status.
+        """
+        daemon_url = "http://localhost:8000"
+        
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(f"{daemon_url}/api/motors/set_mode/enabled")
+                response.raise_for_status()
+                result = response.json()
+                status_msg = result.get("status", "Motors enabled")
+                
+                logger.info(f"🌅 Robot waking up: {status_msg}")
+                
+                return {
+                    "success": True,
+                    "message": "I'm awake! Motors are now enabled.",
+                    "status": status_msg
+                }
+        
+        except httpx.HTTPStatusError as e:
+            try:
+                error_detail = e.response.json().get("detail", str(e))
+            except Exception:
+                error_detail = str(e)
+            logger.error(f"Failed to wake up: {error_detail}")
+            return {"success": False, "error": error_detail}
+        
+        except Exception as e:
+            logger.error(f"Failed to wake up: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _go_to_sleep(self) -> dict:
+        """Put the robot to sleep by disabling motors.
+        
+        Returns:
+            Result dictionary with success status.
+        """
+        daemon_url = "http://localhost:8000"
+        
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(f"{daemon_url}/api/motors/set_mode/disabled")
+                response.raise_for_status()
+                result = response.json()
+                status_msg = result.get("status", "Motors disabled")
+                
+                logger.info(f"🌙 Robot going to sleep: {status_msg}")
+                
+                return {
+                    "success": True,
+                    "message": "Going to sleep now. Motors are disabled. Goodnight!",
+                    "status": status_msg
+                }
+        
+        except httpx.HTTPStatusError as e:
+            try:
+                error_detail = e.response.json().get("detail", str(e))
+            except Exception:
+                error_detail = str(e)
+            logger.error(f"Failed to go to sleep: {error_detail}")
+            return {"success": False, "error": error_detail}
+        
+        except Exception as e:
+            logger.error(f"Failed to go to sleep: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _remember_user_name(self, name: str) -> dict:
+        """Store the user's name for personalized interactions.
+        
+        Args:
+            name: The user's name to remember.
+            
+        Returns:
+            Result dictionary with success status.
+        """
+        if not name or not name.strip():
+            return {"success": False, "error": "Name cannot be empty"}
+        
+        # Clean up the name (capitalize first letter, trim whitespace)
+        clean_name = name.strip().title()
+        
+        try:
+            db = get_database()
+            await db.set_user_setting("user_name", clean_name)
+            
+            logger.info(f"👤 Remembered user name: {clean_name}")
+            
+            return {
+                "success": True,
+                "message": f"Nice to meet you, {clean_name}! I'll remember your name.",
+                "name": clean_name
+            }
+        
+        except Exception as e:
+            logger.error(f"Failed to remember user name: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _get_user_name(self) -> dict:
+        """Retrieve the stored user name.
+        
+        Returns:
+            Result dictionary with the user's name if stored.
+        """
+        try:
+            db = get_database()
+            name = await db.get_user_setting("user_name")
+            
+            if name:
+                logger.info(f"👤 Retrieved user name: {name}")
+                return {
+                    "success": True,
+                    "name": name,
+                    "message": f"The user's name is {name}"
+                }
+            else:
+                return {
+                    "success": True,
+                    "name": None,
+                    "message": "I don't know the user's name yet"
+                }
+        
+        except Exception as e:
+            logger.error(f"Failed to get user name: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _remember_preferred_country(self, country: str) -> dict:
+        """Store the user's preferred country for timezone and localization.
+        
+        Args:
+            country: The user's country to remember.
+            
+        Returns:
+            Result dictionary with success status.
+        """
+        if not country or not country.strip():
+            return {"success": False, "error": "Country cannot be empty"}
+        
+        # Clean up the country name (capitalize properly)
+        clean_country = country.strip().title()
+        
+        # Check if we have a timezone mapping for this country
+        timezone = get_timezone_for_country(country)
+        
+        try:
+            db = get_database()
+            await db.set_user_setting("preferred_country", clean_country)
+            
+            logger.info(f"🌍 Remembered preferred country: {clean_country}")
+            
+            response = {
+                "success": True,
+                "message": f"Got it! I'll remember that you're in {clean_country}.",
+                "country": clean_country
+            }
+            
+            if timezone:
+                response["timezone"] = timezone
+                response["message"] += f" I'll use {timezone} for showing you the correct local time."
+            
+            return response
+        
+        except Exception as e:
+            logger.error(f"Failed to remember preferred country: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+    
+    async def _get_preferred_country(self) -> dict:
+        """Retrieve the stored preferred country.
+        
+        Returns:
+            Result dictionary with the user's country if stored.
+        """
+        try:
+            db = get_database()
+            country = await db.get_user_setting("preferred_country")
+            
+            if country:
+                timezone = get_timezone_for_country(country)
+                logger.info(f"🌍 Retrieved preferred country: {country}")
+                return {
+                    "success": True,
+                    "country": country,
+                    "timezone": timezone,
+                    "message": f"The user's preferred country is {country}"
+                }
+            else:
+                return {
+                    "success": True,
+                    "country": None,
+                    "timezone": None,
+                    "message": "I don't know the user's country yet"
+                }
+        
+        except Exception as e:
+            logger.error(f"Failed to get preferred country: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+
+
+# Global tools handler instance
+_tools_handler: Optional[AppToolsHandler] = None
+
+
+def get_tools_handler() -> AppToolsHandler:
+    """Get or create the global tools handler instance.
+    
+    Returns:
+        The AppToolsHandler singleton.
+    """
+    global _tools_handler
+    if _tools_handler is None:
+        _tools_handler = AppToolsHandler()
+    return _tools_handler
+

reachys_brain/audio_capture.py

@@ -0,0 +1,375 @@
+"""Audio capture service for microphone input on Reachy.
+
+Supports both real hardware (robot mode) and mock mode (cloud deployments).
+"""
+
+import asyncio
+import logging
+import threading
+from typing import Callable, Optional
+
+from .config import get_config
+
+try:
+    import numpy as np
+    NUMPY_AVAILABLE = True
+except ImportError:
+    NUMPY_AVAILABLE = False
+    np = None  # type: ignore
+
+try:
+    import sounddevice as sd
+    SOUNDDEVICE_AVAILABLE = True
+except ImportError:
+    SOUNDDEVICE_AVAILABLE = False
+    sd = None  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+# OpenAI Realtime expects 24kHz mono PCM16
+TARGET_SAMPLE_RATE = 24000
+TARGET_CHANNELS = 1
+CHUNK_DURATION_MS = 100  # Send audio in 100ms chunks
+CHUNK_SAMPLES = int(TARGET_SAMPLE_RATE * CHUNK_DURATION_MS / 1000)
+
+
+class AudioCaptureService:
+    """Service for capturing audio from the microphone.
+    
+    Captures audio from the default input device, resamples to 24kHz mono PCM16,
+    and streams chunks via a callback.
+    
+    In cloud mode, this service is disabled and returns mock data.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the audio capture service."""
+        config = get_config()
+        
+        # Check if audio capture is enabled
+        self._enabled = config.enable_audio_capture and SOUNDDEVICE_AVAILABLE and NUMPY_AVAILABLE
+        
+        if not self._enabled:
+            if config.is_cloud_mode:
+                logger.info("Audio capture disabled (cloud mode)")
+            elif not SOUNDDEVICE_AVAILABLE:
+                logger.warning("sounddevice not available - audio capture disabled")
+            elif not NUMPY_AVAILABLE:
+                logger.warning("numpy not available - audio capture disabled")
+        
+        self._stream = None
+        self._is_capturing = False
+        self._is_paused = False
+        
+        # Callback for audio chunks
+        self.on_audio_chunk: Optional[Callable[[bytes], None]] = None
+        
+        # Audio buffer for collecting samples
+        self._buffer = np.array([], dtype=np.int16)
+        self._lock = threading.Lock()
+        
+        # Detect available devices
+        self._input_device: Optional[int] = None
+        self._native_sample_rate: int = TARGET_SAMPLE_RATE
+        
+        if SOUNDDEVICE_AVAILABLE:
+            self._detect_input_device()
+    
+    def _detect_input_device(self) -> None:
+        """Detect the default input device and its sample rate."""
+        try:
+            devices = sd.query_devices()
+            
+            # Log all available devices for debugging
+            logger.info(f"🔍 Found {len(devices)} audio devices:")
+            for i, device in enumerate(devices):
+                if device.get("max_input_channels", 0) > 0:
+                    logger.info(
+                        f"  [{i}] INPUT: {device.get('name', 'Unknown')} "
+                        f"(channels: {device.get('max_input_channels')}, "
+                        f"rate: {device.get('default_samplerate')}Hz)"
+                    )
+            
+            # First, look for reachymini_audio_src specifically
+            for i, device in enumerate(devices):
+                if "reachymini_audio_src" in device.get("name", ""):
+                    self._input_device = i
+                    self._native_sample_rate = int(device.get("default_samplerate", 16000))
+                    logger.info(
+                        f"✅ Using Reachy microphone: {device.get('name', 'Unknown')} "
+                        f"at {self._native_sample_rate}Hz"
+                    )
+                    return
+            
+            logger.warning("⚠️ Reachy microphone (reachymini_audio_src) not found, trying fallbacks...")
+            
+            # Fallback to default input device
+            default_input = sd.default.device[0]
+            
+            if default_input is not None and default_input >= 0:
+                device_info = devices[default_input]
+                self._input_device = default_input
+                self._native_sample_rate = int(device_info.get("default_samplerate", 16000))
+                logger.info(
+                    f"Using fallback input device: {device_info.get('name', 'Unknown')} "
+                    f"at {self._native_sample_rate}Hz"
+                )
+            else:
+                # Try to find any input device
+                for i, device in enumerate(devices):
+                    if device.get("max_input_channels", 0) > 0:
+                        self._input_device = i
+                        self._native_sample_rate = int(device.get("default_samplerate", 16000))
+                        logger.info(
+                            f"Using fallback input device: {device.get('name', 'Unknown')} "
+                            f"at {self._native_sample_rate}Hz"
+                        )
+                        break
+                else:
+                    logger.error("❌ No input device found! Microphone will not work.")
+        
+        except Exception as e:
+            logger.error(f"❌ Error detecting input device: {e}", exc_info=True)
+    
+    @property
+    def is_available(self) -> bool:
+        """Check if audio capture is available."""
+        return SOUNDDEVICE_AVAILABLE and self._input_device is not None
+    
+    @property
+    def is_capturing(self) -> bool:
+        """Check if currently capturing audio."""
+        return self._is_capturing
+    
+    @property
+    def is_paused(self) -> bool:
+        """Check if capture is paused."""
+        return self._is_paused
+    
+    def _resample(self, audio: np.ndarray, orig_rate: int, target_rate: int) -> np.ndarray:
+        """Resample audio to target sample rate.
+        
+        Uses simple linear interpolation for speed.
+        For production, consider using scipy.signal.resample or librosa.
+        
+        Args:
+            audio: Input audio samples.
+            orig_rate: Original sample rate.
+            target_rate: Target sample rate.
+            
+        Returns:
+            Resampled audio samples.
+        """
+        if orig_rate == target_rate:
+            return audio
+        
+        # Calculate number of output samples
+        duration = len(audio) / orig_rate
+        num_samples = int(duration * target_rate)
+        
+        # Linear interpolation
+        x_orig = np.linspace(0, 1, len(audio))
+        x_new = np.linspace(0, 1, num_samples)
+        resampled = np.interp(x_new, x_orig, audio.astype(np.float32))
+        
+        return resampled.astype(np.int16)
+    
+    def _audio_callback(self, indata: np.ndarray, frames: int, time_info, status) -> None:
+        """Callback for audio stream.
+        
+        Called by sounddevice when audio data is available.
+        """
+        if status:
+            logger.warning(f"Audio status: {status}")
+        
+        if self._is_paused or not self.on_audio_chunk:
+            return
+        
+        try:
+            # Convert to int16 if needed
+            if indata.dtype == np.float32:
+                audio = (indata * 32767).astype(np.int16)
+            else:
+                audio = indata.astype(np.int16)
+            
+            # Convert to mono if stereo
+            if len(audio.shape) > 1 and audio.shape[1] > 1:
+                audio = audio.mean(axis=1).astype(np.int16)
+            else:
+                audio = audio.flatten()
+            
+            # Resample to target rate if needed
+            if self._native_sample_rate != TARGET_SAMPLE_RATE:
+                audio = self._resample(audio, self._native_sample_rate, TARGET_SAMPLE_RATE)
+            
+            # Add to buffer
+            with self._lock:
+                self._buffer = np.concatenate([self._buffer, audio])
+                
+                # Send chunks when we have enough samples
+                while len(self._buffer) >= CHUNK_SAMPLES:
+                    chunk = self._buffer[:CHUNK_SAMPLES]
+                    self._buffer = self._buffer[CHUNK_SAMPLES:]
+                    
+                    # Convert to bytes and send
+                    chunk_bytes = chunk.tobytes()
+                    self.on_audio_chunk(chunk_bytes)
+        
+        except Exception as e:
+            logger.error(f"Error in audio callback: {e}")
+    
+    def start_capture(self) -> bool:
+        """Start capturing audio from the microphone.
+        
+        Returns:
+            True if capture started successfully.
+        """
+        if not self.is_available:
+            logger.error("❌ Audio capture not available - no input device detected")
+            return False
+        
+        if self._is_capturing:
+            logger.warning("Already capturing audio")
+            return True
+        
+        try:
+            # Calculate block size for native sample rate
+            block_size = int(self._native_sample_rate * CHUNK_DURATION_MS / 1000)
+            
+            logger.info(
+                f"🎙️ Opening audio stream: device={self._input_device}, "
+                f"rate={self._native_sample_rate}Hz, blocksize={block_size}"
+            )
+            
+            self._stream = sd.InputStream(
+                device=self._input_device,
+                channels=1,
+                samplerate=self._native_sample_rate,
+                dtype=np.int16,
+                blocksize=block_size,
+                callback=self._audio_callback,
+            )
+            
+            self._buffer = np.array([], dtype=np.int16)
+            self._stream.start()
+            self._is_capturing = True
+            self._is_paused = False
+            
+            logger.info("✅ Audio capture started successfully")
+            return True
+        
+        except Exception as e:
+            logger.error(f"❌ Failed to start audio capture: {e}", exc_info=True)
+            return False
+    
+    def stop_capture(self) -> None:
+        """Stop capturing audio."""
+        if not self._is_capturing:
+            return
+        
+        try:
+            if self._stream:
+                self._stream.stop()
+                self._stream.close()
+                self._stream = None
+            
+            self._is_capturing = False
+            self._is_paused = False
+            self._buffer = np.array([], dtype=np.int16)
+            
+            logger.info("Stopped audio capture")
+        
+        except Exception as e:
+            logger.error(f"Error stopping audio capture: {e}")
+    
+    def pause_capture(self) -> None:
+        """Pause audio capture (stop sending chunks).
+        
+        Use this when the robot is speaking to prevent feedback.
+        """
+        self._is_paused = True
+        logger.debug("Paused audio capture")
+    
+    def resume_capture(self) -> None:
+        """Resume audio capture after pausing."""
+        self._is_paused = False
+        # Clear buffer to avoid sending stale audio
+        with self._lock:
+            self._buffer = np.array([], dtype=np.int16)
+        logger.debug("Resumed audio capture")
+    
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        self.stop_capture()
+
+
+class AsyncAudioCaptureService:
+    """Async wrapper for AudioCaptureService.
+    
+    Provides async methods and uses asyncio queue for audio chunks.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the async audio capture service."""
+        self._capture = AudioCaptureService()
+        self._audio_queue: asyncio.Queue[bytes] = asyncio.Queue()
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        
+        # Wire up callback
+        self._capture.on_audio_chunk = self._on_chunk
+    
+    def _on_chunk(self, chunk: bytes) -> None:
+        """Handle audio chunk from capture service."""
+        if self._loop:
+            self._loop.call_soon_threadsafe(
+                self._audio_queue.put_nowait, chunk
+            )
+    
+    @property
+    def is_available(self) -> bool:
+        """Check if audio capture is available."""
+        return self._capture.is_available
+    
+    @property
+    def is_capturing(self) -> bool:
+        """Check if currently capturing."""
+        return self._capture.is_capturing
+    
+    async def start_capture(self) -> bool:
+        """Start capturing audio."""
+        self._loop = asyncio.get_event_loop()
+        return self._capture.start_capture()
+    
+    def stop_capture(self) -> None:
+        """Stop capturing audio."""
+        self._capture.stop_capture()
+    
+    def pause_capture(self) -> None:
+        """Pause audio capture."""
+        self._capture.pause_capture()
+    
+    def resume_capture(self) -> None:
+        """Resume audio capture."""
+        self._capture.resume_capture()
+    
+    async def get_audio_chunk(self, timeout: float = 0.5) -> Optional[bytes]:
+        """Get the next audio chunk.
+        
+        Args:
+            timeout: Maximum time to wait for a chunk.
+            
+        Returns:
+            Audio chunk bytes, or None if timeout.
+        """
+        try:
+            return await asyncio.wait_for(
+                self._audio_queue.get(),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            return None
+    
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        self._capture.cleanup()
+

reachys_brain/audio_playback.py

@@ -0,0 +1,332 @@
+"""Audio playback service for OpenAI Realtime audio output on Reachy."""
+
+import asyncio
+import logging
+import shutil
+import subprocess
+import threading
+from queue import Empty, Queue
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# OpenAI Realtime outputs 24kHz mono PCM16
+SAMPLE_RATE = 24000
+CHANNELS = 1
+SAMPLE_WIDTH = 2  # 16-bit = 2 bytes
+
+# Reachy audio device
+AUDIO_DEVICE = "plug:reachymini_audio_sink"
+
+# Playback timing
+STOP_DELAY_SECONDS = 0.3  # Delay before stopping to allow buffer to drain
+
+# Kids mode pitch shift (in cents, 400 = ~1/3 octave higher)
+KIDS_MODE_PITCH_CENTS = 400
+
+
+# Global kids mode state
+_kids_mode_enabled = False
+
+
+def is_kids_mode_enabled() -> bool:
+    """Check if kids mode (pitch shifting) is enabled."""
+    return _kids_mode_enabled
+
+
+def set_kids_mode(enabled: bool) -> None:
+    """Enable or disable kids mode (pitch shifting).
+    
+    Args:
+        enabled: True to enable kids mode, False to disable.
+    """
+    global _kids_mode_enabled
+    _kids_mode_enabled = enabled
+    logger.info(f"🧒 Kids mode {'enabled' if enabled else 'disabled'}")
+
+
+class AudioPlaybackService:
+    """Service for playing PCM16 audio from OpenAI on Reachy's speaker.
+    
+    Uses aplay for low-latency streaming playback. Audio chunks are
+    queued and played in order to maintain continuous playback.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the audio playback service."""
+        self._audio_queue: Queue[bytes] = Queue()
+        self._is_playing = False
+        self._playback_thread: Optional[threading.Thread] = None
+        self._process: Optional[subprocess.Popen] = None
+        self._stop_event = threading.Event()
+    
+    @property
+    def is_playing(self) -> bool:
+        """Check if currently playing audio."""
+        return self._is_playing
+    
+    def start_playback(self) -> None:
+        """Start the audio playback pipeline.
+        
+        Creates an aplay process ready to receive audio data.
+        """
+        if self._is_playing:
+            logger.warning("Playback already started")
+            return
+        
+        self._stop_event.clear()
+        self._is_playing = True
+        
+        # Start playback thread
+        self._playback_thread = threading.Thread(
+            target=self._playback_loop,
+            daemon=True,
+        )
+        self._playback_thread.start()
+        
+        logger.info("Started audio playback pipeline")
+    
+    def stop_playback(self) -> None:
+        """Stop the audio playback pipeline."""
+        if not self._is_playing:
+            return
+        
+        self._stop_event.set()
+        self._is_playing = False
+        
+        # Clear the queue
+        while not self._audio_queue.empty():
+            try:
+                self._audio_queue.get_nowait()
+            except Empty:
+                break
+        
+        # Wait for thread to finish
+        if self._playback_thread and self._playback_thread.is_alive():
+            self._playback_thread.join(timeout=2.0)
+        
+        self._playback_thread = None
+        
+        logger.info("Stopped audio playback pipeline")
+    
+    def enqueue_audio(self, audio_data: bytes) -> None:
+        """Add audio data to the playback queue.
+        
+        Args:
+            audio_data: PCM16 audio data at 24kHz mono.
+        """
+        if not self._is_playing:
+            logger.warning("Playback not started, dropping audio")
+            return
+        
+        self._audio_queue.put(audio_data)
+    
+    def clear_queue(self) -> None:
+        """Clear any pending audio in the queue."""
+        while not self._audio_queue.empty():
+            try:
+                self._audio_queue.get_nowait()
+            except Empty:
+                break
+    
+    def _playback_loop(self) -> None:
+        """Main playback loop running in a separate thread.
+        
+        Continuously reads from the queue and writes to aplay.
+        Uses sox for pitch shifting when kids mode is enabled.
+        """
+        sox_process: Optional[subprocess.Popen] = None
+        
+        try:
+            # Check if kids mode is enabled and sox is available
+            use_pitch_shift = _kids_mode_enabled and shutil.which("sox") is not None
+            
+            if _kids_mode_enabled and not shutil.which("sox"):
+                logger.warning("🧒 Kids mode enabled but sox not found, using normal playback")
+            
+            # aplay command for final output
+            aplay_cmd = [
+                "aplay",
+                "-r", str(SAMPLE_RATE),
+                "-f", "S16_LE",  # 16-bit signed little-endian
+                "-t", "raw",
+                "-c", str(CHANNELS),
+                "-D", AUDIO_DEVICE,
+                "-q",  # Quiet mode
+            ]
+            
+            if use_pitch_shift:
+                # sox command for pitch shifting
+                # Input: raw PCM16 24kHz mono from stdin
+                # Output: raw PCM16 24kHz mono to stdout (piped to aplay)
+                sox_cmd = [
+                    "sox",
+                    "-t", "raw",           # Input format: raw
+                    "-r", str(SAMPLE_RATE),  # Input sample rate
+                    "-e", "signed",        # Input encoding: signed
+                    "-b", "16",            # Input bits: 16
+                    "-c", str(CHANNELS),   # Input channels: mono
+                    "-",                   # Input from stdin
+                    "-t", "raw",           # Output format: raw
+                    "-",                   # Output to stdout
+                    "pitch", str(KIDS_MODE_PITCH_CENTS),  # Pitch shift up
+                ]
+                
+                # Start sox process (reads from stdin, outputs to stdout)
+                sox_process = subprocess.Popen(
+                    sox_cmd,
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                )
+                
+                # Start aplay process (reads from sox stdout)
+                self._process = subprocess.Popen(
+                    aplay_cmd,
+                    stdin=sox_process.stdout,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                )
+                
+                # Close sox stdout in parent so aplay gets EOF when sox closes
+                if sox_process.stdout:
+                    sox_process.stdout.close()
+                
+                logger.info(f"🧒 Started kids mode playback with pitch shift +{KIDS_MODE_PITCH_CENTS} cents")
+            else:
+                # Normal playback without pitch shifting
+                self._process = subprocess.Popen(
+                    aplay_cmd,
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                )
+                logger.debug(f"Started aplay process: {' '.join(aplay_cmd)}")
+            
+            # Determine which process stdin to write to
+            write_stdin = sox_process.stdin if sox_process else self._process.stdin
+            
+            while not self._stop_event.is_set():
+                try:
+                    # Get audio from queue with timeout
+                    audio_data = self._audio_queue.get(timeout=0.1)
+                    
+                    # Write to sox (if pitch shifting) or aplay directly
+                    if write_stdin:
+                        write_stdin.write(audio_data)
+                        write_stdin.flush()
+                
+                except Empty:
+                    # No audio available, continue waiting
+                    continue
+                except BrokenPipeError:
+                    logger.error("Audio pipe broken, restarting...")
+                    break
+                except Exception as e:
+                    logger.error(f"Error in playback loop: {e}")
+                    break
+        
+        except Exception as e:
+            logger.error(f"Error starting audio playback: {e}")
+        
+        finally:
+            # Clean up sox process if used
+            if sox_process:
+                try:
+                    if sox_process.stdin:
+                        sox_process.stdin.close()
+                    sox_process.terminate()
+                    sox_process.wait(timeout=1.0)
+                except Exception as e:
+                    logger.error(f"Error cleaning up sox: {e}")
+                    try:
+                        sox_process.kill()
+                    except Exception:
+                        pass
+            
+            # Clean up aplay process
+            if self._process:
+                try:
+                    if self._process.stdin:
+                        self._process.stdin.close()
+                    self._process.terminate()
+                    self._process.wait(timeout=1.0)
+                except Exception as e:
+                    logger.error(f"Error cleaning up aplay: {e}")
+                    try:
+                        self._process.kill()
+                    except Exception:
+                        pass
+                self._process = None
+    
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        self.stop_playback()
+
+
+class StreamingAudioPlayer:
+    """High-level audio player for streaming OpenAI audio.
+    
+    Manages the playback lifecycle and provides simple methods
+    for streaming audio chunks.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the streaming player."""
+        self._playback = AudioPlaybackService()
+        self._is_stream_active = False
+    
+    @property
+    def is_playing(self) -> bool:
+        """Check if audio stream is active."""
+        return self._is_stream_active
+    
+    def start_stream(self) -> None:
+        """Start a new audio stream.
+        
+        Call this when OpenAI starts sending audio.
+        """
+        if not self._is_stream_active:
+            self._playback.start_playback()
+            self._is_stream_active = True
+            logger.info("Started audio stream")
+    
+    def stop_stream(self) -> None:
+        """Stop the current audio stream.
+        
+        Call this when OpenAI stops sending audio.
+        """
+        if self._is_stream_active:
+            # Give a small delay to let remaining audio play
+            threading.Timer(STOP_DELAY_SECONDS, self._stop_delayed).start()
+    
+    def _stop_delayed(self) -> None:
+        """Delayed stop to allow audio buffer to drain."""
+        self._playback.stop_playback()
+        self._is_stream_active = False
+        logger.info("Stopped audio stream")
+    
+    def play_chunk(self, audio_data: bytes) -> None:
+        """Play an audio chunk.
+        
+        Automatically starts the stream if not active.
+        
+        Args:
+            audio_data: PCM16 audio data at 24kHz mono.
+        """
+        if not self._is_stream_active:
+            self.start_stream()
+        
+        self._playback.enqueue_audio(audio_data)
+    
+    def cancel(self) -> None:
+        """Immediately stop playback and clear queue."""
+        self._playback.clear_queue()
+        self._playback.stop_playback()
+        self._is_stream_active = False
+        logger.info("Cancelled audio stream")
+    
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        self._playback.cleanup()
+

reachys_brain/config.py

@@ -0,0 +1,100 @@
+"""Configuration module for Reachy iOS Bridge.
+
+Centralizes all configuration options and supports both robot and cloud deployments.
+Environment variables control the behavior.
+"""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    """Application configuration loaded from environment variables."""
+
+    # Server settings
+    host: str = "0.0.0.0"
+    port: int = 8080
+
+    # Deployment mode
+    # "robot" - Full functionality with Reachy hardware
+    # "cloud" - API-only mode without hardware dependencies (for HF Spaces)
+    mode: str = "cloud"
+
+    # Reachy daemon URL (only used in robot mode)
+    daemon_url: str = "http://localhost:8000"
+
+    # Audio device names (only used in robot mode)
+    audio_input_device: str = "reachymini_audio_src"
+    audio_output_device: str = "plug:reachymini_audio_sink"
+
+    # Database path (None = use default ~/.reachy/reachy_bridge.db)
+    database_path: str | None = None
+
+    # OpenAI settings
+    openai_api_key: str | None = None
+
+    # Feature flags
+    enable_audio_capture: bool = False
+    enable_audio_playback: bool = False
+    enable_motion: bool = False
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        """Load configuration from environment variables."""
+        mode = os.environ.get("REACHY_MODE", "cloud").lower()
+        is_robot_mode = mode == "robot"
+
+        return cls(
+            host=os.environ.get("HOST", "0.0.0.0"),
+            port=int(os.environ.get("PORT", "8080")),
+            mode=mode,
+            daemon_url=os.environ.get("REACHY_DAEMON_URL", "http://localhost:8000"),
+            audio_input_device=os.environ.get(
+                "AUDIO_INPUT_DEVICE", "reachymini_audio_src"
+            ),
+            audio_output_device=os.environ.get(
+                "AUDIO_OUTPUT_DEVICE", "plug:reachymini_audio_sink"
+            ),
+            database_path=os.environ.get("DATABASE_PATH"),
+            openai_api_key=os.environ.get("OPENAI_API_KEY"),
+            # Features are enabled only in robot mode by default
+            enable_audio_capture=is_robot_mode
+            or os.environ.get("ENABLE_AUDIO_CAPTURE", "").lower() == "true",
+            enable_audio_playback=is_robot_mode
+            or os.environ.get("ENABLE_AUDIO_PLAYBACK", "").lower() == "true",
+            enable_motion=is_robot_mode
+            or os.environ.get("ENABLE_MOTION", "").lower() == "true",
+        )
+
+    @property
+    def is_robot_mode(self) -> bool:
+        """Check if running in robot mode with hardware."""
+        return self.mode == "robot"
+
+    @property
+    def is_cloud_mode(self) -> bool:
+        """Check if running in cloud/API-only mode."""
+        return self.mode == "cloud"
+
+
+# Global configuration instance
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get the global configuration instance.
+
+    Loads from environment on first call.
+    """
+    global _config
+    if _config is None:
+        _config = Config.from_env()
+    return _config
+
+
+def reset_config() -> None:
+    """Reset configuration (useful for testing)."""
+    global _config
+    _config = None
+

reachys_brain/daemon_health_monitor.py

@@ -0,0 +1,414 @@
+"""Daemon health monitor with auto-recovery for channel closed errors.
+
+This module monitors the Reachy daemon status and automatically
+recovers from critical errors like "channel closed" which occur
+when the motor controller communication fails.
+
+Recovery Strategy:
+1. Light recovery (~5s): Uses /api/daemon/restart to restart just the backend
+2. Full recovery (~15-20s): Restarts the reachy-mini-daemon systemd service
+
+Light recovery is tried first and works for most channel errors.
+Full recovery is used as a fallback when light recovery fails.
+"""
+
+import asyncio
+import logging
+import subprocess
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Callable, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Daemon API URL
+DAEMON_URL = "http://localhost:8000"
+
+# Health check interval in seconds
+HEALTH_CHECK_INTERVAL = 5.0
+
+# Minimum time between recovery attempts (prevent rapid restart loops)
+MIN_RECOVERY_INTERVAL = timedelta(seconds=30)
+
+# Maximum consecutive failures before giving up
+MAX_RECOVERY_ATTEMPTS = 3
+
+
+class DaemonState(str, Enum):
+    """Daemon health states."""
+    HEALTHY = "healthy"
+    ERROR = "error"
+    RECOVERING = "recovering"
+    NOT_INITIALIZED = "not_initialized"
+    UNKNOWN = "unknown"
+
+
+class DaemonHealthMonitor:
+    """Monitors daemon health and auto-recovers from errors.
+    
+    This service runs in the background, periodically checking the
+    daemon status. When it detects a "channel closed" error (or similar
+    critical motor communication errors), it automatically triggers
+    a recovery sequence.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the health monitor."""
+        self._running = False
+        self._task: Optional[asyncio.Task] = None
+        self._state = DaemonState.UNKNOWN
+        self._last_error: Optional[str] = None
+        self._last_recovery_attempt: Optional[datetime] = None
+        self._consecutive_failures = 0
+        self._recovery_in_progress = False
+        
+        # Callback for state changes
+        self.on_state_change: Optional[Callable[[DaemonState, Optional[str]], None]] = None
+        self.on_recovery_started: Optional[Callable[[], None]] = None
+        self.on_recovery_completed: Optional[Callable[[bool, str], None]] = None
+    
+    @property
+    def state(self) -> DaemonState:
+        """Current daemon state."""
+        return self._state
+    
+    @property
+    def last_error(self) -> Optional[str]:
+        """Last error message from daemon."""
+        return self._last_error
+    
+    @property
+    def is_recovering(self) -> bool:
+        """Check if recovery is in progress."""
+        return self._recovery_in_progress
+    
+    def start(self) -> None:
+        """Start the health monitor."""
+        if self._running:
+            return
+        
+        self._running = True
+        self._task = asyncio.create_task(self._monitor_loop())
+        logger.info("🏥 Daemon health monitor started")
+    
+    def stop(self) -> None:
+        """Stop the health monitor."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            self._task = None
+        logger.info("🏥 Daemon health monitor stopped")
+    
+    async def _monitor_loop(self) -> None:
+        """Main monitoring loop."""
+        while self._running:
+            try:
+                await self._check_health()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error in health monitor: {e}")
+            
+            await asyncio.sleep(HEALTH_CHECK_INTERVAL)
+    
+    async def _check_health(self) -> None:
+        """Check daemon health and trigger recovery if needed."""
+        if self._recovery_in_progress:
+            return
+        
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(f"{DAEMON_URL}/api/daemon/status")
+                response.raise_for_status()
+                status = response.json()
+        except httpx.ConnectError:
+            self._set_state(DaemonState.UNKNOWN, "Cannot connect to daemon")
+            # Daemon is completely offline - this is a critical error
+            await self._handle_critical_error("daemon offline - cannot connect")
+            return
+        except Exception as e:
+            self._set_state(DaemonState.UNKNOWN, str(e))
+            return
+        
+        # Check for errors
+        error = status.get("error")
+        state = status.get("state", "unknown")
+        backend_error = None
+        
+        if status.get("backend_status"):
+            backend_error = status["backend_status"].get("error")
+        
+        # Determine health state
+        if state == "not_initialized":
+            self._set_state(DaemonState.NOT_INITIALIZED, None)
+            self._consecutive_failures = 0
+        elif error or backend_error:
+            error_msg = error or backend_error
+            self._set_state(DaemonState.ERROR, error_msg)
+            
+            # Check if this is a critical error that needs recovery
+            if self._is_critical_error(error_msg):
+                await self._handle_critical_error(error_msg)
+        elif state == "running":
+            self._set_state(DaemonState.HEALTHY, None)
+            self._consecutive_failures = 0
+        else:
+            self._set_state(DaemonState.UNKNOWN, f"Unknown state: {state}")
+    
+    def _set_state(self, state: DaemonState, error: Optional[str]) -> None:
+        """Update state and notify callbacks."""
+        if state != self._state or error != self._last_error:
+            old_state = self._state
+            self._state = state
+            self._last_error = error
+            
+            if state == DaemonState.ERROR:
+                logger.warning(f"🔴 Daemon health: {state.value} - {error}")
+            elif state == DaemonState.HEALTHY and old_state == DaemonState.ERROR:
+                logger.info(f"🟢 Daemon health: recovered!")
+            
+            if self.on_state_change:
+                self.on_state_change(state, error)
+    
+    def _is_critical_error(self, error: str) -> bool:
+        """Check if an error requires automatic recovery."""
+        critical_errors = [
+            "channel closed",
+            "backend not running",
+            "control loop crashed",
+            "motor communication failed",
+            "daemon offline",  # Daemon completely unreachable
+        ]
+        error_lower = error.lower()
+        return any(crit in error_lower for crit in critical_errors)
+    
+    async def _handle_critical_error(self, error: str) -> None:
+        """Handle a critical error by triggering recovery."""
+        # Check if we've exceeded max attempts
+        if self._consecutive_failures >= MAX_RECOVERY_ATTEMPTS:
+            logger.error(
+                f"❌ Max recovery attempts ({MAX_RECOVERY_ATTEMPTS}) exceeded. "
+                "Manual intervention required."
+            )
+            return
+        
+        # Check minimum interval between recoveries
+        if self._last_recovery_attempt:
+            time_since_last = datetime.now() - self._last_recovery_attempt
+            if time_since_last < MIN_RECOVERY_INTERVAL:
+                remaining = (MIN_RECOVERY_INTERVAL - time_since_last).seconds
+                logger.debug(
+                    f"Waiting {remaining}s before next recovery attempt"
+                )
+                return
+        
+        logger.warning(f"🔧 Critical error detected: {error}")
+        logger.info("🔄 Starting automatic recovery...")
+        
+        self._consecutive_failures += 1
+        await self.trigger_recovery()
+    
+    async def trigger_light_recovery(self) -> tuple[bool, str]:
+        """Try a light recovery using the daemon's built-in restart.
+        
+        This is faster than a full systemd restart and works for many
+        channel errors. It uses /api/daemon/restart which restarts
+        just the backend process without restarting the entire service.
+        
+        Returns:
+            Tuple of (success, message).
+        """
+        logger.info("🔄 Attempting light recovery via daemon restart...")
+        
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                # Try the daemon's built-in restart endpoint
+                response = await client.post(f"{DAEMON_URL}/api/daemon/restart")
+                
+                if response.status_code not in (200, 202):
+                    logger.warning(f"Light recovery failed: HTTP {response.status_code}")
+                    return False, f"Daemon restart returned {response.status_code}"
+            
+            # Wait for restart to complete
+            logger.info("⏳ Waiting for daemon to restart...")
+            await asyncio.sleep(5)
+            
+            # Poll until backend is ready
+            for attempt in range(10):
+                try:
+                    async with httpx.AsyncClient(timeout=3.0) as client:
+                        response = await client.get(f"{DAEMON_URL}/api/daemon/status")
+                        if response.status_code == 200:
+                            status = response.json()
+                            state = status.get("state", "unknown")
+                            error = status.get("error")
+                            backend_error = status.get("backend_status", {}).get("error")
+                            
+                            if state == "running" and not error and not backend_error:
+                                logger.info("✅ Light recovery successful!")
+                                return True, "Recovered via daemon restart"
+                            elif error or backend_error:
+                                # Error persists, light recovery didn't work
+                                logger.warning(f"Error persists after light recovery: {error or backend_error}")
+                                return False, f"Error persists: {error or backend_error}"
+                except Exception as e:
+                    logger.debug(f"Polling attempt {attempt + 1}: {e}")
+                await asyncio.sleep(1)
+            
+            return False, "Daemon did not become ready after restart"
+            
+        except httpx.ConnectError:
+            logger.warning("Cannot connect to daemon for light recovery")
+            return False, "Cannot connect to daemon"
+        except Exception as e:
+            logger.warning(f"Light recovery failed: {e}")
+            return False, str(e)
+    
+    async def trigger_recovery(self, force: bool = False, skip_light: bool = False) -> tuple[bool, str]:
+        """Trigger daemon recovery, trying light recovery first.
+        
+        Recovery strategy:
+        1. First try light recovery (daemon restart) - fast, ~5 seconds
+        2. If that fails, do full recovery (systemd restart) - slower, ~15-20 seconds
+        
+        Args:
+            force: If True, bypass the rate limiting checks.
+            skip_light: If True, skip light recovery and go straight to full.
+        
+        Returns:
+            Tuple of (success, message).
+        """
+        if self._recovery_in_progress and not force:
+            return False, "Recovery already in progress"
+        
+        self._recovery_in_progress = True
+        self._last_recovery_attempt = datetime.now()
+        self._set_state(DaemonState.RECOVERING, "Recovery in progress")
+        
+        if self.on_recovery_started:
+            self.on_recovery_started()
+        
+        try:
+            # Step 1: Try light recovery first (unless skipped)
+            if not skip_light:
+                success, message = await self.trigger_light_recovery()
+                if success:
+                    self._consecutive_failures = 0
+                    if self.on_recovery_completed:
+                        self.on_recovery_completed(True, message)
+                    return True, message
+                logger.info("Light recovery failed, trying full recovery...")
+            
+            # Step 2: Full recovery - restart systemd service
+            logger.info("📍 Step 1/3: Restarting reachy-mini-daemon service...")
+            result = await asyncio.get_event_loop().run_in_executor(
+                None,
+                lambda: subprocess.run(
+                    ["sudo", "systemctl", "restart", "reachy-mini-daemon"],
+                    capture_output=True,
+                    text=True,
+                    timeout=30
+                )
+            )
+            
+            if result.returncode != 0:
+                error_msg = f"Failed to restart service: {result.stderr}"
+                logger.error(error_msg)
+                return False, error_msg
+            
+            # Step 3: Wait for service to be ready
+            logger.info("📍 Step 2/3: Waiting for daemon to initialize...")
+            await asyncio.sleep(5)
+            
+            # Poll until daemon is responsive
+            for _ in range(10):
+                try:
+                    async with httpx.AsyncClient(timeout=3.0) as client:
+                        response = await client.get(f"{DAEMON_URL}/api/daemon/status")
+                        if response.status_code == 200:
+                            break
+                except Exception:
+                    pass
+                await asyncio.sleep(1)
+            
+            # Step 4: Start the daemon backend
+            logger.info("📍 Step 3/3: Starting daemon backend...")
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    f"{DAEMON_URL}/api/daemon/start",
+                    params={"wake_up": "true"}
+                )
+                
+                if response.status_code not in (200, 409):  # 409 = already running
+                    error_msg = f"Failed to start daemon: {response.text}"
+                    logger.error(error_msg)
+                    return False, error_msg
+            
+            # Wait for backend to be fully ready
+            await asyncio.sleep(3)
+            
+            # Verify recovery was successful
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(f"{DAEMON_URL}/api/daemon/status")
+                status = response.json()
+                
+                if status.get("error") or (
+                    status.get("backend_status", {}).get("error")
+                ):
+                    error_msg = status.get("error") or status["backend_status"]["error"]
+                    logger.error(f"Recovery incomplete, error persists: {error_msg}")
+                    return False, f"Recovery incomplete: {error_msg}"
+            
+            logger.info("✅ Full recovery completed successfully!")
+            self._consecutive_failures = 0
+            
+            if self.on_recovery_completed:
+                self.on_recovery_completed(True, "Recovery completed successfully")
+            
+            return True, "Motor controllers recovered successfully"
+            
+        except asyncio.TimeoutError:
+            error_msg = "Recovery timed out"
+            logger.error(error_msg)
+            if self.on_recovery_completed:
+                self.on_recovery_completed(False, error_msg)
+            return False, error_msg
+            
+        except Exception as e:
+            error_msg = f"Recovery failed: {str(e)}"
+            logger.error(error_msg, exc_info=True)
+            if self.on_recovery_completed:
+                self.on_recovery_completed(False, error_msg)
+            return False, error_msg
+            
+        finally:
+            self._recovery_in_progress = False
+
+
+# Global instance
+_health_monitor: Optional[DaemonHealthMonitor] = None
+
+
+def get_health_monitor() -> DaemonHealthMonitor:
+    """Get or create the global health monitor instance."""
+    global _health_monitor
+    if _health_monitor is None:
+        _health_monitor = DaemonHealthMonitor()
+    return _health_monitor
+
+
+def start_health_monitor() -> DaemonHealthMonitor:
+    """Start the global health monitor."""
+    monitor = get_health_monitor()
+    monitor.start()
+    return monitor
+
+
+def stop_health_monitor() -> None:
+    """Stop the global health monitor."""
+    global _health_monitor
+    if _health_monitor:
+        _health_monitor.stop()
+

reachys_brain/database.py

@@ -0,0 +1,1620 @@
+"""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/idle_movement_service.py

@@ -0,0 +1,447 @@
+"""Idle movement service for subtle, life-like movements when Reachy is inactive.
+
+Makes smooth, random micro-movements at random intervals to give Reachy
+a more alive, natural presence when not engaged in conversation or animation.
+Includes subtle head movements and antenna twitches.
+"""
+
+import asyncio
+import logging
+import math
+import random
+import time
+from typing import Optional, Callable
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+# Movement amplitude settings (in degrees) - very subtle for idle
+IDLE_AMPLITUDE = {
+    "head_roll": 4.0,      # Gentle side tilts
+    "head_pitch": 3.0,     # Slight nods
+    "head_yaw": 6.0,       # Small turns
+    "antenna_left": 15.0,  # Antenna range
+    "antenna_right": 15.0,
+}
+
+# Timing settings
+IDLE_UPDATE_RATE = 20  # Hz - smooth but not excessive
+IDLE_INTERVAL_RANGE = (5.0, 12.0)  # Seconds between movements - subtle but noticeable
+MOVEMENT_DURATION_RANGE = (1.5, 3.5)  # How long each movement takes
+ANTENNA_TWITCH_CHANCE = 0.3  # Chance of antenna movement with head movement
+
+# Base position (neutral)
+NEUTRAL_POSITION = {
+    "head_roll": 0.0,
+    "head_pitch": 0.0,
+    "head_yaw": 0.0,
+    "antenna_left": 0.0,
+    "antenna_right": 0.0,
+}
+
+
+def _ease_in_out(t: float) -> float:
+    """Smooth easing function for natural movement."""
+    return 0.5 * (1 - math.cos(math.pi * t))
+
+
+def _degrees_to_radians(degrees: float) -> float:
+    """Convert degrees to radians."""
+    return degrees * math.pi / 180.0
+
+
+class IdleMovement:
+    """Represents a single idle movement to perform."""
+    
+    def __init__(self):
+        """Generate a random idle movement."""
+        # Generate random head position within limits
+        self.head_roll = random.uniform(
+            -IDLE_AMPLITUDE["head_roll"],
+            IDLE_AMPLITUDE["head_roll"]
+        )
+        self.head_pitch = random.uniform(
+            -IDLE_AMPLITUDE["head_pitch"],
+            IDLE_AMPLITUDE["head_pitch"]
+        )
+        self.head_yaw = random.uniform(
+            -IDLE_AMPLITUDE["head_yaw"],
+            IDLE_AMPLITUDE["head_yaw"]
+        )
+        
+        # Sometimes move antennas too
+        if random.random() < ANTENNA_TWITCH_CHANCE:
+            self.antenna_left = random.uniform(
+                -IDLE_AMPLITUDE["antenna_left"],
+                IDLE_AMPLITUDE["antenna_left"]
+            )
+            self.antenna_right = random.uniform(
+                -IDLE_AMPLITUDE["antenna_right"],
+                IDLE_AMPLITUDE["antenna_right"]
+            )
+        else:
+            self.antenna_left = 0.0
+            self.antenna_right = 0.0
+        
+        # Movement duration
+        self.duration = random.uniform(*MOVEMENT_DURATION_RANGE)
+    
+    def to_dict(self) -> dict:
+        """Convert to position dict."""
+        return {
+            "head_roll": self.head_roll,
+            "head_pitch": self.head_pitch,
+            "head_yaw": self.head_yaw,
+            "antenna_left": self.antenna_left,
+            "antenna_right": self.antenna_right,
+        }
+
+
+class AntennaOnlyMovement:
+    """Represents an antenna-only twitch movement."""
+    
+    def __init__(self, current_head_pos: dict):
+        """Generate a random antenna movement while keeping head still.
+        
+        Args:
+            current_head_pos: Current head position to maintain.
+        """
+        # Keep head position stable
+        self.head_roll = current_head_pos.get("head_roll", 0.0)
+        self.head_pitch = current_head_pos.get("head_pitch", 0.0)
+        self.head_yaw = current_head_pos.get("head_yaw", 0.0)
+        
+        # Random antenna positions - sometimes asymmetric for personality
+        if random.random() < 0.5:
+            # Symmetric movement
+            angle = random.uniform(-15.0, 15.0)
+            self.antenna_left = angle
+            self.antenna_right = angle
+        else:
+            # Asymmetric - one antenna moves more
+            self.antenna_left = random.uniform(-15.0, 15.0)
+            self.antenna_right = random.uniform(-15.0, 15.0)
+        
+        # Quick antenna movements
+        self.duration = random.uniform(0.5, 1.2)
+    
+    def to_dict(self) -> dict:
+        """Convert to position dict."""
+        return {
+            "head_roll": self.head_roll,
+            "head_pitch": self.head_pitch,
+            "head_yaw": self.head_yaw,
+            "antenna_left": self.antenna_left,
+            "antenna_right": self.antenna_right,
+        }
+
+
+class IdleMovementService:
+    """Service for subtle, life-like idle movements.
+    
+    Runs in the background and periodically moves Reachy's head and
+    antennas to give a more alive, natural presence when idle.
+    
+    Automatically pauses when:
+    - Reachy is speaking
+    - An animation is playing
+    - A conversation is active
+    """
+    
+    def __init__(self, daemon_url: str = "http://localhost:8000"):
+        """Initialize the idle movement service.
+        
+        Args:
+            daemon_url: URL of the Reachy daemon API.
+        """
+        self._daemon_url = daemon_url
+        self._is_running = False
+        self._is_paused = False
+        self._idle_task: Optional[asyncio.Task] = None
+        
+        # Current and target positions
+        self._current_pos = NEUTRAL_POSITION.copy()
+        self._target_pos = NEUTRAL_POSITION.copy()
+        self._start_pos = NEUTRAL_POSITION.copy()
+        
+        # Movement timing
+        self._move_start_time = 0.0
+        self._move_duration = 1.0
+        
+        # Activity check callback
+        self._is_busy_callback: Optional[Callable[[], bool]] = None
+        
+        # HTTP client
+        self._client: Optional[httpx.AsyncClient] = None
+        
+        # Error rate limiting
+        self._last_error_time = 0.0
+        
+        logger.info(f"IdleMovementService initialized (daemon: {daemon_url})")
+    
+    def set_busy_callback(self, callback: Callable[[], bool]) -> None:
+        """Set callback to check if robot is busy.
+        
+        Args:
+            callback: Function that returns True if robot is busy.
+        """
+        self._is_busy_callback = callback
+    
+    @property
+    def is_running(self) -> bool:
+        """Check if idle movement service is running."""
+        return self._is_running
+    
+    @property
+    def is_paused(self) -> bool:
+        """Check if idle movements are currently paused."""
+        return self._is_paused
+    
+    def pause(self) -> None:
+        """Pause idle movements (e.g., during conversation)."""
+        if not self._is_paused:
+            self._is_paused = True
+            logger.debug("Idle movements paused")
+    
+    def resume(self) -> None:
+        """Resume idle movements."""
+        if self._is_paused:
+            self._is_paused = False
+            logger.debug("Idle movements resumed")
+    
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the async HTTP client."""
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                base_url=self._daemon_url,
+                timeout=2.0,
+            )
+        return self._client
+    
+    async def _goto_pose(
+        self,
+        head_roll: float,
+        head_pitch: float,
+        head_yaw: float,
+        antenna_left: float,
+        antenna_right: float,
+        duration: float,
+    ) -> bool:
+        """Send a goto command to smoothly move to target pose.
+        
+        Args:
+            head_roll: Head tilt in degrees.
+            head_pitch: Head nod in degrees.
+            head_yaw: Head turn in degrees.
+            antenna_left: Left antenna angle in degrees.
+            antenna_right: Right antenna angle in degrees.
+            duration: Movement duration in seconds.
+            
+        Returns:
+            True if successful.
+        """
+        try:
+            client = await self._get_client()
+            
+            payload = {
+                "head_pose": {
+                    "x": 0.0,
+                    "y": 0.0,
+                    "z": 0.0,
+                    "roll": _degrees_to_radians(head_roll),
+                    "pitch": _degrees_to_radians(head_pitch),
+                    "yaw": _degrees_to_radians(head_yaw),
+                },
+                "body_yaw": 0.0,
+                "antennas": [
+                    _degrees_to_radians(antenna_left),
+                    _degrees_to_radians(antenna_right),
+                ],
+                "duration": duration,
+                "interpolation": "minjerk",
+            }
+            
+            response = await client.post(
+                "/api/move/goto",
+                json=payload,
+            )
+            response.raise_for_status()
+            return True
+            
+        except Exception as e:
+            # Rate-limit error logging
+            now = time.time()
+            if now - self._last_error_time > 10.0:
+                logger.warning(f"Idle movement: Failed to goto pose: {e}")
+                self._last_error_time = now
+            return False
+    
+    def _interpolate_position(self) -> dict:
+        """Calculate current interpolated position."""
+        elapsed = time.time() - self._move_start_time
+        t = min(1.0, elapsed / self._move_duration)
+        
+        # Apply easing for smooth movement
+        eased_t = _ease_in_out(t)
+        
+        result = {}
+        for key in NEUTRAL_POSITION.keys():
+            start = self._start_pos.get(key, 0.0)
+            target = self._target_pos.get(key, 0.0)
+            result[key] = start + (target - start) * eased_t
+        
+        return result
+    
+    def _is_movement_complete(self) -> bool:
+        """Check if current movement is complete."""
+        elapsed = time.time() - self._move_start_time
+        return elapsed >= self._move_duration
+    
+    def _start_movement(self, target: dict, duration: float) -> None:
+        """Start a new movement toward target position.
+        
+        Args:
+            target: Target position dict.
+            duration: Movement duration in seconds.
+        """
+        self._start_pos = self._current_pos.copy()
+        self._target_pos = target.copy()
+        self._move_start_time = time.time()
+        self._move_duration = duration
+    
+    def _is_robot_busy(self) -> bool:
+        """Check if robot is currently busy (speaking, animating, etc.)."""
+        if self._is_busy_callback:
+            return self._is_busy_callback()
+        return False
+    
+    async def _idle_loop(self) -> None:
+        """Main idle movement loop."""
+        logger.info("🌙 Idle movement service started")
+        
+        next_movement_time = time.time() + random.uniform(3.0, 8.0)  # Start with a shorter initial wait
+        
+        try:
+            while self._is_running:
+                now = time.time()
+                
+                # Check if we should be idle
+                if self._is_paused or self._is_robot_busy():
+                    # Wait and check again
+                    await asyncio.sleep(0.5)
+                    # Reset movement timing when resuming
+                    next_movement_time = time.time() + random.uniform(2.0, 5.0)
+                    continue
+                
+                # Check if it's time for a new movement
+                if now >= next_movement_time:
+                    # Decide what kind of movement
+                    if random.random() < 0.3:
+                        # Antenna-only twitch
+                        movement = AntennaOnlyMovement(self._current_pos)
+                        logger.debug(f"🎭 Antenna twitch (duration: {movement.duration:.1f}s)")
+                    else:
+                        # Full idle movement
+                        movement = IdleMovement()
+                        logger.debug(f"🎭 Idle movement: roll={movement.head_roll:.1f}° pitch={movement.head_pitch:.1f}° yaw={movement.head_yaw:.1f}° (duration: {movement.duration:.1f}s)")
+                    
+                    # Send the goto command - daemon handles interpolation
+                    target = movement.to_dict()
+                    success = await self._goto_pose(
+                        head_roll=target["head_roll"],
+                        head_pitch=target["head_pitch"],
+                        head_yaw=target["head_yaw"],
+                        antenna_left=target["antenna_left"],
+                        antenna_right=target["antenna_right"],
+                        duration=movement.duration,
+                    )
+                    
+                    if success:
+                        # Update our tracked position
+                        self._current_pos = target.copy()
+                        # Wait for movement to complete
+                        await asyncio.sleep(movement.duration + 0.2)
+                    
+                    # Schedule next movement
+                    next_movement_time = time.time() + random.uniform(*IDLE_INTERVAL_RANGE)
+                    logger.debug(f"Next idle movement in {next_movement_time - time.time():.1f}s")
+                else:
+                    # Wait a bit before checking again
+                    await asyncio.sleep(0.5)
+        
+        except asyncio.CancelledError:
+            logger.debug("Idle movement loop cancelled")
+        except Exception as e:
+            logger.error(f"Error in idle movement loop: {e}")
+        finally:
+            # Return to neutral position on stop
+            await self._return_to_neutral()
+            logger.info("🌙 Idle movement service stopped")
+    
+    async def _return_to_neutral(self) -> None:
+        """Smoothly return to neutral position."""
+        await self._goto_pose(
+            head_roll=0.0,
+            head_pitch=0.0,
+            head_yaw=0.0,
+            antenna_left=0.0,
+            antenna_right=0.0,
+            duration=1.5,
+        )
+        self._current_pos = NEUTRAL_POSITION.copy()
+        await asyncio.sleep(1.5)
+    
+    async def start(self) -> None:
+        """Start the idle movement service."""
+        if self._is_running:
+            logger.debug("Idle movement service already running")
+            return
+        
+        self._is_running = True
+        self._is_paused = False
+        self._idle_task = asyncio.create_task(self._idle_loop())
+        logger.info("🌙 Idle movement service starting...")
+    
+    async def stop(self) -> None:
+        """Stop the idle movement service."""
+        if not self._is_running:
+            return
+        
+        self._is_running = False
+        
+        if self._idle_task:
+            self._idle_task.cancel()
+            try:
+                await self._idle_task
+            except asyncio.CancelledError:
+                pass
+            self._idle_task = None
+    
+    async def close(self) -> None:
+        """Clean up resources."""
+        await self.stop()
+        
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+        
+        logger.info("IdleMovementService closed")
+
+
+# Global singleton instance
+_idle_service: Optional[IdleMovementService] = None
+
+
+def get_idle_movement_service() -> Optional[IdleMovementService]:
+    """Get the global idle movement service instance."""
+    return _idle_service
+
+
+def set_idle_movement_service(service: IdleMovementService) -> None:
+    """Set the global idle movement service instance."""
+    global _idle_service
+    _idle_service = service
+    logger.info("Global IdleMovementService instance set")
+

reachys_brain/main.py

@@ -0,0 +1,147 @@
+"""Main entry point for the Reachy iOS Bridge app."""
+
+import logging
+import signal
+import sys
+import threading
+from typing import Any
+
+import uvicorn
+from reachy_mini import ReachyMini, ReachyMiniApp
+
+from .server import app, set_head_controller, set_reachy_connected
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class ReachyIosBridge(ReachyMiniApp):
+    """iOS Bridge app for Reachy Mini.
+    
+    Runs a FastAPI HTTP server that allows an iOS device to:
+    - Send text for text-to-speech
+    - Control head animations
+    - Query robot status
+    """
+
+    # Web interface for configuration (optional)
+    custom_app_url: str | None = None
+    
+    def __init__(self) -> None:
+        """Initialize the iOS Bridge app."""
+        super().__init__()
+        self._server_thread: threading.Thread | None = None
+        self._host = "0.0.0.0"
+        self._port = 8080
+    
+    def run(self, reachy_mini: ReachyMini | None, stop_event: threading.Event) -> None:
+        """Run the iOS Bridge server.
+        
+        Args:
+            reachy_mini: The connected ReachyMini instance (may be None if not connected).
+            stop_event: Event to signal when the app should stop.
+        """
+        logger.info("Starting Reachy iOS Bridge...")
+        logger.info(f"Server will be available at http://{self._host}:{self._port}")
+        
+        # Register Reachy with the server (only if we have a connection)
+        if reachy_mini is not None:
+            set_reachy_connected(True)
+            set_head_controller(reachy_mini)
+            logger.info("Reachy Mini connected - motion enabled")
+        else:
+            set_reachy_connected(False)
+            logger.warning("Reachy Mini not connected - motion disabled")
+        
+        # Configure uvicorn
+        config = uvicorn.Config(
+            app=app,
+            host=self._host,
+            port=self._port,
+            log_level="info",
+            access_log=True,
+        )
+        server = uvicorn.Server(config)
+        
+        # Run server in a thread so we can check stop_event
+        self._server_thread = threading.Thread(
+            target=server.run,
+            daemon=True,
+        )
+        self._server_thread.start()
+        
+        logger.info(f"iOS Bridge server started on port {self._port}")
+        logger.info("Waiting for iOS connections...")
+        
+        # Wait for stop event
+        try:
+            while not stop_event.is_set():
+                stop_event.wait(timeout=0.5)
+        except KeyboardInterrupt:
+            logger.info("Keyboard interrupt received")
+        
+        # Cleanup
+        logger.info("Stopping iOS Bridge server...")
+        set_reachy_connected(False)
+        
+        # Signal server to stop
+        server.should_exit = True
+        
+        if self._server_thread and self._server_thread.is_alive():
+            self._server_thread.join(timeout=2.0)
+        
+        logger.info("iOS Bridge stopped")
+
+
+def main() -> None:
+    """Run the iOS Bridge when called as a module by the daemon.
+    
+    This creates a ReachyMini instance and runs the bridge app.
+    """
+    logger.info("Starting Reachy iOS Bridge as module...")
+    
+    # Create stop event for graceful shutdown
+    stop_event = threading.Event()
+    
+    def signal_handler(signum, frame):
+        logger.info(f"Received signal {signum}, stopping...")
+        stop_event.set()
+    
+    # Register signal handlers
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    # Try to connect to Reachy Mini, but don't block if it fails
+    reachy_mini = None
+    try:
+        logger.info("Attempting to connect to Reachy Mini...")
+        # Use a timeout for connection
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(ReachyMini)
+            try:
+                reachy_mini = future.result(timeout=5.0)
+                logger.info("Connected to Reachy Mini!")
+            except concurrent.futures.TimeoutError:
+                logger.warning("Timeout connecting to Reachy Mini - motion will be disabled")
+            except Exception as e:
+                logger.warning(f"Could not connect to Reachy Mini: {e} - motion will be disabled")
+    except Exception as e:
+        logger.warning(f"Error during Reachy connection: {e}")
+    
+    # Create and run the bridge app
+    try:
+        bridge = ReachyIosBridge()
+        bridge.run(reachy_mini, stop_event)
+    except Exception as e:
+        logger.error(f"Error running bridge: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+

reachys_brain/models.py

@@ -0,0 +1,537 @@
+"""Pydantic models for API requests and responses."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class Emotion(str, Enum):
+    """Supported emotions for speech and motion."""
+    
+    NEUTRAL = "neutral"
+    HAPPY = "happy"
+    SAD = "sad"
+    SURPRISED = "surprised"
+    THINKING = "thinking"
+
+
+class SpeakRequest(BaseModel):
+    """Request body for the /speak endpoint."""
+    
+    text: str = Field(..., min_length=1, max_length=2000, description="Text to speak")
+    emotion: Emotion = Field(default=Emotion.NEUTRAL, description="Emotion for speech delivery")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "text": "Hello! How can I help you today?",
+                    "emotion": "happy"
+                }
+            ]
+        }
+    }
+
+
+class MotionRequest(BaseModel):
+    """Request body for the /motion endpoint."""
+    
+    animation: str = Field(..., description="Animation name to play")
+    duration: float = Field(default=2.0, ge=0.1, le=10.0, description="Duration in seconds")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "animation": "nod",
+                    "duration": 1.5
+                }
+            ]
+        }
+    }
+
+
+class RobotStatus(BaseModel):
+    """Response model for robot status."""
+    
+    connected: bool = Field(..., description="Whether Reachy is connected")
+    speaking: bool = Field(..., description="Whether Reachy is currently speaking")
+    animation_playing: bool = Field(..., description="Whether an animation is playing")
+    battery_level: float | None = Field(None, description="Battery level if available")
+
+
+class SpeakResponse(BaseModel):
+    """Response model for speak requests."""
+    
+    success: bool
+    message: str
+    duration_seconds: float | None = None
+
+
+class MotionResponse(BaseModel):
+    """Response model for motion requests."""
+    
+    success: bool
+    message: str
+    animation: str | None = None
+
+
+class StopResponse(BaseModel):
+    """Response model for stop requests."""
+    
+    success: bool
+    message: str
+
+
+class PowerAction(str, Enum):
+    """Power control actions for the robot."""
+    
+    WAKE = "wake"
+    SLEEP = "sleep"
+    REBOOT = "reboot"
+    REFLASH_MOTORS = "reflash_motors"
+
+
+class PowerControlResponse(BaseModel):
+    """Response model for power control requests."""
+    
+    success: bool
+    message: str
+    action: PowerAction
+
+
+class ReflashMotorsResponse(BaseModel):
+    """Response model for motor reflash operation."""
+    
+    success: bool
+    message: str
+    motors_reflashed: int = 0
+    details: Optional[str] = None
+
+
+# Voice/Language Models
+
+class Voice(BaseModel):
+    """A TTS voice option."""
+    
+    id: str = Field(..., description="Voice identifier (e.g., 'en-us', 'fr', 'de')")
+    name: str = Field(..., description="Human-readable voice name")
+    language: str = Field(..., description="Language code")
+
+
+class VoiceRequest(BaseModel):
+    """Request body for setting the voice."""
+    
+    voice_id: str = Field(..., description="Voice identifier to use")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {"voice_id": "en-us"}
+            ]
+        }
+    }
+
+
+class VoiceResponse(BaseModel):
+    """Response model for voice operations."""
+    
+    success: bool
+    current_voice: str
+    message: str | None = None
+
+
+class VoicesListResponse(BaseModel):
+    """Response model for listing available voices."""
+    
+    voices: list[Voice]
+    current_voice: str
+    preferred_language: str | None = None  # User's preferred language code
+
+
+class SupportedLanguage(BaseModel):
+    """A supported language option."""
+    
+    code: str = Field(..., description="Language code (e.g., 'en', 'nl', 'de')")
+    name: str = Field(..., description="Human-readable language name")
+    flag: str = Field(..., description="Flag emoji for the language")
+
+
+class PreferredLanguageResponse(BaseModel):
+    """Response model for preferred language operations."""
+    
+    success: bool | None = None
+    preferred_language: str
+    message: str | None = None
+    supported_languages: list[SupportedLanguage] | None = None
+
+
+# Joystick Control Models
+
+class HeadPoseRequest(BaseModel):
+    """Request body for setting head pose."""
+    
+    roll: float = Field(default=0.0, ge=-45.0, le=45.0, description="Head roll in degrees")
+    pitch: float = Field(default=0.0, ge=-40.0, le=30.0, description="Head pitch in degrees (negative=up)")
+    yaw: float = Field(default=0.0, ge=-60.0, le=60.0, description="Head yaw in degrees")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {"roll": 0.0, "pitch": -10.0, "yaw": 15.0}
+            ]
+        }
+    }
+
+
+class HeadPoseResponse(BaseModel):
+    """Response model for head pose operations."""
+    
+    success: bool
+    message: str
+    roll: float | None = None
+    pitch: float | None = None
+    yaw: float | None = None
+
+
+class BodyYawRequest(BaseModel):
+    """Request body for setting body yaw rotation."""
+    
+    yaw: float = Field(..., ge=-180.0, le=180.0, description="Body yaw in degrees")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {"yaw": 45.0}
+            ]
+        }
+    }
+
+
+class BodyYawResponse(BaseModel):
+    """Response model for body yaw operations."""
+    
+    success: bool
+    message: str
+    yaw: float | None = None
+
+
+class AntennaRequest(BaseModel):
+    """Request body for setting antenna positions."""
+    
+    left: float = Field(..., ge=-45.0, le=45.0, description="Left antenna angle in degrees")
+    right: float = Field(..., ge=-45.0, le=45.0, description="Right antenna angle in degrees")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {"left": 15.0, "right": -15.0}
+            ]
+        }
+    }
+
+
+class AntennaResponse(BaseModel):
+    """Response model for antenna operations."""
+    
+    success: bool
+    message: str
+    left: float | None = None
+    right: float | None = None
+
+
+class JoystickStateResponse(BaseModel):
+    """Combined state response for all joystick controls."""
+    
+    success: bool
+    head_roll: float
+    head_pitch: float
+    head_yaw: float
+    body_yaw: float
+    antenna_left: float
+    antenna_right: float
+
+
+# =============================================================================
+# Custom Apps Models
+# =============================================================================
+
+
+class CustomAppIconColor(str, Enum):
+    """Available icon colors for custom apps."""
+    
+    BLUE = "blue"
+    PURPLE = "purple"
+    PINK = "pink"
+    RED = "red"
+    ORANGE = "orange"
+    YELLOW = "yellow"
+    GREEN = "green"
+    TEAL = "teal"
+    INDIGO = "indigo"
+    GRAY = "gray"
+    BLACK = "black"
+
+
+class CustomAppBase(BaseModel):
+    """Base model for custom app data (shared by create/update)."""
+    
+    name: str = Field(..., min_length=1, max_length=100, description="App display name")
+    description: str = Field(default="", max_length=500, description="App description")
+    system_prompt: str = Field(..., min_length=1, description="AI system prompt")
+    voice_id: str = Field(default="", description="OpenAI voice ID")
+    emotion_animations: dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping of emotion names to animation names"
+    )
+    icon_color: CustomAppIconColor = Field(
+        default=CustomAppIconColor.BLUE,
+        description="Icon background color"
+    )
+    enabled_tools: list[str] = Field(
+        default_factory=list,
+        description="List of enabled tool IDs (e.g., 'weather', 'web_search')"
+    )
+
+
+class CustomAppCreate(CustomAppBase):
+    """Request model for creating a new custom app."""
+    
+    id: str = Field(..., description="UUID for the app (generated by iOS)")
+    created_at: Optional[str] = Field(None, description="ISO timestamp (optional)")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "id": "550e8400-e29b-41d4-a716-446655440000",
+                    "name": "Chef Assistant",
+                    "description": "A helpful cooking companion",
+                    "system_prompt": "You are a friendly chef...",
+                    "voice_id": "alloy",
+                    "emotion_animations": {
+                        "happy": "cheerful1",
+                        "thinking": "thoughtful1"
+                    },
+                    "icon_color": "orange"
+                }
+            ]
+        }
+    }
+
+
+class CustomAppUpdate(BaseModel):
+    """Request model for updating an existing custom app (all fields optional)."""
+    
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    description: Optional[str] = Field(None, max_length=500)
+    system_prompt: Optional[str] = Field(None, min_length=1)
+    voice_id: Optional[str] = None
+    emotion_animations: Optional[dict[str, str]] = None
+    icon_color: Optional[CustomAppIconColor] = None
+    enabled_tools: Optional[list[str]] = None
+
+
+class CustomApp(CustomAppBase):
+    """Full custom app model (response model)."""
+    
+    id: str = Field(..., description="UUID for the app")
+    created_at: str = Field(..., description="ISO timestamp of creation")
+    updated_at: str = Field(..., description="ISO timestamp of last update")
+    
+    model_config = {
+        "from_attributes": True
+    }
+
+
+class CustomAppResponse(BaseModel):
+    """Response wrapper for single app operations."""
+    
+    success: bool
+    app: Optional[CustomApp] = None
+    message: Optional[str] = None
+
+
+class CustomAppsListResponse(BaseModel):
+    """Response model for listing all custom apps."""
+    
+    success: bool
+    apps: list[CustomApp]
+    count: int
+
+
+class CustomAppsSyncRequest(BaseModel):
+    """Request model for bulk syncing apps from iOS."""
+    
+    apps: list[CustomAppCreate] = Field(..., description="List of apps to sync")
+
+
+class CustomAppsSyncResponse(BaseModel):
+    """Response model for sync operation."""
+    
+    success: bool
+    synced_count: int
+    apps: list[CustomApp]
+    message: Optional[str] = None
+
+
+# =============================================================================
+# Tool Models
+# =============================================================================
+
+
+class ToolInfo(BaseModel):
+    """Information about an available tool."""
+    
+    id: str = Field(..., description="Unique tool identifier")
+    name: str = Field(..., description="Display name for the tool")
+    description: str = Field(..., description="Brief description of what the tool does")
+    icon: str = Field(..., description="SF Symbol icon name for iOS")
+
+
+class ToolsListResponse(BaseModel):
+    """Response model for listing available tools."""
+    
+    success: bool
+    tools: list[ToolInfo]
+    count: int
+
+
+# =============================================================================
+# Custom Animation Models
+# =============================================================================
+
+
+class AnimationKeyframe(BaseModel):
+    """A single keyframe in a recorded animation."""
+    
+    timestamp: float = Field(..., ge=0.0, description="Time offset in milliseconds from animation start")
+    head_pitch: float = Field(default=0.0, description="Head pitch in degrees")
+    head_yaw: float = Field(default=0.0, description="Head yaw in degrees")
+    head_roll: float = Field(default=0.0, description="Head roll in degrees")
+    body_yaw: float = Field(default=0.0, description="Body yaw in degrees")
+    antenna_left: float = Field(default=0.0, description="Left antenna angle in degrees")
+    antenna_right: float = Field(default=0.0, description="Right antenna angle in degrees")
+
+
+class AnimationPose(BaseModel):
+    """A pose representing all robot positions (used for start/end poses)."""
+    
+    head_pitch: float = Field(default=0.0, description="Head pitch in degrees")
+    head_yaw: float = Field(default=0.0, description="Head yaw in degrees")
+    head_roll: float = Field(default=0.0, description="Head roll in degrees")
+    body_yaw: float = Field(default=0.0, description="Body yaw in degrees")
+    antenna_left: float = Field(default=0.0, description="Left antenna angle in degrees")
+    antenna_right: float = Field(default=0.0, description="Right antenna angle in degrees")
+
+
+class CustomAnimationBase(BaseModel):
+    """Base model for custom animation data."""
+    
+    name: str = Field(..., min_length=1, max_length=100, description="Animation display name")
+    description: str = Field(default="", max_length=500, description="Animation description")
+    duration_ms: int = Field(..., ge=100, description="Total animation duration in milliseconds")
+    start_pose: AnimationPose = Field(..., description="Initial robot pose before animation")
+    keyframes: list[AnimationKeyframe] = Field(..., description="List of recorded keyframes")
+    audio_data: Optional[str] = Field(
+        default=None, 
+        description="Base64-encoded audio data (M4A format) to play with animation"
+    )
+
+
+class CustomAnimationCreate(CustomAnimationBase):
+    """Request model for creating a new custom animation."""
+    
+    id: str = Field(..., description="UUID for the animation (generated by iOS)")
+    created_at: Optional[str] = Field(None, description="ISO timestamp (optional)")
+    
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "id": "550e8400-e29b-41d4-a716-446655440000",
+                    "name": "Wave Hello",
+                    "description": "A friendly greeting wave",
+                    "duration_ms": 3500,
+                    "start_pose": {
+                        "head_pitch": 0.0,
+                        "head_yaw": 0.0,
+                        "head_roll": 0.0,
+                        "body_yaw": 0.0,
+                        "antenna_left": 0.0,
+                        "antenna_right": 0.0
+                    },
+                    "keyframes": [
+                        {
+                            "timestamp": 0.0,
+                            "head_pitch": 0.0,
+                            "head_yaw": 10.0,
+                            "head_roll": 0.0,
+                            "body_yaw": 0.0,
+                            "antenna_left": 20.0,
+                            "antenna_right": 20.0
+                        }
+                    ]
+                }
+            ]
+        }
+    }
+
+
+class CustomAnimationUpdate(BaseModel):
+    """Request model for updating an existing custom animation (all fields optional)."""
+    
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    description: Optional[str] = Field(None, max_length=500)
+    duration_ms: Optional[int] = Field(None, ge=100)
+    start_pose: Optional[AnimationPose] = None
+    keyframes: Optional[list[AnimationKeyframe]] = None
+    audio_data: Optional[str] = Field(
+        None,
+        description="Base64-encoded audio data (M4A format) to play with animation"
+    )
+
+
+class CustomAnimation(CustomAnimationBase):
+    """Full custom animation model (response model)."""
+    
+    id: str = Field(..., description="UUID for the animation")
+    created_at: str = Field(..., description="ISO timestamp of creation")
+    updated_at: str = Field(..., description="ISO timestamp of last update")
+    
+    model_config = {
+        "from_attributes": True
+    }
+
+
+class CustomAnimationResponse(BaseModel):
+    """Response wrapper for single animation operations."""
+    
+    success: bool
+    animation: Optional[CustomAnimation] = None
+    message: Optional[str] = None
+
+
+class CustomAnimationsListResponse(BaseModel):
+    """Response model for listing all custom animations."""
+    
+    success: bool
+    animations: list[CustomAnimation]
+    count: int
+
+
+class AnimationPlayRequest(BaseModel):
+    """Request model for playing a custom animation."""
+    
+    speed: float = Field(default=1.0, ge=0.1, le=3.0, description="Playback speed multiplier")
+
+
+class AnimationPlayResponse(BaseModel):
+    """Response model for animation playback."""
+    
+    success: bool
+    message: str
+    animation_id: Optional[str] = None
+    duration_ms: Optional[int] = None

reachys_brain/motion_service.py

@@ -0,0 +1,214 @@
+"""Motion service using Reachy daemon's HTTP API for animations."""
+
+import logging
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+# Dances from reachy-mini-dances-library
+DANCES = [
+    "side_glance_flick", "jackson_square", "side_peekaboo", "groovy_sway_and_roll",
+    "chin_lead", "side_to_side_sway", "neck_recoil", "head_tilt_roll", "simple_nod",
+    "uh_huh_tilt", "interwoven_spirals", "pendulum_swing", "chicken_peck", "yeah_nod",
+    "stumble_and_recover", "dizzy_spin", "grid_snap", "polyrhythm_combo",
+]
+
+# Emotions from reachy-mini-emotions-library
+EMOTIONS = [
+    "fear1", "surprised1", "rage1", "resigned1", "go_away1", "loving1", "impatient1",
+    "enthusiastic2", "cheerful1", "laughing1", "surprised2", "irritated2", "impatient2",
+    "oops2", "enthusiastic1", "curious1", "electric1", "contempt1", "inquiring3",
+    "attentive2", "irritated1", "reprimand3", "frustrated1", "dance2", "no1", "sad2",
+    "understanding2", "come1", "calming1", "sad1", "exhausted1", "scared1", "downcast1",
+    "success1", "disgusted1", "amazed1", "displeased1", "laughing2", "dying1",
+    "no_excited1", "thoughtful2", "lonely1", "welcoming1", "no_sad1", "thoughtful1",
+    "welcoming2", "reprimand1", "attentive1", "boredom2", "boredom1", "inquiring1",
+    "grateful1", "uncertain1", "furious1", "anxiety1", "yes_sad1", "displeased2",
+    "proud1", "shy1", "indifferent1", "tired1", "serenity1", "proud3", "helpful2",
+    "dance1", "understanding1", "incomprehensible2", "relief1", "relief2", "confused1",
+    "success2", "sleep1", "inquiring2", "yes1", "dance3", "oops1", "helpful1",
+    "uncomfortable1", "reprimand2", "lost1", "proud2",
+]
+
+# Simple aliases that map to specific animations
+ALIASES = {
+    "nod": "simple_nod",
+    "shake": "side_to_side_sway",
+    "tilt": "head_tilt_roll",
+    "look_around": "side_glance_flick",
+    "happy": "cheerful1",
+    "sad": "sad1",
+    "surprised": "surprised1",
+    "thinking": "thoughtful1",
+    "idle": "serenity1",
+    "attention": "attentive1",
+}
+
+
+class MotionService:
+    """Service for playing head animations via Reachy daemon's HTTP API."""
+    
+    def __init__(self, daemon_url: str = "http://localhost:8000") -> None:
+        """Initialize the motion service.
+        
+        Args:
+            daemon_url: URL of the Reachy daemon API.
+        """
+        self._daemon_url = daemon_url
+        self._is_playing = False
+        self._current_animation: Optional[str] = None
+        self._client = httpx.Client(base_url=daemon_url, timeout=10.0)
+        logger.info(f"Motion service initialized with daemon URL: {daemon_url}")
+    
+    def set_controller(self, controller) -> None:
+        """Set head controller (not used - we use HTTP API instead)."""
+        pass
+    
+    @property
+    def is_playing(self) -> bool:
+        """Check if an animation is currently playing."""
+        return self._is_playing
+    
+    def get_available_animations(self) -> dict:
+        """Get all available animations organized by category.
+        
+        Returns:
+            Dict with 'dances', 'emotions', and 'aliases' lists.
+        """
+        return {
+            "dances": DANCES,
+            "emotions": EMOTIONS,
+            "aliases": list(ALIASES.keys()),
+        }
+    
+    def get_all_animation_names(self) -> list[str]:
+        """Get flat list of all animation names.
+        
+        Returns:
+            List of all animation names.
+        """
+        all_names = set(DANCES + EMOTIONS + list(ALIASES.keys()))
+        return sorted(list(all_names))
+    
+    def _resolve_animation(self, animation: str) -> tuple[str, str]:
+        """Resolve animation name to library and actual name.
+        
+        Args:
+            animation: Animation name (can be alias, dance, or emotion).
+            
+        Returns:
+            Tuple of (library_name, animation_name) or (None, None) if not found.
+        """
+        animation_lower = animation.lower()
+        
+        # Check aliases first
+        if animation_lower in ALIASES:
+            resolved = ALIASES[animation_lower]
+            # Determine which library the resolved name belongs to
+            if resolved in DANCES:
+                return ("reachy-mini-dances-library", resolved)
+            elif resolved in EMOTIONS:
+                return ("reachy-mini-emotions-library", resolved)
+        
+        # Check dances
+        if animation_lower in [d.lower() for d in DANCES]:
+            # Find the exact case
+            for d in DANCES:
+                if d.lower() == animation_lower:
+                    return ("reachy-mini-dances-library", d)
+        
+        # Check emotions
+        if animation_lower in [e.lower() for e in EMOTIONS]:
+            # Find the exact case
+            for e in EMOTIONS:
+                if e.lower() == animation_lower:
+                    return ("reachy-mini-emotions-library", e)
+        
+        return (None, None)
+    
+    def play(self, animation: str, duration: float = 2.0, blocking: bool = False) -> bool:
+        """Play a head animation via the daemon API.
+        
+        Args:
+            animation: Name of the animation to play.
+            duration: Duration (not used - animations have fixed length).
+            blocking: If True, wait for animation to complete (not implemented).
+            
+        Returns:
+            True if animation was triggered successfully.
+        """
+        library, anim_name = self._resolve_animation(animation)
+        
+        if not library or not anim_name:
+            logger.warning(f"Unknown animation: {animation}")
+            return False
+        
+        try:
+            self._is_playing = True
+            self._current_animation = animation
+            
+            # Call the daemon's recorded move API
+            url = f"/api/move/play/recorded-move-dataset/pollen-robotics/{library}/{anim_name}"
+            logger.info(f"Playing animation: {animation} -> {library}/{anim_name}")
+            
+            response = self._client.post(url)
+            response.raise_for_status()
+            
+            result = response.json()
+            logger.info(f"Animation triggered: {result}")
+            
+            self._is_playing = False
+            self._current_animation = None
+            
+            return True
+            
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP error playing animation: {e}")
+            self._is_playing = False
+            self._current_animation = None
+            return False
+        except Exception as e:
+            logger.error(f"Error playing animation: {e}")
+            self._is_playing = False
+            self._current_animation = None
+            return False
+    
+    async def play_async(self, animation: str, duration: float = 2.0) -> bool:
+        """Play animation asynchronously.
+        
+        Args:
+            animation: Name of the animation to play.
+            duration: Duration (not used).
+            
+        Returns:
+            True if animation was triggered successfully.
+        """
+        return self.play(animation, duration, blocking=False)
+    
+    def stop(self) -> bool:
+        """Stop current animation.
+        
+        Returns:
+            True if stop was successful.
+        """
+        try:
+            response = self._client.post("/api/move/stop")
+            response.raise_for_status()
+            
+            self._is_playing = False
+            self._current_animation = None
+            
+            logger.info("Animation stopped")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error stopping animation: {e}")
+            return False
+    
+    async def close(self) -> None:
+        """Clean up resources."""
+        self._client.close()
+        logger.info("Motion service closed")

reachys_brain/openai_realtime.py

@@ -0,0 +1,1123 @@
+"""OpenAI Realtime API WebSocket client for voice conversations on Reachy."""
+
+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
+
+import websockets
+from websockets.client import WebSocketClientProtocol
+
+from .routes.voice import get_current_voice, get_current_language, get_preferred_language
+
+# 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
+
+logger = logging.getLogger(__name__)
+
+# OpenAI Realtime API endpoint
+OPENAI_REALTIME_URL = "wss://api.openai.com/v1/realtime"
+OPENAI_MODEL = "gpt-4o-realtime-preview-2024-12-17"
+
+# Voice Activity Detection (VAD) settings
+VAD_THRESHOLD = 0.7  # Sensitivity: Higher = less sensitive (default 0.5)
+VAD_PREFIX_PADDING_MS = 300  # Audio padding before speech detection
+VAD_SILENCE_DURATION_MS = 700  # Silence duration before response (default 500)
+
+
+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"
+
+
+@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.
+    
+    Manages the connection to OpenAI, sends audio from the microphone,
+    receives transcriptions and AI responses, and plays audio responses.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the OpenAI Realtime service."""
+        self._websocket: Optional[WebSocketClientProtocol] = None
+        self._receive_task: Optional[asyncio.Task] = None
+        
+        # State
+        self._connection_state = ConnectionState.DISCONNECTED
+        self._speaking_state = SpeakingState.IDLE
+        self._is_listening = False
+        self._current_transcript = ""
+        self._response_text_buffer = ""
+
+        # Event used to await the end of an in-flight spoken response.
+        # This matters because `session.update` (voice/language) only applies to *future* responses.
+        self._speaking_idle_event = asyncio.Event()
+        self._speaking_idle_event.set()
+        
+        # Language settings - use preferred language from voice 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
+        
+        # Enabled tools for current app (None = default/all tools)
+        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
+        
+        # Callbacks for iOS relay
+        self.on_connection_state: Optional[Callable[[ConnectionState], None]] = None
+        self.on_speaking_state: Optional[Callable[[SpeakingState], 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
+        
+        # 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)
+        
+        # Session update callback - called when OpenAI confirms session update
+        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
+        self._setup_tools_handler()
+        self._setup_meeting_callbacks()
+    
+    @property
+    def connection_state(self) -> ConnectionState:
+        """Get current connection state."""
+        return self._connection_state
+    
+    @property
+    def speaking_state(self) -> SpeakingState:
+        """Get current speaking state."""
+        return self._speaking_state
+    
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected to OpenAI."""
+        return self._connection_state == ConnectionState.CONNECTED
+    
+    @property
+    def is_listening(self) -> bool:
+        """Check if actively listening for audio."""
+        return self._is_listening
+    
+    @property
+    def language(self) -> str:
+        """Get current language code."""
+        return self._language
+    
+    @language.setter
+    def language(self, value: str) -> None:
+        """Set language and update session if connected."""
+        if value != self._language:
+            self._language = value
+            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
+    
+    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.
+        """
+        logger.info(f"🎭 Setting custom personality ({len(system_prompt)} chars)")
+        self._custom_system_prompt = system_prompt
+        self._enabled_tools = enabled_tools
+        
+        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())
+    
+    def clear_custom_personality(self) -> None:
+        """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
+        
+        # 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
+    
+    def _setup_tools_handler(self) -> None:
+        """Setup callbacks for the app 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,
+        ) -> None:
+            if system_prompt:
+                self.set_custom_personality(system_prompt, enabled_tools)
+            else:
+                self.clear_custom_personality()
+        
+        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)
+        
+        tools_handler.on_app_change = on_app_change
+    
+    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
+        
+        def on_meeting_started(meeting_id: str, title: str) -> None:
+            """Called when a meeting recording starts."""
+            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."""
+            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_transcript_update=on_transcript_update,
+        )
+    
+    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
+        
+        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)
+    
+    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.
+        """
+        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")
+            raise ValueError("OpenAI API key not provided")
+        
+        logger.info(f"🔌 Connecting to OpenAI Realtime API (key: {key[:8]}...)")
+        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",
+            }
+            
+            logger.info(f"🔌 Connecting to {url}")
+            
+            self._websocket = await websockets.connect(
+                url,
+                additional_headers=headers,
+                ping_interval=20,
+                ping_timeout=10,
+            )
+            
+            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:
+            logger.error(f"❌ Failed to connect to OpenAI: {e}", exc_info=True)
+            self._set_connection_state(ConnectionState.ERROR)
+            if self.on_error:
+                self.on_error(str(e))
+            raise
+    
+    async def disconnect(self) -> None:
+        """Disconnect from OpenAI Realtime API."""
+        if self._receive_task:
+            self._receive_task.cancel()
+            try:
+                await self._receive_task
+            except asyncio.CancelledError:
+                pass
+            self._receive_task = None
+        
+        if self._websocket:
+            await self._websocket.close()
+            self._websocket = None
+        
+        self._is_listening = False
+        self._set_speaking_state(SpeakingState.IDLE)
+        self._set_connection_state(ConnectionState.DISCONNECTED)
+        logger.info("Disconnected from OpenAI Realtime API")
+    
+    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()
+        
+        # Sync language with preferred setting
+        self._language = get_preferred_language()
+        
+        # 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}")
+        
+        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_PADDING_MS,
+                    "silence_duration_ms": VAD_SILENCE_DURATION_MS,
+                },
+                "tools": all_tools,
+                "tool_choice": "auto",
+            },
+        }
+        
+        await self._send_message(session_config)
+    
+    async def _update_session(self) -> None:
+        """Update session with new language settings."""
+        if not self.is_connected:
+            return
+        
+        lang_name = self._language_names.get(self._language, "English")
+        logger.info(f"Updating OpenAI session language to {lang_name}")
+        
+        await self._configure_session()
+    
+    async def _send_message(self, message: dict) -> None:
+        """Send a message to OpenAI."""
+        if not self._websocket:
+            raise RuntimeError("Not connected to OpenAI")
+        
+        await self._websocket.send(json.dumps(message))
+    
+    async def _receive_messages(self) -> None:
+        """Receive and handle messages from OpenAI."""
+        if not self._websocket:
+            return
+        
+        try:
+            async for message in self._websocket:
+                await self._handle_message(message)
+        except websockets.ConnectionClosed:
+            logger.info("OpenAI WebSocket connection closed")
+            self._set_connection_state(ConnectionState.DISCONNECTED)
+        except Exception as e:
+            logger.error(f"Error receiving messages: {e}")
+            self._set_connection_state(ConnectionState.ERROR)
+            if self.on_error:
+                self.on_error(str(e))
+    
+    async def _handle_message(self, message: str) -> None:
+        """Handle a message from OpenAI."""
+        try:
+            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
+                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
+                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)
+                    
+                    # Decode and forward audio
+                    audio_data = base64.b64decode(audio_base64)
+                    if self.on_audio_delta:
+                        self.on_audio_delta(audio_data)
+            
+            elif msg_type == "response.audio.done":
+                # AI audio response complete
+                self._set_speaking_state(SpeakingState.IDLE)
+            
+            elif msg_type == "response.done":
+                # Full response complete
+                self._set_speaking_state(SpeakingState.IDLE)
+                if self._response_text_buffer:
+                    if self.on_response_text:
+                        self.on_response_text(self._response_text_buffer)
+                    self._response_text_buffer = ""
+            
+            elif msg_type == "error":
+                error_data = data.get("error", {})
+                error_msg = error_data.get("message", "Unknown error")
+                error_code = error_data.get("code", "unknown")
+                logger.error(f"❌ OpenAI error [{error_code}]: {error_msg}")
+                logger.error(f"❌ Full error data: {error_data}")
+                if self.on_error:
+                    self.on_error(error_msg)
+            
+            elif msg_type == "input_audio_buffer.committed":
+                logger.info("✅ Audio buffer committed to OpenAI")
+            
+            elif msg_type == "input_audio_buffer.cleared":
+                logger.info("🗑️ Audio buffer cleared")
+            
+            # Tool/Function 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", "")
+                    func_name = item.get("name", "")
+                    logger.info(f"🔧 Function call started: {func_name} (call_id: {call_id})")
+                    self._pending_tool_calls[call_id] = {
+                        "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", "")
+                
+                if call_id in self._pending_tool_calls:
+                    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}")
+                    
+                    # Execute the tool asynchronously
+                    asyncio.create_task(
+                        self._execute_tool_call(call_id, tool_name, arguments_str)
+                    )
+            
+            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", "")
+                    if call_id in self._pending_tool_calls:
+                        del self._pending_tool_calls[call_id]
+            
+            else:
+                logger.debug(f"Unhandled message type: {msg_type}")
+        
+        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."
+            )
+            # 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")
+    
+    # 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.
+        """
+        if not self.is_connected:
+            return
+        
+        # Encode audio as base64
+        audio_base64 = base64.b64encode(audio_data).decode("utf-8")
+        
+        message = {
+            "type": "input_audio_buffer.append",
+            "audio": audio_base64,
+        }
+        
+        await self._send_message(message)
+    
+    async def commit_audio_and_respond(self) -> None:
+        """Commit the audio buffer and request a response."""
+        if not self.is_connected:
+            return
+        
+        # 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:
+        """Clear the input audio buffer."""
+        if not self.is_connected:
+            return
+        
+        await self._send_message({"type": "input_audio_buffer.clear"})
+    
+    async def cancel_response(self) -> None:
+        """Cancel the current response."""
+        if not self.is_connected:
+            return
+        
+        await self._send_message({"type": "response.cancel"})
+    
+    # MARK: - Text Input
+    
+    async def send_text_message(self, text: str) -> None:
+        """Send a text message (non-voice interaction).
+        
+        Args:
+            text: The text message to send.
+        """
+        if not self.is_connected:
+            raise RuntimeError("Not connected to OpenAI")
+        
+        # Create conversation item
+        item_message = {
+            "type": "conversation.item.create",
+            "item": {
+                "type": "message",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": text,
+                    }
+                ],
+            },
+        }
+        await self._send_message(item_message)
+        
+        # Trigger response
+        await self._send_message({"type": "response.create"})
+    
+    # MARK: - Listening Control
+    
+    def start_listening(self) -> None:
+        """Start listening for audio input."""
+        self._is_listening = True
+        self._current_transcript = ""
+        logger.info("Started listening")
+    
+    def stop_listening(self) -> None:
+        """Stop listening for audio input."""
+        self._is_listening = False
+        logger.info("Stopped listening")
+    
+    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
+        
+        # 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.
+        
+        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()
+            await self.clear_audio_buffer()
+            try:
+                await asyncio.wait_for(self._speaking_idle_event.wait(), timeout=timeout)
+            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")
+            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
+        
+        # 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()
+            await self.clear_audio_buffer()
+            try:
+                await asyncio.wait_for(self._speaking_idle_event.wait(), timeout=timeout)
+            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")
+            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"
+        if "_" in voice_id:
+            lang_code = voice_id[:2].lower()
+        else:
+            lang_code = "en"
+        
+        if lang_code in self._language_names:
+            self.language = lang_code
+        else:
+            self.language = "en"
+

reachys_brain/routes/__init__.py

@@ -0,0 +1,42 @@
+"""Route modules for the iOS Bridge API."""
+
+from .animations import router as animations_router
+from .apps import router as apps_router
+from .conversation import router as conversation_router
+from .games import router as games_router
+from .joystick import router as joystick_router
+from .meetings import router as meetings_router
+from .motion import router as motion_router
+from .notes import router as notes_router
+from .openai_config import router as openai_config_router
+from .power import router as power_router
+from .scheduled_messages import router as scheduled_messages_router
+from .speech import router as speech_router
+from .state import router as state_router
+from .tools import router as tools_router
+from .user_settings import router as user_settings_router
+from .voice import router as voice_router
+from .volume import router as volume_router
+from .websites import router as websites_router
+
+__all__ = [
+    "animations_router",
+    "apps_router",
+    "conversation_router",
+    "games_router",
+    "joystick_router",
+    "meetings_router",
+    "motion_router",
+    "notes_router",
+    "openai_config_router",
+    "power_router",
+    "scheduled_messages_router",
+    "speech_router",
+    "state_router",
+    "tools_router",
+    "user_settings_router",
+    "voice_router",
+    "volume_router",
+    "websites_router",
+]
+

reachys_brain/routes/animation_manager.py

@@ -0,0 +1,190 @@
+"""Animation management for conversation handling.
+
+Coordinates pre-speech animations, emotion-based animations,
+and speaking gestures during voice conversations.
+"""
+
+import asyncio
+import logging
+from typing import Optional
+
+from .audio_stream_manager import ConversationTimings
+from .audio_manager import flush_audio_buffer
+from .conversation_services import get_services, get_state
+from .user_settings import get_user_name_value
+
+logger = logging.getLogger(__name__)
+
+
+async def handle_pre_speech_animation(text: str) -> None:
+    """Handle pre-speech animation and audio buffer flushing.
+    
+    This is the core of the animation system:
+    1. Analyze sentiment from response text
+    2. Play appropriate emotion animation (with probability)
+    3. Flush buffered audio chunks
+    4. Continue normal audio streaming
+    
+    Args:
+        text: The AI response text to analyze for sentiment.
+    """
+    services = get_services()
+    state = get_state()
+    
+    if not services.pre_speech_animation_lock:
+        return
+    
+    async with services.pre_speech_animation_lock:
+        # Only play animation once per response
+        if state.animation_played_for_response:
+            return
+        state.animation_played_for_response = True
+        
+        try:
+            # Play pre-speech emotion animation
+            if services.animation_coordinator and text:
+                result = await services.animation_coordinator.play_emotion_for_text(text)
+                if result.played:
+                    logger.info(
+                        f"🎭 Pre-speech animation: {result.animation} "
+                        f"(sentiment: {result.sentiment}, duration: {result.duration}s)"
+                    )
+            
+            # Flush buffered audio
+            flush_audio_buffer()
+            
+            # Stop buffering - stream directly now
+            state.is_buffering_audio = False
+            
+        except Exception as e:
+            logger.error(f"Error in pre-speech animation: {e}")
+            # Make sure we flush audio even on error
+            flush_audio_buffer()
+            state.is_buffering_audio = False
+
+
+async def send_greeting() -> None:
+    """Send a greeting prompt when conversation starts.
+    
+    Plays a welcoming animation, then sends an instruction to the AI
+    to greet the user naturally, optionally personalized with their name.
+    """
+    services = get_services()
+    state = get_state()
+    
+    try:
+        await asyncio.sleep(ConversationTimings.GREETING_ANIMATION_DELAY)
+        
+        # Play welcoming animation first
+        if services.motion:
+            greeting_animation = state.custom_emotion_animations.get(
+                "greeting", "welcoming1"
+            )
+            logger.info(f"👋 Playing welcome animation: {greeting_animation}")
+            await services.motion.play_async(
+                animation=greeting_animation,
+                duration=ConversationTimings.PRE_SPEECH_DURATION_GREETING
+            )
+            await asyncio.sleep(ConversationTimings.POST_GREETING_PAUSE)
+        
+        if not services.openai or not services.openai.is_connected:
+            logger.warning("Cannot send greeting - not connected")
+            return
+        
+        # Check if we know the user's name for personalized greeting
+        user_name = await get_user_name_value()
+        
+        # Send an instruction prompt to the AI to generate the greeting
+        if user_name:
+            greeting_prompt = (
+                f"[Start of conversation. Greet me warmly - my name is {user_name}.]"
+            )
+            logger.info(f"👋 Sending personalized greeting prompt for: {user_name}")
+        else:
+            greeting_prompt = (
+                "[Start of conversation. Greet me warmly and introduce yourself.]"
+            )
+            logger.info("👋 Sending greeting prompt")
+        
+        await services.openai.send_text_message(greeting_prompt)
+        
+    except Exception as e:
+        logger.error(f"Error sending greeting: {e}")
+
+
+async def send_goodbye() -> None:
+    """Send a goodbye prompt when conversation ends.
+    
+    Sends an instruction to the AI to say goodbye naturally,
+    optionally personalized with the user's name.
+    """
+    services = get_services()
+    state = get_state()
+    
+    try:
+        if not services.openai or not services.openai.is_connected:
+            logger.warning("Cannot send goodbye - not connected")
+            return
+        
+        # Check if we know the user's name for personalized goodbye
+        user_name = await get_user_name_value()
+        
+        # Send an instruction prompt to the AI to generate the goodbye
+        if user_name:
+            goodbye_prompt = (
+                f"[End of conversation. Say a warm goodbye to me - "
+                f"my name is {user_name}.]"
+            )
+            logger.info(f"👋 Sending personalized goodbye prompt for: {user_name}")
+        else:
+            goodbye_prompt = "[End of conversation. Say a warm goodbye.]"
+            logger.info("👋 Sending goodbye prompt")
+        
+        await services.openai.send_text_message(goodbye_prompt)
+        
+        # Play a friendly wave/goodbye animation
+        if services.motion:
+            await asyncio.sleep(ConversationTimings.GREETING_ANIMATION_DELAY)
+            goodbye_animation = state.custom_emotion_animations.get(
+                "greeting", "welcoming1"
+            )
+            await services.motion.play_async(
+                animation=goodbye_animation,
+                duration=ConversationTimings.PRE_SPEECH_DURATION_GREETING
+            )
+        
+    except Exception as e:
+        logger.error(f"Error sending goodbye: {e}")
+
+
+def set_custom_animations(emotion_animations: dict) -> None:
+    """Set custom emotion-to-animation mappings.
+    
+    Args:
+        emotion_animations: Dictionary mapping emotion names to animation names.
+    """
+    services = get_services()
+    state = get_state()
+    
+    state.custom_emotion_animations = emotion_animations
+    
+    # Pass custom animations to the AnimationCoordinator
+    if services.animation_coordinator:
+        services.animation_coordinator.set_custom_animations(emotion_animations)
+    
+    logger.info(f"🎬 Custom emotion animations set: {list(emotion_animations.keys())}")
+
+
+def clear_custom_animations() -> None:
+    """Clear custom animations and revert to defaults."""
+    services = get_services()
+    state = get_state()
+    
+    state.custom_emotion_animations = {}
+    
+    # Clear custom animations from AnimationCoordinator
+    if services.animation_coordinator:
+        services.animation_coordinator.clear_custom_animations()
+    
+    logger.info("🎬 Custom emotion animations cleared - using defaults")
+

reachys_brain/routes/animations.py

@@ -0,0 +1,578 @@
+"""Custom animation endpoints for recording and playing back joystick animations.
+
+Provides CRUD operations for custom animations and playback functionality.
+"""
+
+import asyncio
+import base64
+import logging
+import math
+import tempfile
+from pathlib import Path
+
+import httpx
+from fastapi import APIRouter, HTTPException
+
+from ..database import get_database
+from ..models import (
+    AnimationPlayRequest,
+    AnimationPlayResponse,
+    CustomAnimation,
+    CustomAnimationCreate,
+    CustomAnimationResponse,
+    CustomAnimationsListResponse,
+    CustomAnimationUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/animations", tags=["Custom Animations"])
+
+# Daemon API URL for sending position commands
+DAEMON_URL = "http://localhost:8000"
+
+# Playback state
+_is_playing = False
+_current_animation_id: str | None = None
+
+
+def _degrees_to_radians(degrees: float) -> float:
+    """Convert degrees to radians."""
+    return degrees * math.pi / 180.0
+
+
+async def _send_pose_to_daemon(
+    head_roll: float,
+    head_pitch: float,
+    head_yaw: float,
+    body_yaw: float,
+    antenna_left: float,
+    antenna_right: float,
+) -> None:
+    """Send a complete pose to the daemon's set_target endpoint."""
+    payload = {
+        "target_head_pose": {
+            "x": 0.0,
+            "y": 0.0,
+            "z": 0.0,
+            "roll": _degrees_to_radians(head_roll),
+            "pitch": _degrees_to_radians(head_pitch),
+            "yaw": _degrees_to_radians(head_yaw),
+        },
+        "target_body_yaw": _degrees_to_radians(body_yaw),
+        "target_antennas": [
+            _degrees_to_radians(antenna_left),
+            _degrees_to_radians(antenna_right),
+        ],
+    }
+    
+    async with httpx.AsyncClient(timeout=2.0) as client:
+        response = await client.post(
+            f"{DAEMON_URL}/api/move/set_target",
+            json=payload,
+        )
+        response.raise_for_status()
+
+
+# =============================================================================
+# CRUD Endpoints
+# =============================================================================
+
+
+@router.get("", response_model=CustomAnimationsListResponse)
+async def list_animations() -> CustomAnimationsListResponse:
+    """List all custom animations."""
+    try:
+        db = get_database()
+        animations = await db.get_all_animations()
+        return CustomAnimationsListResponse(
+            success=True,
+            animations=animations,
+            count=len(animations),
+        )
+    except Exception as e:
+        logger.error(f"Error listing animations: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{animation_id}", response_model=CustomAnimationResponse)
+async def get_animation(animation_id: str) -> CustomAnimationResponse:
+    """Get a single custom animation by ID."""
+    try:
+        db = get_database()
+        animation = await db.get_animation(animation_id)
+        
+        if not animation:
+            raise HTTPException(status_code=404, detail="Animation not found")
+        
+        return CustomAnimationResponse(
+            success=True,
+            animation=animation,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting animation {animation_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("", response_model=CustomAnimationResponse, status_code=201)
+async def create_animation(animation: CustomAnimationCreate) -> CustomAnimationResponse:
+    """Create a new custom animation."""
+    try:
+        db = get_database()
+        
+        # Check if animation with this ID already exists
+        existing = await db.get_animation(animation.id)
+        if existing:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Animation with ID {animation.id} already exists"
+            )
+        
+        # Convert Pydantic models to dicts for database
+        animation_data = animation.model_dump()
+        animation_data["start_pose"] = animation.start_pose.model_dump()
+        animation_data["keyframes"] = [kf.model_dump() for kf in animation.keyframes]
+        # audio_data is already a string (base64) so no conversion needed
+        
+        created = await db.create_animation(animation_data)
+        
+        has_audio = bool(animation.audio_data)
+        logger.info(f"Animation created with audio: {has_audio}")
+        
+        return CustomAnimationResponse(
+            success=True,
+            animation=created,
+            message="Animation created successfully" + (" (with audio)" if has_audio else ""),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error creating animation: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.put("/{animation_id}", response_model=CustomAnimationResponse)
+async def update_animation(
+    animation_id: str,
+    animation: CustomAnimationUpdate,
+) -> CustomAnimationResponse:
+    """Update an existing custom animation."""
+    try:
+        db = get_database()
+        
+        # Build update dict, only including non-None fields
+        update_data = {}
+        if animation.name is not None:
+            update_data["name"] = animation.name
+        if animation.description is not None:
+            update_data["description"] = animation.description
+        if animation.duration_ms is not None:
+            update_data["duration_ms"] = animation.duration_ms
+        if animation.start_pose is not None:
+            update_data["start_pose"] = animation.start_pose.model_dump()
+        if animation.keyframes is not None:
+            update_data["keyframes"] = [kf.model_dump() for kf in animation.keyframes]
+        if animation.audio_data is not None:
+            update_data["audio_data"] = animation.audio_data
+        
+        updated = await db.update_animation(animation_id, update_data)
+        
+        if not updated:
+            raise HTTPException(status_code=404, detail="Animation not found")
+        
+        return CustomAnimationResponse(
+            success=True,
+            animation=updated,
+            message="Animation updated successfully",
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error updating animation {animation_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/{animation_id}")
+async def delete_animation(animation_id: str) -> dict:
+    """Delete a custom animation."""
+    try:
+        db = get_database()
+        deleted = await db.delete_animation(animation_id)
+        
+        if not deleted:
+            raise HTTPException(status_code=404, detail="Animation not found")
+        
+        return {
+            "success": True,
+            "message": f"Animation {animation_id} deleted successfully",
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deleting animation {animation_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# =============================================================================
+# Playback Endpoints
+# =============================================================================
+
+
+@router.post("/{animation_id}/play", response_model=AnimationPlayResponse)
+async def play_animation(
+    animation_id: str,
+    request: AnimationPlayRequest = AnimationPlayRequest(),
+) -> AnimationPlayResponse:
+    """Play a custom animation on the robot.
+    
+    Moves the robot through all recorded keyframes with proper timing.
+    """
+    global _is_playing, _current_animation_id
+    
+    if _is_playing:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Animation {_current_animation_id} is already playing"
+        )
+    
+    try:
+        db = get_database()
+        animation = await db.get_animation(animation_id)
+        
+        if not animation:
+            raise HTTPException(status_code=404, detail="Animation not found")
+        
+        _is_playing = True
+        _current_animation_id = animation_id
+        
+        # Start playback in background task
+        asyncio.create_task(_play_animation_task(animation, request.speed))
+        
+        return AnimationPlayResponse(
+            success=True,
+            message="Animation playback started",
+            animation_id=animation_id,
+            duration_ms=int(animation["duration_ms"] / request.speed),
+        )
+        
+    except HTTPException:
+        _is_playing = False
+        _current_animation_id = None
+        raise
+    except Exception as e:
+        _is_playing = False
+        _current_animation_id = None
+        logger.error(f"Error playing animation {animation_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/stop")
+async def stop_animation() -> dict:
+    """Stop the currently playing animation."""
+    global _is_playing, _current_animation_id
+    
+    if not _is_playing:
+        return {
+            "success": True,
+            "message": "No animation is currently playing",
+        }
+    
+    _is_playing = False
+    stopped_id = _current_animation_id
+    _current_animation_id = None
+    
+    return {
+        "success": True,
+        "message": f"Animation {stopped_id} stopped",
+    }
+
+
+@router.get("/status")
+async def get_playback_status() -> dict:
+    """Get the current animation playback status."""
+    return {
+        "is_playing": _is_playing,
+        "current_animation_id": _current_animation_id,
+    }
+
+
+# Track audio playback state
+_audio_process: asyncio.subprocess.Process | None = None
+
+
+@router.post("/play-audio")
+async def play_audio(request: dict) -> dict:
+    """Play audio data through Reachy's speaker.
+    
+    Accepts base64-encoded audio data (M4A format) and plays it.
+    Used for testing animations before saving.
+    """
+    global _audio_process
+    
+    audio_data_b64 = request.get("audio_data")
+    if not audio_data_b64:
+        raise HTTPException(status_code=400, detail="No audio_data provided")
+    
+    try:
+        # Stop any currently playing audio
+        if _audio_process and _audio_process.returncode is None:
+            _audio_process.terminate()
+            try:
+                await asyncio.wait_for(_audio_process.wait(), timeout=1.0)
+            except asyncio.TimeoutError:
+                _audio_process.kill()
+        
+        # Decode base64 audio
+        audio_bytes = base64.b64decode(audio_data_b64)
+        logger.info(f"Playing audio: {len(audio_bytes)} bytes")
+        
+        # Write to temp file
+        audio_temp_file = tempfile.NamedTemporaryFile(
+            suffix=".m4a", delete=False
+        )
+        audio_temp_file.write(audio_bytes)
+        audio_temp_file.close()
+        
+        # Start playback
+        _audio_process = await _play_audio_file(Path(audio_temp_file.name))
+        
+        if _audio_process:
+            # Clean up temp file after playback in background
+            asyncio.create_task(_cleanup_audio_after_playback(
+                _audio_process, Path(audio_temp_file.name)
+            ))
+            return {
+                "success": True,
+                "message": "Audio playback started",
+            }
+        else:
+            # Clean up immediately if playback failed
+            Path(audio_temp_file.name).unlink(missing_ok=True)
+            raise HTTPException(
+                status_code=500,
+                detail="Failed to start audio playback (no audio player available)"
+            )
+            
+    except base64.binascii.Error as e:
+        raise HTTPException(status_code=400, detail=f"Invalid base64 data: {e}")
+    except Exception as e:
+        logger.error(f"Error playing audio: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/stop-audio")
+async def stop_audio() -> dict:
+    """Stop currently playing audio."""
+    global _audio_process
+    
+    if _audio_process and _audio_process.returncode is None:
+        _audio_process.terminate()
+        try:
+            await asyncio.wait_for(_audio_process.wait(), timeout=1.0)
+        except asyncio.TimeoutError:
+            _audio_process.kill()
+        _audio_process = None
+        return {"success": True, "message": "Audio stopped"}
+    
+    return {"success": True, "message": "No audio was playing"}
+
+
+async def _cleanup_audio_after_playback(
+    process: asyncio.subprocess.Process,
+    file_path: Path
+) -> None:
+    """Wait for audio playback to finish and clean up temp file."""
+    try:
+        await process.wait()
+    except Exception:
+        pass
+    finally:
+        file_path.unlink(missing_ok=True)
+
+
+async def _play_audio_file(audio_file_path: Path) -> asyncio.subprocess.Process | None:
+    """Play an audio file using GStreamer with Reachy's dmix audio sink.
+    
+    Uses the reachymini_audio_sink device which allows sharing the audio
+    device with the daemon process.
+    
+    Args:
+        audio_file_path: Path to the audio file to play.
+        
+    Returns:
+        The subprocess if started, None on error.
+    """
+    # Use GStreamer with Reachy's shared audio sink (dmix)
+    # This allows playing audio even while the daemon holds the device
+    try:
+        process = await asyncio.create_subprocess_exec(
+            "gst-launch-1.0", "-q",
+            "filesrc", f"location={audio_file_path}",
+            "!", "decodebin",
+            "!", "audioconvert",
+            "!", "audioresample",
+            "!", "audio/x-raw,rate=16000,channels=2",
+            "!", "alsasink", "device=reachymini_audio_sink",
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        logger.info(f"Audio playback started with GStreamer (reachymini_audio_sink): {audio_file_path}")
+        return process
+    except FileNotFoundError:
+        logger.error("gst-launch-1.0 not found")
+        return None
+    except Exception as e:
+        logger.error(f"Failed to start audio playback: {e}")
+        return None
+
+
+async def _play_animation_task(animation: dict, speed: float) -> None:
+    """Background task to play animation keyframes.
+    
+    Args:
+        animation: The animation data dict.
+        speed: Playback speed multiplier.
+    """
+    global _is_playing, _current_animation_id
+    
+    audio_temp_file = None
+    audio_process = None
+    
+    try:
+        logger.info(f"Starting animation playback: {animation['name']}")
+        
+        # Move to start pose first
+        start_pose = animation["start_pose"]
+        await _send_pose_to_daemon(
+            head_roll=start_pose.get("head_roll", 0.0),
+            head_pitch=start_pose.get("head_pitch", 0.0),
+            head_yaw=start_pose.get("head_yaw", 0.0),
+            body_yaw=start_pose.get("body_yaw", 0.0),
+            antenna_left=start_pose.get("antenna_left", 0.0),
+            antenna_right=start_pose.get("antenna_right", 0.0),
+        )
+        
+        # Small delay for start pose
+        await asyncio.sleep(0.3)
+        
+        # Handle audio playback if present
+        audio_data = animation.get("audio_data")
+        if audio_data:
+            try:
+                # Decode base64 audio and write to temp file
+                audio_bytes = base64.b64decode(audio_data)
+                audio_temp_file = tempfile.NamedTemporaryFile(
+                    suffix=".m4a", delete=False
+                )
+                audio_temp_file.write(audio_bytes)
+                audio_temp_file.close()
+                
+                logger.info(f"Audio data decoded: {len(audio_bytes)} bytes")
+                
+                # Start audio playback
+                audio_process = await _play_audio_file(Path(audio_temp_file.name))
+                
+            except Exception as e:
+                logger.error(f"Failed to prepare audio: {e}")
+        
+        keyframes = animation["keyframes"]
+        if not keyframes:
+            logger.warning("Animation has no keyframes")
+            return
+        
+        # Sort keyframes by timestamp
+        keyframes = sorted(keyframes, key=lambda kf: kf["timestamp"])
+        
+        # Play through keyframes
+        start_time = asyncio.get_event_loop().time() * 1000  # ms
+        
+        for i, keyframe in enumerate(keyframes):
+            if not _is_playing:
+                logger.info("Animation playback stopped")
+                break
+            
+            # Calculate when this keyframe should be hit
+            target_time = start_time + (keyframe["timestamp"] / speed)
+            current_time = asyncio.get_event_loop().time() * 1000
+            
+            # Wait until it's time for this keyframe
+            wait_time = (target_time - current_time) / 1000  # convert to seconds
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+            
+            if not _is_playing:
+                break
+            
+            # Send the keyframe pose
+            await _send_pose_to_daemon(
+                head_roll=keyframe.get("head_roll", 0.0),
+                head_pitch=keyframe.get("head_pitch", 0.0),
+                head_yaw=keyframe.get("head_yaw", 0.0),
+                body_yaw=keyframe.get("body_yaw", 0.0),
+                antenna_left=keyframe.get("antenna_left", 0.0),
+                antenna_right=keyframe.get("antenna_right", 0.0),
+            )
+        
+        logger.info(f"Animation playback completed: {animation['name']}")
+        
+    except Exception as e:
+        logger.error(f"Error during animation playback: {e}")
+    finally:
+        _is_playing = False
+        _current_animation_id = None
+        
+        # Stop audio playback if still running
+        if audio_process and audio_process.returncode is None:
+            try:
+                audio_process.terminate()
+                await audio_process.wait()
+            except Exception:
+                pass
+        
+        # Clean up temp audio file
+        if audio_temp_file:
+            try:
+                Path(audio_temp_file.name).unlink(missing_ok=True)
+            except Exception:
+                pass
+
+
+async def play_custom_animation(animation_id: str, speed: float = 1.0) -> bool:
+    """Play a custom animation by ID (for use by other modules).
+    
+    Args:
+        animation_id: The UUID of the animation to play.
+        speed: Playback speed multiplier.
+        
+    Returns:
+        True if animation started successfully, False otherwise.
+    """
+    global _is_playing, _current_animation_id
+    
+    if _is_playing:
+        logger.warning(f"Cannot play animation {animation_id}: another animation is playing")
+        return False
+    
+    try:
+        db = get_database()
+        animation = await db.get_animation(animation_id)
+        
+        if not animation:
+            logger.warning(f"Animation not found: {animation_id}")
+            return False
+        
+        _is_playing = True
+        _current_animation_id = animation_id
+        
+        # Start playback in background
+        asyncio.create_task(_play_animation_task(animation, speed))
+        return True
+        
+    except Exception as e:
+        logger.error(f"Error starting animation {animation_id}: {e}")
+        _is_playing = False
+        _current_animation_id = None
+        return False
+

reachys_brain/routes/apps.py

@@ -0,0 +1,246 @@
+"""Custom Apps API endpoints.
+
+Provides CRUD operations for user-created custom apps stored on the bridge.
+"""
+
+import logging
+
+from fastapi import APIRouter, HTTPException
+
+from ..database import get_database
+from ..models import (
+    CustomApp,
+    CustomAppCreate,
+    CustomAppResponse,
+    CustomAppsListResponse,
+    CustomAppsSyncRequest,
+    CustomAppsSyncResponse,
+    CustomAppUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/apps", tags=["Custom Apps"])
+
+
+# =============================================================================
+# List / Read Operations
+# =============================================================================
+
+
+@router.get("", response_model=CustomAppsListResponse)
+async def list_apps() -> CustomAppsListResponse:
+    """Get all custom apps.
+
+    Returns:
+        List of all custom apps stored on the bridge.
+    """
+    try:
+        db = get_database()
+        apps = await db.get_all_apps()
+        return CustomAppsListResponse(
+            success=True,
+            apps=[CustomApp(**app) for app in apps],
+            count=len(apps),
+        )
+    except Exception as e:
+        logger.error(f"Failed to list apps: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{app_id}", response_model=CustomAppResponse)
+async def get_app(app_id: str) -> CustomAppResponse:
+    """Get a single custom app by ID.
+
+    Args:
+        app_id: UUID of the app.
+
+    Returns:
+        The custom app if found.
+
+    Raises:
+        HTTPException: 404 if app not found.
+    """
+    try:
+        db = get_database()
+        # Normalize UUID to lowercase (iOS sends uppercase, db stores lowercase)
+        app = await db.get_app(app_id.lower())
+
+        if not app:
+            raise HTTPException(status_code=404, detail=f"App not found: {app_id}")
+
+        return CustomAppResponse(
+            success=True,
+            app=CustomApp(**app),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get app {app_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# =============================================================================
+# Create / Update / Delete Operations
+# =============================================================================
+
+
+@router.post("", response_model=CustomAppResponse, status_code=201)
+async def create_app(app_data: CustomAppCreate) -> CustomAppResponse:
+    """Create a new custom app.
+
+    Args:
+        app_data: The app data including UUID from iOS.
+
+    Returns:
+        The created app.
+    """
+    try:
+        db = get_database()
+
+        # Normalize UUID to lowercase (iOS sends uppercase)
+        normalized_id = app_data.id.lower()
+
+        # Check if app already exists
+        existing = await db.get_app(normalized_id)
+        if existing:
+            raise HTTPException(
+                status_code=409,
+                detail=f"App already exists: {app_data.id}",
+            )
+
+        # Create the app with normalized ID
+        app_dict = app_data.model_dump()
+        app_dict["id"] = normalized_id
+        created = await db.create_app(app_dict)
+
+        logger.info(f"Created app: {app_data.name} ({app_data.id})")
+        return CustomAppResponse(
+            success=True,
+            app=CustomApp(**created),
+            message="App created successfully",
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to create app: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.put("/{app_id}", response_model=CustomAppResponse)
+async def update_app(app_id: str, app_data: CustomAppUpdate) -> CustomAppResponse:
+    """Update an existing custom app.
+
+    Args:
+        app_id: UUID of the app to update.
+        app_data: Fields to update (partial update supported).
+
+    Returns:
+        The updated app.
+
+    Raises:
+        HTTPException: 404 if app not found.
+    """
+    try:
+        db = get_database()
+
+        # Get only the fields that were actually provided
+        update_data = app_data.model_dump(exclude_unset=True)
+
+        if not update_data:
+            raise HTTPException(status_code=400, detail="No fields to update")
+
+        # Normalize UUID to lowercase (iOS sends uppercase, db stores lowercase)
+        updated = await db.update_app(app_id.lower(), update_data)
+
+        if not updated:
+            raise HTTPException(status_code=404, detail=f"App not found: {app_id}")
+
+        logger.info(f"Updated app: {app_id}")
+        return CustomAppResponse(
+            success=True,
+            app=CustomApp(**updated),
+            message="App updated successfully",
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to update app {app_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/{app_id}", response_model=CustomAppResponse)
+async def delete_app(app_id: str) -> CustomAppResponse:
+    """Delete a custom app.
+
+    Args:
+        app_id: UUID of the app to delete.
+
+    Returns:
+        Success response.
+
+    Raises:
+        HTTPException: 404 if app not found.
+    """
+    try:
+        db = get_database()
+        # Normalize UUID to lowercase (iOS sends uppercase, db stores lowercase)
+        deleted = await db.delete_app(app_id.lower())
+
+        if not deleted:
+            raise HTTPException(status_code=404, detail=f"App not found: {app_id}")
+
+        logger.info(f"Deleted app: {app_id}")
+        return CustomAppResponse(
+            success=True,
+            message="App deleted successfully",
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to delete app {app_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# =============================================================================
+# Sync Operation
+# =============================================================================
+
+
+@router.post("/sync", response_model=CustomAppsSyncResponse)
+async def sync_apps(sync_data: CustomAppsSyncRequest) -> CustomAppsSyncResponse:
+    """Bulk sync apps from iOS client.
+
+    This replaces all existing apps with the provided list.
+    Useful for initial sync or restore from iOS backup.
+
+    Args:
+        sync_data: List of apps to sync.
+
+    Returns:
+        All apps after sync.
+    """
+    try:
+        db = get_database()
+
+        # Convert to dicts for database, normalizing IDs to lowercase
+        apps_data = []
+        for app in sync_data.apps:
+            app_dict = app.model_dump()
+            app_dict["id"] = app_dict["id"].lower()  # Normalize UUID
+            apps_data.append(app_dict)
+
+        # Perform sync
+        synced = await db.sync_apps(apps_data)
+
+        logger.info(f"Synced {len(synced)} apps from iOS")
+        return CustomAppsSyncResponse(
+            success=True,
+            synced_count=len(synced),
+            apps=[CustomApp(**app) for app in synced],
+            message=f"Successfully synced {len(synced)} apps",
+        )
+    except Exception as e:
+        logger.error(f"Failed to sync apps: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+

reachys_brain/routes/audio_manager.py

@@ -0,0 +1,157 @@
+"""Audio management for conversation handling.
+
+Handles audio buffering, streaming to OpenAI, and microphone control
+during voice conversations.
+"""
+
+import asyncio
+import logging
+from typing import Optional
+
+from .audio_stream_manager import ConversationTimings
+from .conversation_services import get_services, get_state
+
+logger = logging.getLogger(__name__)
+
+
+def flush_audio_buffer() -> None:
+    """Flush all buffered audio chunks to the player.
+    
+    Called after pre-speech animation completes to start audio playback.
+    """
+    services = get_services()
+    state = get_state()
+    
+    if not services.audio_player:
+        state.audio_buffer = []
+        return
+    
+    if state.audio_buffer:
+        logger.info(f"🔊 Flushing {len(state.audio_buffer)} buffered audio chunks")
+        for chunk in state.audio_buffer:
+            services.audio_player.play_chunk(chunk)
+        state.audio_buffer = []
+
+
+def handle_audio_delta(audio_data: bytes) -> None:
+    """Handle AI audio output - buffers initially for pre-speech animation.
+    
+    Args:
+        audio_data: Raw audio bytes from OpenAI.
+    """
+    services = get_services()
+    state = get_state()
+    
+    if state.is_buffering_audio:
+        # Buffer audio until we have text and can play animation
+        state.audio_buffer.append(audio_data)
+    else:
+        # Streaming directly after animation
+        if services.audio_player:
+            services.audio_player.play_chunk(audio_data)
+
+
+async def stream_audio_to_openai() -> None:
+    """Stream audio from microphone to OpenAI.
+    
+    Continuously reads audio chunks from the capture service and
+    sends them to OpenAI for transcription.
+    """
+    services = get_services()
+    
+    if not services.audio_capture or not services.openai:
+        logger.error("Cannot stream: audio_capture or openai not initialized")
+        return
+    
+    logger.info("🎙️ Starting audio stream to OpenAI")
+    
+    chunks_sent = 0
+    consecutive_empty = 0
+    MAX_CONSECUTIVE_EMPTY = 100  # Safety limit to prevent tight loops
+    
+    try:
+        while services.openai.is_connected and services.openai.is_listening:
+            chunk = await services.audio_capture.get_audio_chunk(
+                timeout=ConversationTimings.AUDIO_CHUNK_TIMEOUT_SECONDS
+            )
+            
+            if chunk:
+                await services.openai.send_audio(chunk)
+                chunks_sent += 1
+                consecutive_empty = 0  # Reset counter on successful chunk
+                
+                if chunks_sent % 50 == 0:
+                    logger.info(f"🎙️ Audio streaming active ({chunks_sent} chunks sent)")
+            else:
+                consecutive_empty += 1
+                
+                # Safety check: if we get too many empty responses in a row,
+                # add a small delay to prevent CPU spinning
+                if consecutive_empty >= MAX_CONSECUTIVE_EMPTY:
+                    logger.warning("⚠️ Many consecutive empty audio chunks - adding delay")
+                    await asyncio.sleep(0.5)
+                    consecutive_empty = 0
+    
+    except asyncio.CancelledError:
+        logger.info(f"Audio stream cancelled after {chunks_sent} chunks")
+    except Exception as e:
+        logger.error(f"Error in audio stream: {e}", exc_info=True)
+    
+    logger.info(f"🎙️ Audio stream stopped (sent {chunks_sent} total chunks)")
+
+
+async def delayed_resume_microphone() -> None:
+    """Resume microphone after a delay to prevent echo pickup.
+    
+    Waits for the audio buffer to drain before resuming capture
+    to avoid picking up the AI's own speech.
+    """
+    services = get_services()
+    
+    await asyncio.sleep(ConversationTimings.MICROPHONE_RESUME_DELAY_SECONDS)
+    
+    if (services.audio_capture and 
+        services.openai and 
+        services.openai.is_listening):
+        # Clear OpenAI's audio buffer BEFORE resuming capture to prevent
+        # any buffered audio from being processed as user speech
+        if services.openai:
+            await services.openai.clear_audio_buffer()
+            logger.info("🗑️ Cleared audio buffer before resume")
+        
+        # Brief pause to ensure buffer is cleared on OpenAI's side
+        await asyncio.sleep(0.1)
+        
+        services.audio_capture.resume_capture()
+        logger.info(
+            f"▶️ Resumed microphone (after "
+            f"{ConversationTimings.MICROPHONE_RESUME_DELAY_SECONDS}s delay)"
+        )
+
+
+def start_audio_streaming() -> Optional[asyncio.Task]:
+    """Start the audio streaming task.
+    
+    Returns:
+        The created asyncio Task, or None if already running.
+    """
+    state = get_state()
+    
+    # Cancel existing task if any
+    if state.audio_stream_task:
+        state.audio_stream_task.cancel()
+    
+    state.audio_stream_task = asyncio.create_task(stream_audio_to_openai())
+    logger.info("✅ Audio streaming task started")
+    
+    return state.audio_stream_task
+
+
+def stop_audio_streaming() -> None:
+    """Stop the audio streaming task."""
+    state = get_state()
+    
+    if state.audio_stream_task:
+        state.audio_stream_task.cancel()
+        state.audio_stream_task = None
+

reachys_brain/routes/audio_stream_manager.py

@@ -0,0 +1,151 @@
+"""Audio streaming manager for OpenAI Realtime conversations.
+
+Handles streaming audio from microphone to OpenAI and managing
+the audio pipeline for real-time voice conversations.
+"""
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..audio_capture import AsyncAudioCaptureService
+    from ..openai_realtime import OpenAIRealtimeService
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationTimings:
+    """Named constants for timing-related magic numbers."""
+    
+    # Microphone control
+    MICROPHONE_RESUME_DELAY_SECONDS = 2.5
+    AUDIO_CHUNK_TIMEOUT_SECONDS = 0.1
+    
+    # Animation timings
+    GREETING_ANIMATION_DELAY = 0.3
+    POST_GREETING_PAUSE = 0.5  # Brief pause after greeting animation
+    
+    # Pre-speech animation durations (by sentiment)
+    PRE_SPEECH_DURATION_DEFAULT = 1.0  # seconds
+    PRE_SPEECH_DURATION_STRONG = 1.2   # for excited, happy, sad, apologetic
+    PRE_SPEECH_DURATION_GREETING = 1.5 # warm welcome
+    
+    # Pre-speech animation chances (by sentiment type)
+    # Strong emotions: excited, happy, sad, apologetic
+    PRE_SPEECH_CHANCE_STRONG = 0.90    # 90% chance
+    # Questions and thinking
+    PRE_SPEECH_CHANCE_THINKING = 0.70  # 70% chance
+    # Helpful and neutral
+    PRE_SPEECH_CHANCE_NEUTRAL = 0.50   # 50% chance (up from 25%)
+    # Greeting always plays
+    PRE_SPEECH_CHANCE_GREETING = 1.0   # 100% chance
+
+
+class AudioStreamManager:
+    """Manages audio streaming between microphone and OpenAI.
+    
+    Handles the continuous audio pipeline, including pause/resume
+    functionality for preventing echo during AI speech.
+    """
+    
+    def __init__(
+        self,
+        audio_capture: "AsyncAudioCaptureService",
+        openai_service: "OpenAIRealtimeService",
+    ):
+        """Initialize the audio stream manager.
+        
+        Args:
+            audio_capture: Service for capturing microphone audio.
+            openai_service: Service for communicating with OpenAI.
+        """
+        self._audio_capture = audio_capture
+        self._openai_service = openai_service
+        self._stream_task: asyncio.Task | None = None
+        self._chunks_sent = 0
+    
+    @property
+    def is_streaming(self) -> bool:
+        """Check if audio is currently streaming."""
+        return self._stream_task is not None and not self._stream_task.done()
+    
+    @property
+    def chunks_sent(self) -> int:
+        """Get the number of audio chunks sent in current session."""
+        return self._chunks_sent
+    
+    def start_streaming(self) -> None:
+        """Start streaming audio from microphone to OpenAI."""
+        if self.is_streaming:
+            logger.warning("Audio streaming already active")
+            return
+        
+        self._chunks_sent = 0
+        self._stream_task = asyncio.create_task(self._stream_loop())
+        logger.info("✅ Audio streaming task started")
+    
+    def stop_streaming(self) -> None:
+        """Stop the audio streaming task."""
+        if self._stream_task:
+            self._stream_task.cancel()
+            self._stream_task = None
+            logger.info(f"🎙️ Audio stream stopped (sent {self._chunks_sent} total chunks)")
+    
+    async def _stream_loop(self) -> None:
+        """Main audio streaming loop.
+        
+        Continuously reads audio chunks from the microphone and sends
+        them to OpenAI. Handles pausing automatically (audio_capture
+        manages its own pause state).
+        """
+        logger.info("🎙️ Starting audio stream to OpenAI")
+        
+        try:
+            while self._openai_service.is_connected and self._openai_service.is_listening:
+                # get_audio_chunk returns None on timeout (no audio available)
+                # Audio pausing is handled at capture level - paused capture won't queue chunks
+                chunk = await self._audio_capture.get_audio_chunk(
+                    timeout=ConversationTimings.AUDIO_CHUNK_TIMEOUT_SECONDS
+                )
+                
+                if chunk:
+                    await self._openai_service.send_audio(chunk)
+                    self._chunks_sent += 1
+                    
+                    # Log every 50 chunks (~5 seconds) to show activity
+                    if self._chunks_sent % 50 == 0:
+                        logger.info(f"🎙️ Audio streaming active ({self._chunks_sent} chunks sent)")
+        
+        except asyncio.CancelledError:
+            logger.info(f"Audio stream cancelled after {self._chunks_sent} chunks")
+        except Exception as e:
+            logger.error(f"Error in audio stream: {e}", exc_info=True)
+        
+        logger.info(f"🎙️ Audio stream stopped (sent {self._chunks_sent} total chunks)")
+    
+    def pause_capture(self) -> None:
+        """Pause audio capture (e.g., when AI is speaking)."""
+        self._audio_capture.pause_capture()
+        logger.info("⏸️ Paused microphone (AI speaking)")
+    
+    def resume_capture(self) -> None:
+        """Resume audio capture."""
+        self._audio_capture.resume_capture()
+        logger.info(f"▶️ Resumed microphone (after {ConversationTimings.MICROPHONE_RESUME_DELAY_SECONDS}s delay)")
+    
+    async def delayed_resume(self) -> None:
+        """Resume microphone after a delay to prevent echo pickup.
+        
+        This waits for the audio to finish playing through the speaker
+        before resuming capture to avoid echo.
+        """
+        await asyncio.sleep(ConversationTimings.MICROPHONE_RESUME_DELAY_SECONDS)
+        
+        if self._openai_service.is_listening:
+            self.resume_capture()
+            
+            # Clear any residual audio that might have been buffered
+            await self._openai_service.clear_audio_buffer()
+            logger.info("🗑️ Cleared audio buffer after resume")
+

reachys_brain/routes/broadcast_manager.py

@@ -0,0 +1,105 @@
+"""Client broadcasting utilities for WebSocket connections.
+
+Handles broadcasting messages to connected iOS clients with proper
+error handling, size limits, and disconnection tracking.
+"""
+
+import json
+import logging
+from typing import Set
+
+from fastapi import WebSocket
+
+logger = logging.getLogger(__name__)
+
+# Connected WebSocket clients
+_connected_clients: Set[WebSocket] = set()
+
+
+def get_connected_clients() -> Set[WebSocket]:
+    """Get the set of connected clients."""
+    return _connected_clients
+
+
+def add_client(websocket: WebSocket) -> int:
+    """Add a client to the connected set.
+    
+    Args:
+        websocket: The WebSocket connection to add.
+        
+    Returns:
+        The new total number of connected clients.
+    """
+    _connected_clients.add(websocket)
+    return len(_connected_clients)
+
+
+def remove_client(websocket: WebSocket) -> int:
+    """Remove a client from the connected set.
+    
+    Args:
+        websocket: The WebSocket connection to remove.
+        
+    Returns:
+        The remaining number of connected clients.
+    """
+    _connected_clients.discard(websocket)
+    return len(_connected_clients)
+
+
+async def broadcast(message: dict) -> None:
+    """Broadcast a message to all connected iOS clients.
+    
+    Args:
+        message: Dictionary to broadcast as JSON.
+    """
+    if not _connected_clients:
+        return
+    
+    message_json = json.dumps(message)
+    
+    disconnected = set()
+    for client in _connected_clients:
+        try:
+            await client.send_text(message_json)
+        except Exception as e:
+            logger.error(f"Error sending to client: {e}")
+            disconnected.add(client)
+    
+    _connected_clients.difference_update(disconnected)
+
+
+async def safe_broadcast(message: dict) -> None:
+    """Safely broadcast a message with error handling and size limits.
+    
+    This wrapper around broadcast adds:
+    - Size validation to prevent memory issues
+    - Comprehensive error handling
+    - Logging for debugging
+    
+    Args:
+        message: Dictionary to broadcast as JSON.
+    """
+    try:
+        # Validate message can be serialized
+        try:
+            message_json = json.dumps(message)
+        except (TypeError, ValueError) as e:
+            logger.error(f"Failed to serialize broadcast message: {e}")
+            return
+        
+        # Check message size (max 1MB for WebSocket)
+        max_size = 1024 * 1024  # 1MB
+        if len(message_json) > max_size:
+            logger.warning(f"Broadcast message too large ({len(message_json)} bytes), truncating")
+            # Try to truncate large fields
+            if "existing_html" in message and message["existing_html"]:
+                message["existing_html"] = message["existing_html"][:50000] + "... (truncated)"
+            if "html_content" in message and message["html_content"]:
+                message["html_content"] = message["html_content"][:50000] + "... (truncated)"
+        
+        await broadcast(message)
+        
+    except Exception as e:
+        logger.error(f"Error in safe_broadcast: {e}", exc_info=True)
+

reachys_brain/routes/conversation.py

@@ -0,0 +1,1132 @@
+"""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
+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 _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_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")
+
+
+def cleanup_services() -> None:
+    """Clean up conversation services."""
+    # Cancel all tracked tasks first
+    cancel_all_tracked_tasks()
+    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 _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")
+    
+    start_audio_streaming()
+    
+    await websocket.send_json({
+        "type": "listening_state",
+        "listening": True,
+    })
+    
+    create_tracked_task(send_greeting())
+
+
+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
+            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()
+    
+    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_messages.py

@@ -0,0 +1,190 @@
+"""Multilingual conversation messages for Reachy.
+
+Contains greeting and goodbye messages in multiple languages,
+as well as dance moves for post-speech animations and stop commands.
+"""
+
+# Stop commands that end the conversation when spoken
+# These are checked case-insensitively and should be short/distinct
+STOP_COMMANDS = {
+    "en": ["stop", "stop it", "that's enough", "enough", "shut up", "be quiet"],
+    "nl": ["stop", "stop maar", "genoeg", "hou op", "stil", "wees stil"],
+    "de": ["stop", "stopp", "genug", "halt", "still", "sei still", "hör auf"],
+    "fr": ["stop", "arrête", "assez", "suffit", "tais-toi", "silence"],
+    "es": ["stop", "para", "basta", "suficiente", "cállate", "silencio"],
+    "it": ["stop", "basta", "fermati", "smettila", "silenzio", "zitto"],
+    "pt": ["stop", "pare", "para", "basta", "chega", "silêncio", "cala"],
+}
+
+# Fun dances to play occasionally
+DANCE_MOVES = [
+    "simple_nod", "yeah_nod", "head_tilt_roll", "side_glance_flick",
+    "groovy_sway_and_roll", "uh_huh_tilt"
+]
+
+# Greeting messages by language (when conversation starts)
+# These are used when we don't know the user's name
+GREETINGS = {
+    "en": [
+        "Hello! I'm Reachy. How can I help you today?",
+        "Hi there! Reachy here. What would you like to talk about?",
+        "Hey! Great to see you. What's on your mind?",
+    ],
+    "nl": [
+        "Hallo! Ik ben Reachy. Hoe kan ik je helpen?",
+        "Hoi! Reachy hier. Waar wil je over praten?",
+        "Hey! Leuk je te zien. Wat kan ik voor je doen?",
+    ],
+    "de": [
+        "Hallo! Ich bin Reachy. Wie kann ich dir helfen?",
+        "Hi! Reachy hier. Worüber möchtest du sprechen?",
+        "Hey! Schön dich zu sehen. Was kann ich für dich tun?",
+    ],
+    "fr": [
+        "Bonjour! Je suis Reachy. Comment puis-je vous aider?",
+        "Salut! Reachy ici. De quoi voulez-vous parler?",
+        "Coucou! Ravi de vous voir. Qu'est-ce qui vous amène?",
+    ],
+    "es": [
+        "¡Hola! Soy Reachy. ¿Cómo puedo ayudarte hoy?",
+        "¡Hola! Reachy aquí. ¿De qué te gustaría hablar?",
+        "¡Hey! Qué bueno verte. ¿Qué tienes en mente?",
+    ],
+    "it": [
+        "Ciao! Sono Reachy. Come posso aiutarti oggi?",
+        "Ciao! Reachy qui. Di cosa vorresti parlare?",
+        "Ehi! Bello vederti. Cosa hai in mente?",
+    ],
+    "pt": [
+        "Olá! Eu sou Reachy. Como posso ajudar você hoje?",
+        "Oi! Reachy aqui. Sobre o que você quer conversar?",
+        "Ei! Que bom te ver. O que posso fazer por você?",
+    ],
+}
+
+# Personalized greeting messages by language (when we know the user's name)
+# {name} will be replaced with the user's name
+PERSONALIZED_GREETINGS = {
+    "en": [
+        "Hey {name}! Great to see you again. What can I do for you?",
+        "Hello {name}! How's it going? What would you like to talk about?",
+        "Hi {name}! Nice to see you. How can I help today?",
+        "{name}! Good to see you again. What's on your mind?",
+    ],
+    "nl": [
+        "Hey {name}! Leuk je weer te zien. Wat kan ik voor je doen?",
+        "Hallo {name}! Hoe gaat het? Waar wil je over praten?",
+        "Hoi {name}! Fijn je te zien. Hoe kan ik je helpen?",
+        "{name}! Goed je weer te zien. Wat heb je op je hart?",
+    ],
+    "de": [
+        "Hey {name}! Schön dich wiederzusehen. Was kann ich für dich tun?",
+        "Hallo {name}! Wie geht's? Worüber möchtest du sprechen?",
+        "Hi {name}! Schön dich zu sehen. Wie kann ich dir helfen?",
+        "{name}! Gut dich wiederzusehen. Was hast du auf dem Herzen?",
+    ],
+    "fr": [
+        "Hey {name}! Content de te revoir. Que puis-je faire pour toi?",
+        "Bonjour {name}! Comment ça va? De quoi voudrais-tu parler?",
+        "Salut {name}! Ravi de te voir. Comment puis-je t'aider?",
+        "{name}! Bon de te revoir. Qu'est-ce qui t'amène?",
+    ],
+    "es": [
+        "¡Hey {name}! Qué bueno verte de nuevo. ¿Qué puedo hacer por ti?",
+        "¡Hola {name}! ¿Cómo estás? ¿De qué te gustaría hablar?",
+        "¡Hola {name}! Me alegra verte. ¿En qué puedo ayudarte?",
+        "¡{name}! Qué bueno verte otra vez. ¿Qué tienes en mente?",
+    ],
+    "it": [
+        "Hey {name}! Bello rivederti. Cosa posso fare per te?",
+        "Ciao {name}! Come va? Di cosa vorresti parlare?",
+        "Ciao {name}! Felice di vederti. Come posso aiutarti?",
+        "{name}! Bello rivederti. Cosa hai in mente?",
+    ],
+    "pt": [
+        "Hey {name}! Que bom te ver de novo. O que posso fazer por você?",
+        "Olá {name}! Como você está? Sobre o que quer conversar?",
+        "Oi {name}! Bom te ver. Como posso ajudar?",
+        "{name}! Bom te ver de novo. O que você tem em mente?",
+    ],
+}
+
+# Goodbye messages by language (when conversation ends)
+GOODBYES = {
+    "en": [
+        "Thank you! Speak to you later!",
+        "Goodbye! It was nice talking to you!",
+        "See you later! Take care!",
+    ],
+    "nl": [
+        "Dankjewel! Tot later!",
+        "Dag! Het was leuk om met je te praten!",
+        "Tot ziens! Pas goed op jezelf!",
+    ],
+    "de": [
+        "Danke! Bis später!",
+        "Tschüss! Es war schön mit dir zu reden!",
+        "Bis bald! Pass auf dich auf!",
+    ],
+    "fr": [
+        "Merci! À bientôt!",
+        "Au revoir! C'était agréable de parler avec vous!",
+        "À plus tard! Prenez soin de vous!",
+    ],
+    "es": [
+        "¡Gracias! ¡Hasta luego!",
+        "¡Adiós! ¡Fue un placer hablar contigo!",
+        "¡Nos vemos! ¡Cuídate!",
+    ],
+    "it": [
+        "Grazie! A dopo!",
+        "Arrivederci! È stato bello parlare con te!",
+        "Ci vediamo! Prenditi cura di te!",
+    ],
+    "pt": [
+        "Obrigado! Até mais!",
+        "Tchau! Foi bom conversar com você!",
+        "Até logo! Cuide-se!",
+    ],
+}
+
+# Personalized goodbye messages by language (when we know the user's name)
+# {name} will be replaced with the user's name
+PERSONALIZED_GOODBYES = {
+    "en": [
+        "Goodbye {name}! It was great talking to you!",
+        "See you later {name}! Take care!",
+        "Bye {name}! Talk to you soon!",
+    ],
+    "nl": [
+        "Dag {name}! Het was fijn om met je te praten!",
+        "Tot ziens {name}! Pas goed op jezelf!",
+        "Doei {name}! Tot snel!",
+    ],
+    "de": [
+        "Tschüss {name}! Es war schön mit dir zu reden!",
+        "Bis bald {name}! Pass auf dich auf!",
+        "Ciao {name}! Bis zum nächsten Mal!",
+    ],
+    "fr": [
+        "Au revoir {name}! C'était super de parler avec toi!",
+        "À plus tard {name}! Prends soin de toi!",
+        "Salut {name}! À bientôt!",
+    ],
+    "es": [
+        "¡Adiós {name}! ¡Fue genial hablar contigo!",
+        "¡Hasta luego {name}! ¡Cuídate!",
+        "¡Chao {name}! ¡Nos vemos pronto!",
+    ],
+    "it": [
+        "Ciao {name}! È stato bello parlare con te!",
+        "A presto {name}! Prenditi cura di te!",
+        "Arrivederci {name}! Ci vediamo!",
+    ],
+    "pt": [
+        "Tchau {name}! Foi ótimo conversar com você!",
+        "Até mais {name}! Cuide-se!",
+        "Falou {name}! Até a próxima!",
+    ],
+}
+

reachys_brain/routes/conversation_services.py

@@ -0,0 +1,213 @@
+"""Service instances and lifecycle management for conversation handling.
+
+Centralizes all service initialization and cleanup for the conversation
+system, reducing global state and improving testability.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from ..audio_capture import AsyncAudioCaptureService
+from ..audio_playback import StreamingAudioPlayer
+from ..animation_coordinator import AnimationCoordinator
+from ..motion_service import MotionService
+from ..openai_realtime import OpenAIRealtimeService
+from ..speaking_gestures import SpeakingGesturesService
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ConversationServices:
+    """Container for all conversation-related services.
+    
+    Provides a single point of access for all services needed during
+    a conversation, making dependencies explicit and testable.
+    """
+    
+    openai: Optional[OpenAIRealtimeService] = None
+    audio_capture: Optional[AsyncAudioCaptureService] = None
+    audio_player: Optional[StreamingAudioPlayer] = None
+    motion: Optional[MotionService] = None
+    animation_coordinator: Optional[AnimationCoordinator] = None
+    speaking_gestures: Optional[SpeakingGesturesService] = None
+    
+    # Locks for thread safety
+    pre_speech_animation_lock: Optional[asyncio.Lock] = None
+    
+    # Callbacks for wiring up event handlers
+    on_connection_state: Optional[Callable] = None
+    on_speaking_state: Optional[Callable] = None
+    on_transcript_update: Optional[Callable] = None
+    on_response_text: Optional[Callable] = None
+    on_audio_delta: Optional[Callable] = None
+    on_error: Optional[Callable] = None
+    on_app_change: Optional[Callable] = None
+    on_tool_usage: Optional[Callable] = None
+    on_website_ready: Optional[Callable] = None
+    
+    @property
+    def is_initialized(self) -> bool:
+        """Check if core services are initialized."""
+        return self.openai is not None and self.audio_capture is not None
+
+
+@dataclass
+class ConversationState:
+    """Mutable state for the current conversation.
+    
+    Tracks audio buffering, animation state, and custom configurations.
+    """
+    
+    # Audio buffering for pre-speech animation
+    audio_buffer: list[bytes] = field(default_factory=list)
+    is_buffering_audio: bool = True
+    animation_played_for_response: bool = False
+    
+    # Conversation tracking
+    response_count: int = 0
+    last_response_text: str = ""
+    is_active: bool = False  # True when a conversation is in progress
+    
+    # Custom app state
+    custom_emotion_animations: dict = field(default_factory=dict)
+    
+    # Audio streaming task
+    audio_stream_task: Optional[asyncio.Task] = None
+    
+    def reset_for_new_response(self) -> None:
+        """Reset state for a new AI response."""
+        self.is_buffering_audio = True
+        self.animation_played_for_response = False
+        self.audio_buffer = []
+    
+    def reset_for_new_conversation(self) -> None:
+        """Reset state for a new conversation."""
+        self.response_count = 0
+        self.last_response_text = ""
+        self.is_active = True  # Mark conversation as active
+        self.reset_for_new_response()
+    
+    def end_conversation(self) -> None:
+        """Mark conversation as ended."""
+        self.is_active = False
+
+
+# Global instances (initialized on first use)
+_services: Optional[ConversationServices] = None
+_state: Optional[ConversationState] = None
+
+
+def get_services() -> ConversationServices:
+    """Get or create the conversation services instance.
+    
+    Returns:
+        The ConversationServices singleton.
+    """
+    global _services
+    if _services is None:
+        _services = ConversationServices()
+    return _services
+
+
+def get_state() -> ConversationState:
+    """Get or create the conversation state instance.
+    
+    Returns:
+        The ConversationState singleton.
+    """
+    global _state
+    if _state is None:
+        _state = ConversationState()
+    return _state
+
+
+def init_services() -> ConversationServices:
+    """Initialize all conversation services.
+    
+    Creates and wires up all services needed for voice conversations.
+    
+    Returns:
+        The initialized ConversationServices instance.
+    """
+    services = get_services()
+    
+    # Create service instances
+    services.openai = OpenAIRealtimeService()
+    services.audio_capture = AsyncAudioCaptureService()
+    services.audio_player = StreamingAudioPlayer()
+    services.motion = MotionService()
+    services.animation_coordinator = AnimationCoordinator(services.motion)
+    services.speaking_gestures = SpeakingGesturesService()
+    services.pre_speech_animation_lock = asyncio.Lock()
+    
+    logger.info("Motion service, AnimationCoordinator, and SpeakingGestures initialized")
+    logger.info("Conversation services initialized")
+    
+    return services
+
+
+def cleanup_services() -> None:
+    """Clean up all conversation services."""
+    services = get_services()
+    state = get_state()
+    
+    # Cancel audio streaming task
+    if state.audio_stream_task:
+        state.audio_stream_task.cancel()
+        state.audio_stream_task = None
+    
+    if services.audio_capture:
+        services.audio_capture.cleanup()
+    
+    if services.audio_player:
+        services.audio_player.cleanup()
+    
+    # Stop speaking gestures if running
+    if services.speaking_gestures:
+        asyncio.create_task(services.speaking_gestures.close())
+    
+    logger.info("Conversation services cleaned up")
+
+
+def wire_openai_callbacks(
+    on_connection_state: Callable,
+    on_speaking_state: Callable,
+    on_transcript_update: Callable,
+    on_response_text: Callable,
+    on_audio_delta: Callable,
+    on_error: Callable,
+    on_app_change: Callable,
+    on_tool_usage: Callable,
+    on_website_ready: Callable,
+) -> None:
+    """Wire up callbacks from OpenAI service to handlers.
+    
+    Args:
+        on_connection_state: Handler for connection state changes.
+        on_speaking_state: Handler for speaking state changes.
+        on_transcript_update: Handler for transcript updates.
+        on_response_text: Handler for response text.
+        on_audio_delta: Handler for audio data.
+        on_error: Handler for errors.
+        on_app_change: Handler for app changes.
+        on_tool_usage: Handler for tool usage.
+        on_website_ready: Handler for website ready events.
+    """
+    services = get_services()
+    
+    if not services.openai:
+        raise RuntimeError("OpenAI service not initialized")
+    
+    services.openai.on_connection_state = on_connection_state
+    services.openai.on_speaking_state = on_speaking_state
+    services.openai.on_transcript_update = on_transcript_update
+    services.openai.on_response_text = on_response_text
+    services.openai.on_audio_delta = on_audio_delta
+    services.openai.on_error = on_error
+    services.openai.on_app_change = on_app_change
+    services.openai.on_tool_usage = on_tool_usage
+    services.openai.on_website_ready = on_website_ready
+