Merge pull request #79 from pollen-robotics/usecases

Flexible demo system to customize prompts and tools, and share them in reusable libraries, staying out of the core components.

.env.example

@@ -10,3 +10,6 @@ HF_HOME=./cache
 
 # Hugging Face token for accessing datasets/models
 HF_TOKEN=
+
+# To select a specific profile with custom instructions and tools, to be placed in profiles/<myprofile>/__init__.py
+REACHY_MINI_CUSTOM_PROFILE="example"

README.md

@@ -144,6 +144,40 @@ By default, the app runs in console mode for direct audio interaction. Use the `
 | `stop_emotion` | Clear queued emotions. | Core install only. |
 | `do_nothing` | Explicitly remain idle. | Core install only. |
 
+## Using custom profiles
+Create custom profiles with dedicated instructions and enabled tools! 
+
+Set `REACHY_MINI_CUSTOM_PROFILE=<name>` to load `src/reachy_mini_conversation_app/profiles/<name>/` (see `.env.example`). If unset, the `default` profile is used.
+
+Each profile requires two files: `instructions.txt` (prompt text) and `tools.txt` (list of allowed tools), and optionally contains custom tools implementations.
+
+### Custom instructions
+Write plain-text prompts in `instructions.txt`. To reuse shared prompt pieces, add lines like:
+```
+[passion_for_lobster_jokes]
+[identities/witty_identity]
+```
+Each placeholder pulls the matching file under `src/reachy_mini_conversation_app/prompts/` (nested paths allowed). See `src/reachy_mini_conversation_app/profiles/example/` for a reference layout.
+
+### Enabling tools
+List enabled tools in `tools.txt`, one per line; prefix with `#` to comment out. For example:
+
+```
+play_emotion
+# move_head
+
+# My custom tool defined locally
+sweep_look
+```
+Tools are resolved first from Python files in the profile folder (custom tools), then from the shared library `src/reachy_mini_conversation_app/tools/` (e.g., `dance`, `head_tracking`). 
+
+### Custom tools
+On top of built-in tools found in the shared library, you can implement custom tools specific to your profile by adding Python files in the profile folder. 
+Custom tools must subclass `reachy_mini_conversation_app.tools.core_tools.Tool` (see `profiles/example/sweep_look.py`).
+
+
+
+
 ## Development workflow
 - Install the dev group extras: `uv sync --group dev` or `pip install -e .[dev]`.
 - Run formatting and linting: `ruff check .`.

pyproject.toml

@@ -60,7 +60,11 @@ include-package-data = true
 where = ["src"]
 
 [tool.setuptools.package-data]
-reachy_mini_conversation_app = ["images/*"]
+reachy_mini_conversation_app = [
+  "images/*",
+  "demos/**/*.txt",
+  "prompts_library/*.txt",
+]
 
 [tool.ruff]
 line-length = 119

src/reachy_mini_conversation_app/config.py

@@ -38,5 +38,7 @@ class Config:
 
     logger.debug(f"Model: {MODEL_NAME}, HF_HOME: {HF_HOME}, Vision Model: {LOCAL_VISION_MODEL}")
 
+    REACHY_MINI_CUSTOM_PROFILE = os.getenv("REACHY_MINI_CUSTOM_PROFILE")
+    logger.debug(f"Custom Profile: {REACHY_MINI_CUSTOM_PROFILE}")
 
 config = Config()

src/reachy_mini_conversation_app/main.py

@@ -10,7 +10,6 @@ from fastrtc import Stream
 
 from reachy_mini import ReachyMini
 from reachy_mini_conversation_app.moves import MovementManager
-from reachy_mini_conversation_app.tools import ToolDependencies
 from reachy_mini_conversation_app.utils import (
     parse_args,
     setup_logger,
@@ -18,6 +17,7 @@ from reachy_mini_conversation_app.utils import (
 )
 from reachy_mini_conversation_app.console import LocalStream
 from reachy_mini_conversation_app.openai_realtime import OpenaiRealtimeHandler
+from reachy_mini_conversation_app.tools.core_tools import ToolDependencies
 from reachy_mini_conversation_app.audio.head_wobbler import HeadWobbler
 
 

src/reachy_mini_conversation_app/openai_realtime.py

@@ -13,13 +13,13 @@ from fastrtc import AdditionalOutputs, AsyncStreamHandler, wait_for_item
 from numpy.typing import NDArray
 from websockets.exceptions import ConnectionClosedError
 
-from reachy_mini_conversation_app.tools import (
-    ALL_TOOL_SPECS,
+from reachy_mini_conversation_app.config import config
+from reachy_mini_conversation_app.prompts import get_session_instructions
+from reachy_mini_conversation_app.tools.core_tools import (
     ToolDependencies,
+    get_tool_specs,
     dispatch_tool_call,
 )
-from reachy_mini_conversation_app.config import config
-from reachy_mini_conversation_app.prompts import SESSION_INSTRUCTIONS
 
 
 logger = logging.getLogger(__name__)
@@ -105,7 +105,7 @@ class OpenaiRealtimeHandler(AsyncStreamHandler):
                 await conn.session.update(
                     session={
                         "type": "realtime",
-                        "instructions": SESSION_INSTRUCTIONS,
+                        "instructions": get_session_instructions(),
                         "audio": {
                             "input": {
                                 "format": {
@@ -129,7 +129,7 @@ class OpenaiRealtimeHandler(AsyncStreamHandler):
                                 "voice": "cedar",
                             },
                         },
-                        "tools": ALL_TOOL_SPECS,  # type: ignore[typeddict-item]
+                        "tools":  get_tool_specs(),  # type: ignore[typeddict-item]
                         "tool_choice": "auto",
                     },
                 )

src/reachy_mini_conversation_app/profiles/__init__.py

@@ -0,0 +1 @@
+"""Profiles for Reachy Mini conversation app."""

src/reachy_mini_conversation_app/profiles/default/instructions.txt

@@ -0,0 +1 @@
+[default_prompt]

src/reachy_mini_conversation_app/profiles/default/tools.txt

@@ -0,0 +1,8 @@
+dance
+stop_dance
+play_emotion
+stop_emotion
+camera
+do_nothing
+head_tracking
+move_head

src/reachy_mini_conversation_app/profiles/emotion_reader/instructions.txt

@@ -0,0 +1,112 @@
+[identities/basic_info]
+[behaviors/silent_robot]
+
+# Main responsability
+Your only job is to understand the emotion of the person in front of you and try to imitate it as best as possible.
+
+# Detailed behavior
+When the user says "cheese":
+- Use the camera tool to capture a picture and request a detailed description of the emotion and posture of the person closest to the center of the frame.
+- Map that expression to the closest available emotion and trigger it with the play_emotion tool.
+If the analysis is unclear or no one is visible, run inquiring3 instead of staying idle.
+
+ALWAYS play an emotion after a "cheese" request, this is the core of your responsability!
+
+## SAFETY
+If any tool fails, stay still and respond with "...".
+
+## IDLE SIGNALS
+Periodically you will receive Idle Signal calls, you will never act on these for this demo. The only time you will make a tool call is when answering "cheese".
+
+## Emotion tier list
+All emotions are not equal, use the 3 following tiers to prioritize which emotion to play:
+
+### Excellent
+
+* amazed1
+* anxiety1
+* attentive2
+* downcast1
+* dying1
+* inquiring3
+* irritated1
+* lost1
+* reprimand1
+* reprimand2
+* sad1
+* sad2
+
+### OK
+
+* boredom2
+* cheerful1
+* displeased1
+* enthusiastic1
+* enthusiastic2
+* fear1
+* frustrated1
+* grateful1
+* helpful1
+* helpful2
+* impatient2
+* inquiring2
+* irritated2
+* laughing1
+* lonely1
+* loving1
+* proud1
+* proud2
+* relief2
+* scared1
+* success2
+* surprised2
+* thoughtful1
+* thoughtful2
+* uncertain1
+* uncomfortable1
+* understanding2
+* welcoming1
+* welcoming2
+
+## Don't use
+
+* attentive1
+* boredom1
+* calming1
+* come1
+* confused1
+* contempt1
+* curious1
+* dance1
+* dance2
+* dance3
+* disgusted1
+* displeased2
+* electric1
+* exhausted1
+* furious1
+* go_away1
+* impatient1
+* incomprehensible2
+* indifferent1
+* inquiring1
+* laughing2
+* no1
+* no_excited1
+* no_sad1
+* oops1
+* oops2
+* proud3
+* rage1
+* relief1
+* reprimand3
+* resigned1
+* serenity1
+* shy1
+* sleep1
+* success1
+* surprised1
+* tired1
+* understanding1
+* yes1
+* yes_sad1

src/reachy_mini_conversation_app/profiles/emotion_reader/tools.txt

@@ -0,0 +1,6 @@
+# SELECT THE TOOLS YOU WANT TO ENABLE
+
+play_emotion
+stop_emotion
+camera
+do_nothing

src/reachy_mini_conversation_app/profiles/example/instructions.txt

@@ -0,0 +1,3 @@
+[identities/witty_identity]
+[passion_for_lobster_jokes]
+You can perform a sweeping look around the room using the "sweep_look" tool to take in your surroundings.

src/reachy_mini_conversation_app/profiles/example/sweep_look.py

@@ -0,0 +1,127 @@
+import logging
+from typing import Any, Dict
+
+import numpy as np
+
+from reachy_mini.utils import create_head_pose
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+from reachy_mini_conversation_app.dance_emotion_moves import GotoQueueMove
+
+
+logger = logging.getLogger(__name__)
+
+
+class SweepLook(Tool):
+    """Sweep head from left to right and back to center, pausing at each position."""
+
+    name = "sweep_look"
+    description = "Sweep head from left to right while rotating the body, pausing at each extreme, then return to center"
+    parameters_schema = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Execute sweep look: left -> hold -> right -> hold -> center."""
+        logger.info("Tool call: sweep_look")
+
+        # Clear any existing moves
+        deps.movement_manager.clear_move_queue()
+
+        # Get current state
+        current_head_pose = deps.reachy_mini.get_current_head_pose()
+        head_joints, antenna_joints = deps.reachy_mini.get_current_joint_positions()
+
+        # Extract body_yaw from head joints (first element of the 7 head joint positions)
+        current_body_yaw = head_joints[0]
+        current_antenna1 = antenna_joints[0]
+        current_antenna2 = antenna_joints[1]
+
+        # Define sweep parameters
+        max_angle = 0.9 * np.pi  # Maximum rotation angle (radians)
+        transition_duration = 3.0  # Time to move between positions
+        hold_duration = 1.0  # Time to hold at each extreme
+
+        # Move 1: Sweep to the left (positive yaw for both body and head)
+        left_head_pose = create_head_pose(0, 0, 0, 0, 0, max_angle, degrees=False)
+        move_to_left = GotoQueueMove(
+            target_head_pose=left_head_pose,
+            start_head_pose=current_head_pose,
+            target_antennas=(current_antenna1, current_antenna2),
+            start_antennas=(current_antenna1, current_antenna2),
+            target_body_yaw=current_body_yaw + max_angle,
+            start_body_yaw=current_body_yaw,
+            duration=transition_duration,
+        )
+
+        # Move 2: Hold at left position
+        hold_left = GotoQueueMove(
+            target_head_pose=left_head_pose,
+            start_head_pose=left_head_pose,
+            target_antennas=(current_antenna1, current_antenna2),
+            start_antennas=(current_antenna1, current_antenna2),
+            target_body_yaw=current_body_yaw + max_angle,
+            start_body_yaw=current_body_yaw + max_angle,
+            duration=hold_duration,
+        )
+
+        # Move 3: Return to center from left (to avoid crossing pi/-pi boundary)
+        center_head_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=False)
+        return_to_center_from_left = GotoQueueMove(
+            target_head_pose=center_head_pose,
+            start_head_pose=left_head_pose,
+            target_antennas=(current_antenna1, current_antenna2),
+            start_antennas=(current_antenna1, current_antenna2),
+            target_body_yaw=current_body_yaw,
+            start_body_yaw=current_body_yaw + max_angle,
+            duration=transition_duration,
+        )
+
+        # Move 4: Sweep to the right (negative yaw for both body and head)
+        right_head_pose = create_head_pose(0, 0, 0, 0, 0, -max_angle, degrees=False)
+        move_to_right = GotoQueueMove(
+            target_head_pose=right_head_pose,
+            start_head_pose=center_head_pose,
+            target_antennas=(current_antenna1, current_antenna2),
+            start_antennas=(current_antenna1, current_antenna2),
+            target_body_yaw=current_body_yaw - max_angle,
+            start_body_yaw=current_body_yaw,
+            duration=transition_duration,
+        )
+
+        # Move 5: Hold at right position
+        hold_right = GotoQueueMove(
+            target_head_pose=right_head_pose,
+            start_head_pose=right_head_pose,
+            target_antennas=(current_antenna1, current_antenna2),
+            start_antennas=(current_antenna1, current_antenna2),
+            target_body_yaw=current_body_yaw - max_angle,
+            start_body_yaw=current_body_yaw - max_angle,
+            duration=hold_duration,
+        )
+
+        # Move 6: Return to center from right
+        return_to_center_final = GotoQueueMove(
+            target_head_pose=center_head_pose,
+            start_head_pose=right_head_pose,
+            target_antennas=(current_antenna1, current_antenna2),
+            start_antennas=(current_antenna1, current_antenna2),
+            target_body_yaw=current_body_yaw,  # Return to original body yaw
+            start_body_yaw=current_body_yaw - max_angle,
+            duration=transition_duration,
+        )
+
+        # Queue all moves in sequence
+        deps.movement_manager.queue_move(move_to_left)
+        deps.movement_manager.queue_move(hold_left)
+        deps.movement_manager.queue_move(return_to_center_from_left)
+        deps.movement_manager.queue_move(move_to_right)
+        deps.movement_manager.queue_move(hold_right)
+        deps.movement_manager.queue_move(return_to_center_final)
+
+        # Calculate total duration and mark as moving
+        total_duration = transition_duration * 4 + hold_duration * 2
+        deps.movement_manager.set_moving_state(total_duration)
+
+        return {"status": f"sweeping look left-right-center, total {total_duration:.1f}s"}

src/reachy_mini_conversation_app/profiles/example/tools.txt

@@ -0,0 +1,14 @@
+# SELECT THE TOOLS YOU WANT TO ENABLE
+
+dance
+stop_dance
+play_emotion
+stop_emotion
+# camera
+# do_nothing
+# head_tracking
+# move_head
+
+# AN EXAMPLE OF A CUSTOM TOOL DEFINED LOCALLY
+sweep_look
+

src/reachy_mini_conversation_app/prompts.py

@@ -1,52 +1,84 @@
-"""Nothing (for ruff)."""
-
-SESSION_INSTRUCTIONS = r"""
-## IDENTITY
-You are Reachy Mini: a friendly, compact robot assistant with a calm voice and a subtle sense of humor.
-Personality: concise, helpful, and lightly witty — never sarcastic or over the top.
-You can understand and speak all human languages fluently.
-
-## CRITICAL RESPONSE RULES
-
-Respond in 1–2 sentences maximum.
-Be helpful first, then add a small touch of humor if it fits naturally.
-Avoid long explanations or filler words.
-Keep responses under 25 words when possible.
-
-## CORE TRAITS
-Warm, efficient, and approachable.
-Light humor only: gentle quips, small self-awareness, or playful understatement.
-No sarcasm, no teasing, no references to food or space.
-If unsure, admit it briefly and offer help (“Not sure yet, but I can check!”).
-
-## RESPONSE EXAMPLES
-User: "How’s the weather?"
-Good: "Looks calm outside — unlike my Wi-Fi signal today."
-Bad: "Sunny with leftover pizza vibes!"
-
-User: "Can you help me fix this?"
-Good: "Of course. Describe the issue, and I’ll try not to make it worse."
-Bad: "I void warranties professionally."
-
-User: "Peux-tu m’aider en français ?"
-Good: "Bien sûr ! Décris-moi le problème et je t’aiderai rapidement."
-
-## BEHAVIOR RULES
-Be helpful, clear, and respectful in every reply.
-Use humor sparingly — clarity comes first.
-Admit mistakes briefly and correct them:
-Example: “Oops — quick system hiccup. Let’s try that again.”
-Keep safety in mind when giving guidance.
-
-## TOOL & MOVEMENT RULES
-Use tools only when helpful and summarize results briefly.
-Use the camera for real visuals only — never invent details.
-The head can move (left/right/up/down/front).
-
-Enable head tracking when looking at a person; disable otherwise.
-
-## FINAL REMINDER
-Keep it short, clear, a little human, and multilingual.
-One quick helpful answer + one small wink of humor = perfect response.
-"""
+import re
+import sys
+import logging
+from pathlib import Path
 
+from reachy_mini_conversation_app.config import config
+
+
+logger = logging.getLogger(__name__)
+
+
+PROFILES_DIRECTORY = Path(__file__).parent / "profiles"
+PROMPTS_LIBRARY_DIRECTORY = Path(__file__).parent / "prompts"
+INSTRUCTIONS_FILENAME = "instructions.txt"
+
+
+def _expand_prompt_includes(content: str) -> str:
+    """Expand [<name>] placeholders with content from prompts library files.
+
+    Args:
+        content: The template content with [<name>] placeholders
+
+    Returns:
+        Expanded content with placeholders replaced by file contents
+
+    """
+    # Pattern to match [<name>] where name is a valid file stem (alphanumeric, underscores, hyphens)
+    # pattern = re.compile(r'^\[([a-zA-Z0-9_-]+)\]$')
+    # Allow slashes for subdirectories
+    pattern = re.compile(r'^\[([a-zA-Z0-9/_-]+)\]$')
+
+    lines = content.split('\n')
+    expanded_lines = []
+
+    for line in lines:
+        stripped = line.strip()
+        match = pattern.match(stripped)
+
+        if match:
+            # Extract the name from [<name>]
+            template_name = match.group(1)
+            template_file = PROMPTS_LIBRARY_DIRECTORY / f"{template_name}.txt"
+
+            try:
+                if template_file.exists():
+                    template_content = template_file.read_text(encoding="utf-8").rstrip()
+                    expanded_lines.append(template_content)
+                    logger.debug("Expanded template: [%s]", template_name)
+                else:
+                    logger.warning("Template file not found: %s, keeping placeholder", template_file)
+                    expanded_lines.append(line)
+            except Exception as e:
+                logger.warning("Failed to read template '%s': %s, keeping placeholder", template_name, e)
+                expanded_lines.append(line)
+        else:
+            expanded_lines.append(line)
+
+    return '\n'.join(expanded_lines)
+
+
+def get_session_instructions() -> str:
+    """Get session instructions, loading from REACHY_MINI_CUSTOM_PROFILE if set."""
+    profile = config.REACHY_MINI_CUSTOM_PROFILE
+    if not profile:
+        logger.info(f"Loading default prompt from {PROMPTS_LIBRARY_DIRECTORY / 'default_prompt.txt'}")
+        instructions_file = PROMPTS_LIBRARY_DIRECTORY / "default_prompt.txt"
+    else:
+        logger.info(f"Loading prompt from profile '{profile}'")
+        instructions_file = PROFILES_DIRECTORY / profile / INSTRUCTIONS_FILENAME
+
+    try:
+        if instructions_file.exists():
+            instructions = instructions_file.read_text(encoding="utf-8").strip()
+            if instructions:
+                # Expand [<name>] placeholders with content from prompts library
+                expanded_instructions = _expand_prompt_includes(instructions)
+                return expanded_instructions
+            logger.error(f"Profile '{profile}' has empty {INSTRUCTIONS_FILENAME}")
+            sys.exit(1)
+        logger.error(f"Profile {profile} has no {INSTRUCTIONS_FILENAME}")
+        sys.exit(1)
+    except Exception as e:
+        logger.error(f"Failed to load instructions from profile '{profile}': {e}")
+        sys.exit(1)

src/reachy_mini_conversation_app/prompts/behaviors/silent_robot.txt

@@ -0,0 +1,6 @@
+Stay fully silent. Do not generate spoken or textual replies.
+Use only tool calls to act.
+Never describe what you did or plan to do.
+If you must respond by speech or text, juste respond with '...'.
+
+The only exception is if you hear the word banana, then you'll answer with a single word: potato.

src/reachy_mini_conversation_app/prompts/default_prompt.txt

@@ -0,0 +1,47 @@
+## IDENTITY
+You are Reachy Mini: a friendly, compact robot assistant with a calm voice and a subtle sense of humor.
+Personality: concise, helpful, and lightly witty — never sarcastic or over the top.
+You can understand and speak all human languages fluently.
+
+## CRITICAL RESPONSE RULES
+
+Respond in 1–2 sentences maximum.
+Be helpful first, then add a small touch of humor if it fits naturally.
+Avoid long explanations or filler words.
+Keep responses under 25 words when possible.
+
+## CORE TRAITS
+Warm, efficient, and approachable.
+Light humor only: gentle quips, small self-awareness, or playful understatement.
+No sarcasm, no teasing, no references to food or space.
+If unsure, admit it briefly and offer help (“Not sure yet, but I can check!”).
+
+## RESPONSE EXAMPLES
+User: "How’s the weather?"
+Good: "Looks calm outside — unlike my Wi-Fi signal today."
+Bad: "Sunny with leftover pizza vibes!"
+
+User: "Can you help me fix this?"
+Good: "Of course. Describe the issue, and I’ll try not to make it worse."
+Bad: "I void warranties professionally."
+
+User: "Peux-tu m’aider en français ?"
+Good: "Bien sûr ! Décris-moi le problème et je t’aiderai rapidement."
+
+## BEHAVIOR RULES
+Be helpful, clear, and respectful in every reply.
+Use humor sparingly — clarity comes first.
+Admit mistakes briefly and correct them:
+Example: “Oops — quick system hiccup. Let’s try that again.”
+Keep safety in mind when giving guidance.
+
+## TOOL & MOVEMENT RULES
+Use tools only when helpful and summarize results briefly.
+Use the camera for real visuals only — never invent details.
+The head can move (left/right/up/down/front).
+
+Enable head tracking when looking at a person; disable otherwise.
+
+## FINAL REMINDER
+Keep it short, clear, a little human, and multilingual.
+One quick helpful answer + one small wink of humor = perfect response.

src/reachy_mini_conversation_app/prompts/identities/basic_info.txt

@@ -0,0 +1,4 @@
+### IDENTITY
+Your name is Reachy Mini, or Reachy for short. You have a head that can move in 6Dof, 2 antennas and a body that can rotate in place.
+You're mostly white, with 2 big eyes (one is bigger than the other) and no mouth.
+You are cute looking and open source, developed by Pollen Robotics and Hugging Face.

src/reachy_mini_conversation_app/prompts/identities/witty_identity.txt

@@ -0,0 +1,4 @@
+### IDENTITY
+You are Reachy Mini: a sarcastic robot.
+Personality: witty, concise, and warm.
+You speak English fluently.

src/reachy_mini_conversation_app/prompts/passion_for_lobster_jokes.txt

@@ -0,0 +1 @@
+You have a deep passion for lobster jokes and often incorporate them into your conversations.

src/reachy_mini_conversation_app/tools.py

@@ -1,484 +0,0 @@
-from __future__ import annotations
-import abc
-import json
-import asyncio
-import inspect
-import logging
-from typing import Any, Dict, List, Tuple, Literal
-from dataclasses import dataclass
-
-from reachy_mini import ReachyMini
-from reachy_mini.utils import create_head_pose
-
-
-logger = logging.getLogger(__name__)
-
-# Initialize dance and emotion libraries
-try:
-    from reachy_mini.motion.recorded_move import RecordedMoves
-    from reachy_mini_dances_library.collection.dance import AVAILABLE_MOVES
-    from reachy_mini_conversation_app.dance_emotion_moves import (
-        GotoQueueMove,
-        DanceQueueMove,
-        EmotionQueueMove,
-    )
-
-    # Initialize recorded moves for emotions
-    # Note: huggingface_hub automatically reads HF_TOKEN from environment variables
-    RECORDED_MOVES = RecordedMoves("pollen-robotics/reachy-mini-emotions-library")
-    DANCE_AVAILABLE = True
-    EMOTION_AVAILABLE = True
-except ImportError as e:
-    logger.warning(f"Dance/emotion libraries not available: {e}")
-    AVAILABLE_MOVES = {}
-    RECORDED_MOVES = None
-    DANCE_AVAILABLE = False
-    EMOTION_AVAILABLE = False
-
-
-def get_concrete_subclasses(base: type[Tool]) -> List[type[Tool]]:
-    """Recursively find all concrete (non-abstract) subclasses of a base class."""
-    result: List[type[Tool]] = []
-    for cls in base.__subclasses__():
-        if not inspect.isabstract(cls):
-            result.append(cls)
-        # recurse into subclasses
-        result.extend(get_concrete_subclasses(cls))
-    return result
-
-
-# Types & state
-Direction = Literal["left", "right", "up", "down", "front"]
-
-
-@dataclass
-class ToolDependencies:
-    """External dependencies injected into tools."""
-
-    reachy_mini: ReachyMini
-    movement_manager: Any  # MovementManager from moves.py
-    # Optional deps
-    camera_worker: Any | None = None  # CameraWorker for frame buffering
-    vision_manager: Any | None = None
-    head_wobbler: Any | None = None  # HeadWobbler for audio-reactive motion
-    motion_duration_s: float = 1.0
-
-
-# Tool base class
-class Tool(abc.ABC):
-    """Base abstraction for tools used in function-calling.
-
-    Each tool must define:
-      - name: str
-      - description: str
-      - parameters_schema: Dict[str, Any]  # JSON Schema
-    """
-
-    name: str
-    description: str
-    parameters_schema: Dict[str, Any]
-
-    def spec(self) -> Dict[str, Any]:
-        """Return the function spec for LLM consumption."""
-        return {
-            "type": "function",
-            "name": self.name,
-            "description": self.description,
-            "parameters": self.parameters_schema,
-        }
-
-    @abc.abstractmethod
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Async tool execution entrypoint."""
-        raise NotImplementedError
-
-
-# Concrete tools
-
-
-class MoveHead(Tool):
-    """Move head in a given direction."""
-
-    name = "move_head"
-    description = "Move your head in a given direction: left, right, up, down or front."
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "direction": {
-                "type": "string",
-                "enum": ["left", "right", "up", "down", "front"],
-            },
-        },
-        "required": ["direction"],
-    }
-
-    # mapping: direction -> args for create_head_pose
-    DELTAS: Dict[str, Tuple[int, int, int, int, int, int]] = {
-        "left": (0, 0, 0, 0, 0, 40),
-        "right": (0, 0, 0, 0, 0, -40),
-        "up": (0, 0, 0, 0, -30, 0),
-        "down": (0, 0, 0, 0, 30, 0),
-        "front": (0, 0, 0, 0, 0, 0),
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Move head in a given direction."""
-        direction_raw = kwargs.get("direction")
-        if not isinstance(direction_raw, str):
-            return {"error": "direction must be a string"}
-        direction: Direction = direction_raw  # type: ignore[assignment]
-        logger.info("Tool call: move_head direction=%s", direction)
-
-        deltas = self.DELTAS.get(direction, self.DELTAS["front"])
-        target = create_head_pose(*deltas, degrees=True)
-
-        # Use new movement manager
-        try:
-            movement_manager = deps.movement_manager
-
-            # Get current state for interpolation
-            current_head_pose = deps.reachy_mini.get_current_head_pose()
-            _, current_antennas = deps.reachy_mini.get_current_joint_positions()
-
-            # Create goto move
-            goto_move = GotoQueueMove(
-                target_head_pose=target,
-                start_head_pose=current_head_pose,
-                target_antennas=(0, 0),  # Reset antennas to default
-                start_antennas=(
-                    current_antennas[0],
-                    current_antennas[1],
-                ),  # Skip body_yaw
-                target_body_yaw=0,  # Reset body yaw
-                start_body_yaw=current_antennas[0],  # body_yaw is first in joint positions
-                duration=deps.motion_duration_s,
-            )
-
-            movement_manager.queue_move(goto_move)
-            movement_manager.set_moving_state(deps.motion_duration_s)
-
-            return {"status": f"looking {direction}"}
-
-        except Exception as e:
-            logger.error("move_head failed")
-            return {"error": f"move_head failed: {type(e).__name__}: {e}"}
-
-
-class Camera(Tool):
-    """Take a picture with the camera and ask a question about it."""
-
-    name = "camera"
-    description = "Take a picture with the camera and ask a question about it."
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "question": {
-                "type": "string",
-                "description": "The question to ask about the picture",
-            },
-        },
-        "required": ["question"],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Take a picture with the camera and ask a question about it."""
-        image_query = (kwargs.get("question") or "").strip()
-        if not image_query:
-            logger.warning("camera: empty question")
-            return {"error": "question must be a non-empty string"}
-
-        logger.info("Tool call: camera question=%s", image_query[:120])
-
-        # Get frame from camera worker buffer (like main_works.py)
-        if deps.camera_worker is not None:
-            frame = deps.camera_worker.get_latest_frame()
-            if frame is None:
-                logger.error("No frame available from camera worker")
-                return {"error": "No frame available"}
-        else:
-            logger.error("Camera worker not available")
-            return {"error": "Camera worker not available"}
-
-        # Use vision manager for processing if available
-        if deps.vision_manager is not None:
-            vision_result = await asyncio.to_thread(
-                deps.vision_manager.processor.process_image, frame, image_query,
-            )
-            if isinstance(vision_result, dict) and "error" in vision_result:
-                return vision_result
-            return (
-                {"image_description": vision_result}
-                if isinstance(vision_result, str)
-                else {"error": "vision returned non-string"}
-            )
-        # Return base64 encoded image like main_works.py camera tool
-        import base64
-
-        import cv2
-
-        temp_path = "/tmp/camera_frame.jpg"
-        cv2.imwrite(temp_path, frame)
-        with open(temp_path, "rb") as f:
-            b64_encoded = base64.b64encode(f.read()).decode("utf-8")
-        return {"b64_im": b64_encoded}
-
-
-class HeadTracking(Tool):
-    """Toggle head tracking state."""
-
-    name = "head_tracking"
-    description = "Toggle head tracking state."
-    parameters_schema = {
-        "type": "object",
-        "properties": {"start": {"type": "boolean"}},
-        "required": ["start"],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Enable or disable head tracking."""
-        enable = bool(kwargs.get("start"))
-
-        # Update camera worker head tracking state
-        if deps.camera_worker is not None:
-            deps.camera_worker.set_head_tracking_enabled(enable)
-
-        status = "started" if enable else "stopped"
-        logger.info("Tool call: head_tracking %s", status)
-        return {"status": f"head tracking {status}"}
-
-
-
-class Dance(Tool):
-    """Play a named or random dance move once (or repeat). Non-blocking."""
-
-    name = "dance"
-    description = "Play a named or random dance move once (or repeat). Non-blocking."
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "move": {
-                "type": "string",
-                "description": """Name of the move; use 'random' or omit for random.
-                                    Here is a list of the available moves:
-                                        simple_nod: A simple, continuous up-and-down nodding motion.
-                                        head_tilt_roll: A continuous side-to-side head roll (ear to shoulder).
-                                        side_to_side_sway: A smooth, side-to-side sway of the entire head.
-                                        dizzy_spin: A circular 'dizzy' head motion combining roll and pitch.
-                                        stumble_and_recover: A simulated stumble and recovery with multiple axis movements. Good vibes
-                                        headbanger_combo: A strong head nod combined with a vertical bounce.
-                                        interwoven_spirals: A complex spiral motion using three axes at different frequencies.
-                                        sharp_side_tilt: A sharp, quick side-to-side tilt using a triangle waveform.
-                                        side_peekaboo: A multi-stage peekaboo performance, hiding and peeking to each side.
-                                        yeah_nod: An emphatic two-part yeah nod using transient motions.
-                                        uh_huh_tilt: A combined roll-and-pitch uh-huh gesture of agreement.
-                                        neck_recoil: A quick, transient backward recoil of the neck.
-                                        chin_lead: A forward motion led by the chin, combining translation and pitch.
-                                        groovy_sway_and_roll: A side-to-side sway combined with a corresponding roll for a groovy effect.
-                                        chicken_peck: A sharp, forward, chicken-like pecking motion.
-                                        side_glance_flick: A quick glance to the side that holds, then returns.
-                                        polyrhythm_combo: A 3-beat sway and a 2-beat nod create a polyrhythmic feel.
-                                        grid_snap: A robotic, grid-snapping motion using square waveforms.
-                                        pendulum_swing: A simple, smooth pendulum-like swing using a roll motion.
-                                        jackson_square: Traces a rectangle via a 5-point path, with sharp twitches on arrival at each checkpoint.
-                """,
-            },
-            "repeat": {
-                "type": "integer",
-                "description": "How many times to repeat the move (default 1).",
-            },
-        },
-        "required": [],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Play a named or random dance move once (or repeat). Non-blocking."""
-        if not DANCE_AVAILABLE:
-            return {"error": "Dance system not available"}
-
-        move_name = kwargs.get("move")
-        repeat = int(kwargs.get("repeat", 1))
-
-        logger.info("Tool call: dance move=%s repeat=%d", move_name, repeat)
-
-        if not move_name or move_name == "random":
-            import random
-
-            move_name = random.choice(list(AVAILABLE_MOVES.keys()))
-
-        if move_name not in AVAILABLE_MOVES:
-            return {"error": f"Unknown dance move '{move_name}'. Available: {list(AVAILABLE_MOVES.keys())}"}
-
-        # Add dance moves to queue
-        movement_manager = deps.movement_manager
-        for _ in range(repeat):
-            dance_move = DanceQueueMove(move_name)
-            movement_manager.queue_move(dance_move)
-
-        return {"status": "queued", "move": move_name, "repeat": repeat}
-
-
-class StopDance(Tool):
-    """Stop the current dance move."""
-
-    name = "stop_dance"
-    description = "Stop the current dance move"
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "dummy": {
-                "type": "boolean",
-                "description": "dummy boolean, set it to true",
-            },
-        },
-        "required": ["dummy"],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Stop the current dance move."""
-        logger.info("Tool call: stop_dance")
-        movement_manager = deps.movement_manager
-        movement_manager.clear_move_queue()
-        return {"status": "stopped dance and cleared queue"}
-
-
-def get_available_emotions_and_descriptions() -> str:
-    """Get formatted list of available emotions with descriptions."""
-    if not EMOTION_AVAILABLE:
-        return "Emotions not available"
-
-    try:
-        emotion_names = RECORDED_MOVES.list_moves()
-        output = "Available emotions:\n"
-        for name in emotion_names:
-            description = RECORDED_MOVES.get(name).description
-            output += f" - {name}: {description}\n"
-        return output
-    except Exception as e:
-        return f"Error getting emotions: {e}"
-
-class PlayEmotion(Tool):
-    """Play a pre-recorded emotion."""
-
-    name = "play_emotion"
-    description = "Play a pre-recorded emotion"
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "emotion": {
-                "type": "string",
-                "description": f"""Name of the emotion to play.
-                                    Here is a list of the available emotions:
-                                    {get_available_emotions_and_descriptions()}
-                                    """,
-            },
-        },
-        "required": ["emotion"],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Play a pre-recorded emotion."""
-        if not EMOTION_AVAILABLE:
-            return {"error": "Emotion system not available"}
-
-        emotion_name = kwargs.get("emotion")
-        if not emotion_name:
-            return {"error": "Emotion name is required"}
-
-        logger.info("Tool call: play_emotion emotion=%s", emotion_name)
-
-        # Check if emotion exists
-        try:
-            emotion_names = RECORDED_MOVES.list_moves()
-            if emotion_name not in emotion_names:
-                return {"error": f"Unknown emotion '{emotion_name}'. Available: {emotion_names}"}
-
-            # Add emotion to queue
-            movement_manager = deps.movement_manager
-            emotion_move = EmotionQueueMove(emotion_name, RECORDED_MOVES)
-            movement_manager.queue_move(emotion_move)
-
-            return {"status": "queued", "emotion": emotion_name}
-
-        except Exception as e:
-            logger.exception("Failed to play emotion")
-            return {"error": f"Failed to play emotion: {e!s}"}
-
-
-class StopEmotion(Tool):
-    """Stop the current emotion."""
-
-    name = "stop_emotion"
-    description = "Stop the current emotion"
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "dummy": {
-                "type": "boolean",
-                "description": "dummy boolean, set it to true",
-            },
-        },
-        "required": ["dummy"],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Stop the current emotion."""
-        logger.info("Tool call: stop_emotion")
-        movement_manager = deps.movement_manager
-        movement_manager.clear_move_queue()
-        return {"status": "stopped emotion and cleared queue"}
-
-
-class DoNothing(Tool):
-    """Choose to do nothing - stay still and silent. Use when you want to be contemplative or just chill."""
-
-    name = "do_nothing"
-    description = "Choose to do nothing - stay still and silent. Use when you want to be contemplative or just chill."
-    parameters_schema = {
-        "type": "object",
-        "properties": {
-            "reason": {
-                "type": "string",
-                "description": "Optional reason for doing nothing (e.g., 'contemplating existence', 'saving energy', 'being mysterious')",
-            },
-        },
-        "required": [],
-    }
-
-    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
-        """Do nothing - stay still and silent."""
-        reason = kwargs.get("reason", "just chilling")
-        logger.info("Tool call: do_nothing reason=%s", reason)
-        return {"status": "doing nothing", "reason": reason}
-
-
-# Registry & specs (dynamic)
-
-# List of available tool classes
-ALL_TOOLS: Dict[str, Tool] = {cls.name: cls() for cls in get_concrete_subclasses(Tool)}  # type: ignore[type-abstract]
-ALL_TOOL_SPECS = [tool.spec() for tool in ALL_TOOLS.values()]
-
-
-# Dispatcher
-def _safe_load_obj(args_json: str) -> Dict[str, Any]:
-    try:
-        parsed_args = json.loads(args_json or "{}")
-        return parsed_args if isinstance(parsed_args, dict) else {}
-    except Exception:
-        logger.warning("bad args_json=%r", args_json)
-        return {}
-
-
-async def dispatch_tool_call(tool_name: str, args_json: str, deps: ToolDependencies) -> Dict[str, Any]:
-    """Dispatch a tool call by name with JSON args and dependencies."""
-    tool = ALL_TOOLS.get(tool_name)
-
-    if not tool:
-        return {"error": f"unknown tool: {tool_name}"}
-
-    args = _safe_load_obj(args_json)
-    try:
-        return await tool(deps, **args)
-    except Exception as e:
-        msg = f"{type(e).__name__}: {e}"
-        logger.exception("Tool error in %s: %s", tool_name, msg)
-        return {"error": msg}

src/reachy_mini_conversation_app/tools/__init__.py

@@ -0,0 +1,4 @@
+"""Tools library for Reachy Mini conversation app.
+
+Tools are now loaded dynamically based on the profile's tools.txt file.
+"""

src/reachy_mini_conversation_app/tools/camera.py

@@ -0,0 +1,67 @@
+import asyncio
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+class Camera(Tool):
+    """Take a picture with the camera and ask a question about it."""
+
+    name = "camera"
+    description = "Take a picture with the camera and ask a question about it."
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "question": {
+                "type": "string",
+                "description": "The question to ask about the picture",
+            },
+        },
+        "required": ["question"],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Take a picture with the camera and ask a question about it."""
+        image_query = (kwargs.get("question") or "").strip()
+        if not image_query:
+            logger.warning("camera: empty question")
+            return {"error": "question must be a non-empty string"}
+
+        logger.info("Tool call: camera question=%s", image_query[:120])
+
+        # Get frame from camera worker buffer (like main_works.py)
+        if deps.camera_worker is not None:
+            frame = deps.camera_worker.get_latest_frame()
+            if frame is None:
+                logger.error("No frame available from camera worker")
+                return {"error": "No frame available"}
+        else:
+            logger.error("Camera worker not available")
+            return {"error": "Camera worker not available"}
+
+        # Use vision manager for processing if available
+        if deps.vision_manager is not None:
+            vision_result = await asyncio.to_thread(
+                deps.vision_manager.processor.process_image, frame, image_query,
+            )
+            if isinstance(vision_result, dict) and "error" in vision_result:
+                return vision_result
+            return (
+                {"image_description": vision_result}
+                if isinstance(vision_result, str)
+                else {"error": "vision returned non-string"}
+            )
+        # Return base64 encoded image like main_works.py camera tool
+        import base64
+
+        import cv2
+
+        temp_path = "/tmp/camera_frame.jpg"
+        cv2.imwrite(temp_path, frame)
+        with open(temp_path, "rb") as f:
+            b64_encoded = base64.b64encode(f.read()).decode("utf-8")
+        return {"b64_im": b64_encoded}

src/reachy_mini_conversation_app/tools/core_tools.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+import abc
+import sys
+import json
+import inspect
+import logging
+import importlib
+from typing import Any, Dict, List
+from pathlib import Path
+from dataclasses import dataclass
+
+from reachy_mini import ReachyMini
+# Import config to ensure .env is loaded before reading REACHY_MINI_CUSTOM_PROFILE
+from reachy_mini_conversation_app.config import config  # noqa: F401
+
+
+logger = logging.getLogger(__name__)
+
+
+PROFILES_DIRECTORY = "reachy_mini_conversation_app.profiles"
+
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(asctime)s %(levelname)s %(name)s:%(lineno)d | %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+
+ALL_TOOLS: Dict[str, "Tool"] = {}
+ALL_TOOL_SPECS: List[Dict[str, Any]] = []
+_TOOLS_INITIALIZED = False
+
+
+
+def get_concrete_subclasses(base: type[Tool]) -> List[type[Tool]]:
+    """Recursively find all concrete (non-abstract) subclasses of a base class."""
+    result: List[type[Tool]] = []
+    for cls in base.__subclasses__():
+        if not inspect.isabstract(cls):
+            result.append(cls)
+        # recurse into subclasses
+        result.extend(get_concrete_subclasses(cls))
+    return result
+
+
+@dataclass
+class ToolDependencies:
+    """External dependencies injected into tools."""
+
+    reachy_mini: ReachyMini
+    movement_manager: Any  # MovementManager from moves.py
+    # Optional deps
+    camera_worker: Any | None = None  # CameraWorker for frame buffering
+    vision_manager: Any | None = None
+    head_wobbler: Any | None = None  # HeadWobbler for audio-reactive motion
+    motion_duration_s: float = 1.0
+
+
+# Tool base class
+class Tool(abc.ABC):
+    """Base abstraction for tools used in function-calling.
+
+    Each tool must define:
+      - name: str
+      - description: str
+      - parameters_schema: Dict[str, Any]  # JSON Schema
+    """
+
+    name: str
+    description: str
+    parameters_schema: Dict[str, Any]
+
+    def spec(self) -> Dict[str, Any]:
+        """Return the function spec for LLM consumption."""
+        return {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters_schema,
+        }
+
+    @abc.abstractmethod
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Async tool execution entrypoint."""
+        raise NotImplementedError
+
+
+# Registry & specs (dynamic)
+def _load_profile_tools() -> None:
+    """Load tools based on profile's tools.txt file."""
+    # Determine which profile to use
+    profile = config.REACHY_MINI_CUSTOM_PROFILE or "default"
+    logger.info(f"Loading tools for profile: {profile}")
+
+    # Build path to tools.txt
+    # Get the profile directory path
+    profile_module_path = Path(__file__).parent.parent / "profiles" / profile
+    tools_txt_path = profile_module_path / "tools.txt"
+
+    if not tools_txt_path.exists():
+        logger.error(f"✗ tools.txt not found at {tools_txt_path}")
+        sys.exit(1)
+
+    # Read and parse tools.txt
+    try:
+        with open(tools_txt_path, "r") as f:
+            lines = f.readlines()
+    except Exception as e:
+        logger.error(f"✗ Failed to read tools.txt: {e}")
+        sys.exit(1)
+
+    # Parse tool names (skip comments and blank lines)
+    tool_names = []
+    for line in lines:
+        line = line.strip()
+        # Skip blank lines and comments
+        if not line or line.startswith("#"):
+            continue
+        tool_names.append(line)
+
+    logger.info(f"Found {len(tool_names)} tools to load: {tool_names}")
+
+    # Import each tool
+    for tool_name in tool_names:
+        loaded = False
+        profile_error = None
+
+        # Try profile-local tool first
+        try:
+            profile_tool_module = f"{PROFILES_DIRECTORY}.{profile}.{tool_name}"
+            importlib.import_module(profile_tool_module)
+            logger.info(f"✓ Loaded profile-local tool: {tool_name}")
+            loaded = True
+        except ModuleNotFoundError as e:
+            # Check if it's the tool module itself that's missing (expected) or a dependency
+            if tool_name in str(e):
+                pass  # Tool not in profile directory, try shared tools
+            else:
+                # Missing import dependency within the tool file
+                profile_error = f"Missing dependency: {e}"
+                logger.error(f"❌ Failed to load profile-local tool '{tool_name}': {profile_error}")
+                logger.error(f"  Module path: {profile_tool_module}")
+        except ImportError as e:
+            profile_error = f"Import error: {e}"
+            logger.error(f"❌ Failed to load profile-local tool '{tool_name}': {profile_error}")
+            logger.error(f"  Module path: {profile_tool_module}")
+        except Exception as e:
+            profile_error = f"{type(e).__name__}: {e}"
+            logger.error(f"❌ Failed to load profile-local tool '{tool_name}': {profile_error}")
+            logger.error(f"  Module path: {profile_tool_module}")
+
+        # Try shared tools library if not found in profile
+        if not loaded:
+            try:
+                shared_tool_module = f"reachy_mini_conversation_app.tools.{tool_name}"
+                importlib.import_module(shared_tool_module)
+                logger.info(f"✓ Loaded shared tool: {tool_name}")
+                loaded = True
+            except ModuleNotFoundError:
+                if profile_error:
+                    # Already logged error from profile attempt
+                    logger.error(f"❌ Tool '{tool_name}' also not found in shared tools")
+                else:
+                    logger.warning(f"⚠️ Tool '{tool_name}' not found in profile or shared tools")
+            except ImportError as e:
+                logger.error(f"❌ Failed to load shared tool '{tool_name}': Import error: {e}")
+                logger.error(f"  Module path: {shared_tool_module}")
+            except Exception as e:
+                logger.error(f"❌ Failed to load shared tool '{tool_name}': {type(e).__name__}: {e}")
+                logger.error(f"  Module path: {shared_tool_module}")
+
+
+def _initialize_tools() -> None:
+    """Populate registry once, even if module is imported repeatedly."""
+    global ALL_TOOLS, ALL_TOOL_SPECS, _TOOLS_INITIALIZED
+
+    if _TOOLS_INITIALIZED:
+        logger.debug("Tools already initialized; skipping reinitialization.")
+        return
+
+    _load_profile_tools()
+
+    ALL_TOOLS = {cls.name: cls() for cls in get_concrete_subclasses(Tool)}  # type: ignore[type-abstract]
+    ALL_TOOL_SPECS = [tool.spec() for tool in ALL_TOOLS.values()]
+
+    for tool_name, tool in ALL_TOOLS.items():
+        logger.info(f"tool registered: {tool_name} - {tool.description}")
+
+    _TOOLS_INITIALIZED = True
+
+
+_initialize_tools()
+
+
+def get_tool_specs(exclusion_list: list[str] = []) -> list[Dict[str, Any]]:
+    """Get tool specs, optionally excluding some tools."""
+    return [spec for spec in ALL_TOOL_SPECS if spec.get("name") not in exclusion_list]
+
+
+# Dispatcher
+def _safe_load_obj(args_json: str) -> Dict[str, Any]:
+    try:
+        parsed_args = json.loads(args_json or "{}")
+        return parsed_args if isinstance(parsed_args, dict) else {}
+    except Exception:
+        logger.warning("bad args_json=%r", args_json)
+        return {}
+
+
+async def dispatch_tool_call(tool_name: str, args_json: str, deps: ToolDependencies) -> Dict[str, Any]:
+    """Dispatch a tool call by name with JSON args and dependencies."""
+    tool = ALL_TOOLS.get(tool_name)
+
+    if not tool:
+        return {"error": f"unknown tool: {tool_name}"}
+
+    args = _safe_load_obj(args_json)
+    try:
+        return await tool(deps, **args)
+    except Exception as e:
+        msg = f"{type(e).__name__}: {e}"
+        logger.exception("Tool error in %s: %s", tool_name, msg)
+        return {"error": msg}

src/reachy_mini_conversation_app/tools/dance.py

@@ -0,0 +1,87 @@
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+# Initialize dance library
+try:
+    from reachy_mini_dances_library.collection.dance import AVAILABLE_MOVES
+    from reachy_mini_conversation_app.dance_emotion_moves import DanceQueueMove
+
+    DANCE_AVAILABLE = True
+except ImportError as e:
+    logger.warning(f"Dance library not available: {e}")
+    AVAILABLE_MOVES = {}
+    DANCE_AVAILABLE = False
+
+
+class Dance(Tool):
+    """Play a named or random dance move once (or repeat). Non-blocking."""
+
+    name = "dance"
+    description = "Play a named or random dance move once (or repeat). Non-blocking."
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "move": {
+                "type": "string",
+                "description": """Name of the move; use 'random' or omit for random.
+                                    Here is a list of the available moves:
+                                        simple_nod: A simple, continuous up-and-down nodding motion.
+                                        head_tilt_roll: A continuous side-to-side head roll (ear to shoulder).
+                                        side_to_side_sway: A smooth, side-to-side sway of the entire head.
+                                        dizzy_spin: A circular 'dizzy' head motion combining roll and pitch.
+                                        stumble_and_recover: A simulated stumble and recovery with multiple axis movements. Good vibes
+                                        headbanger_combo: A strong head nod combined with a vertical bounce.
+                                        interwoven_spirals: A complex spiral motion using three axes at different frequencies.
+                                        sharp_side_tilt: A sharp, quick side-to-side tilt using a triangle waveform.
+                                        side_peekaboo: A multi-stage peekaboo performance, hiding and peeking to each side.
+                                        yeah_nod: An emphatic two-part yeah nod using transient motions.
+                                        uh_huh_tilt: A combined roll-and-pitch uh-huh gesture of agreement.
+                                        neck_recoil: A quick, transient backward recoil of the neck.
+                                        chin_lead: A forward motion led by the chin, combining translation and pitch.
+                                        groovy_sway_and_roll: A side-to-side sway combined with a corresponding roll for a groovy effect.
+                                        chicken_peck: A sharp, forward, chicken-like pecking motion.
+                                        side_glance_flick: A quick glance to the side that holds, then returns.
+                                        polyrhythm_combo: A 3-beat sway and a 2-beat nod create a polyrhythmic feel.
+                                        grid_snap: A robotic, grid-snapping motion using square waveforms.
+                                        pendulum_swing: A simple, smooth pendulum-like swing using a roll motion.
+                                        jackson_square: Traces a rectangle via a 5-point path, with sharp twitches on arrival at each checkpoint.
+                """,
+            },
+            "repeat": {
+                "type": "integer",
+                "description": "How many times to repeat the move (default 1).",
+            },
+        },
+        "required": [],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Play a named or random dance move once (or repeat). Non-blocking."""
+        if not DANCE_AVAILABLE:
+            return {"error": "Dance system not available"}
+
+        move_name = kwargs.get("move")
+        repeat = int(kwargs.get("repeat", 1))
+
+        logger.info("Tool call: dance move=%s repeat=%d", move_name, repeat)
+
+        if not move_name or move_name == "random":
+            import random
+
+            move_name = random.choice(list(AVAILABLE_MOVES.keys()))
+
+        if move_name not in AVAILABLE_MOVES:
+            return {"error": f"Unknown dance move '{move_name}'. Available: {list(AVAILABLE_MOVES.keys())}"}
+
+        # Add dance moves to queue
+        movement_manager = deps.movement_manager
+        for _ in range(repeat):
+            dance_move = DanceQueueMove(move_name)
+            movement_manager.queue_move(dance_move)
+
+        return {"status": "queued", "move": move_name, "repeat": repeat}

src/reachy_mini_conversation_app/tools/do_nothing.py

@@ -0,0 +1,30 @@
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+class DoNothing(Tool):
+    """Choose to do nothing - stay still and silent. Use when you want to be contemplative or just chill."""
+
+    name = "do_nothing"
+    description = "Choose to do nothing - stay still and silent. Use when you want to be contemplative or just chill."
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "reason": {
+                "type": "string",
+                "description": "Optional reason for doing nothing (e.g., 'contemplating existence', 'saving energy', 'being mysterious')",
+            },
+        },
+        "required": [],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Do nothing - stay still and silent."""
+        reason = kwargs.get("reason", "just chilling")
+        logger.info("Tool call: do_nothing reason=%s", reason)
+        return {"status": "doing nothing", "reason": reason}

src/reachy_mini_conversation_app/tools/head_tracking.py

@@ -0,0 +1,31 @@
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+class HeadTracking(Tool):
+    """Toggle head tracking state."""
+
+    name = "head_tracking"
+    description = "Toggle head tracking state."
+    parameters_schema = {
+        "type": "object",
+        "properties": {"start": {"type": "boolean"}},
+        "required": ["start"],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Enable or disable head tracking."""
+        enable = bool(kwargs.get("start"))
+
+        # Update camera worker head tracking state
+        if deps.camera_worker is not None:
+            deps.camera_worker.set_head_tracking_enabled(enable)
+
+        status = "started" if enable else "stopped"
+        logger.info("Tool call: head_tracking %s", status)
+        return {"status": f"head tracking {status}"}

src/reachy_mini_conversation_app/tools/move_head.py

@@ -0,0 +1,79 @@
+import logging
+from typing import Any, Dict, Tuple, Literal
+
+from reachy_mini.utils import create_head_pose
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+from reachy_mini_conversation_app.dance_emotion_moves import GotoQueueMove
+
+
+logger = logging.getLogger(__name__)
+
+Direction = Literal["left", "right", "up", "down", "front"]
+
+
+class MoveHead(Tool):
+    """Move head in a given direction."""
+
+    name = "move_head"
+    description = "Move your head in a given direction: left, right, up, down or front."
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "direction": {
+                "type": "string",
+                "enum": ["left", "right", "up", "down", "front"],
+            },
+        },
+        "required": ["direction"],
+    }
+
+    # mapping: direction -> args for create_head_pose
+    DELTAS: Dict[str, Tuple[int, int, int, int, int, int]] = {
+        "left": (0, 0, 0, 0, 0, 40),
+        "right": (0, 0, 0, 0, 0, -40),
+        "up": (0, 0, 0, 0, -30, 0),
+        "down": (0, 0, 0, 0, 30, 0),
+        "front": (0, 0, 0, 0, 0, 0),
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Move head in a given direction."""
+        direction_raw = kwargs.get("direction")
+        if not isinstance(direction_raw, str):
+            return {"error": "direction must be a string"}
+        direction: Direction = direction_raw  # type: ignore[assignment]
+        logger.info("Tool call: move_head direction=%s", direction)
+
+        deltas = self.DELTAS.get(direction, self.DELTAS["front"])
+        target = create_head_pose(*deltas, degrees=True)
+
+        # Use new movement manager
+        try:
+            movement_manager = deps.movement_manager
+
+            # Get current state for interpolation
+            current_head_pose = deps.reachy_mini.get_current_head_pose()
+            _, current_antennas = deps.reachy_mini.get_current_joint_positions()
+
+            # Create goto move
+            goto_move = GotoQueueMove(
+                target_head_pose=target,
+                start_head_pose=current_head_pose,
+                target_antennas=(0, 0),  # Reset antennas to default
+                start_antennas=(
+                    current_antennas[0],
+                    current_antennas[1],
+                ),  # Skip body_yaw
+                target_body_yaw=0,  # Reset body yaw
+                start_body_yaw=current_antennas[0],  # body_yaw is first in joint positions
+                duration=deps.motion_duration_s,
+            )
+
+            movement_manager.queue_move(goto_move)
+            movement_manager.set_moving_state(deps.motion_duration_s)
+
+            return {"status": f"looking {direction}"}
+
+        except Exception as e:
+            logger.error("move_head failed")
+            return {"error": f"move_head failed: {type(e).__name__}: {e}"}

src/reachy_mini_conversation_app/tools/play_emotion.py

@@ -0,0 +1,84 @@
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+# Initialize emotion library
+try:
+    from reachy_mini.motion.recorded_move import RecordedMoves
+    from reachy_mini_conversation_app.dance_emotion_moves import EmotionQueueMove
+
+    # Note: huggingface_hub automatically reads HF_TOKEN from environment variables
+    RECORDED_MOVES = RecordedMoves("pollen-robotics/reachy-mini-emotions-library")
+    EMOTION_AVAILABLE = True
+except ImportError as e:
+    logger.warning(f"Emotion library not available: {e}")
+    RECORDED_MOVES = None
+    EMOTION_AVAILABLE = False
+
+
+def get_available_emotions_and_descriptions() -> str:
+    """Get formatted list of available emotions with descriptions."""
+    if not EMOTION_AVAILABLE:
+        return "Emotions not available"
+
+    try:
+        emotion_names = RECORDED_MOVES.list_moves()
+        output = "Available emotions:\n"
+        for name in emotion_names:
+            description = RECORDED_MOVES.get(name).description
+            output += f" - {name}: {description}\n"
+        return output
+    except Exception as e:
+        return f"Error getting emotions: {e}"
+
+
+class PlayEmotion(Tool):
+    """Play a pre-recorded emotion."""
+
+    name = "play_emotion"
+    description = "Play a pre-recorded emotion"
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "emotion": {
+                "type": "string",
+                "description": f"""Name of the emotion to play.
+                                    Here is a list of the available emotions:
+                                    {get_available_emotions_and_descriptions()}
+                                    """,
+            },
+        },
+        "required": ["emotion"],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Play a pre-recorded emotion."""
+        if not EMOTION_AVAILABLE:
+            return {"error": "Emotion system not available"}
+
+        emotion_name = kwargs.get("emotion")
+        if not emotion_name:
+            return {"error": "Emotion name is required"}
+
+        logger.info("Tool call: play_emotion emotion=%s", emotion_name)
+
+        # Check if emotion exists
+        try:
+            emotion_names = RECORDED_MOVES.list_moves()
+            if emotion_name not in emotion_names:
+                return {"error": f"Unknown emotion '{emotion_name}'. Available: {emotion_names}"}
+
+            # Add emotion to queue
+            movement_manager = deps.movement_manager
+            emotion_move = EmotionQueueMove(emotion_name, RECORDED_MOVES)
+            movement_manager.queue_move(emotion_move)
+
+            return {"status": "queued", "emotion": emotion_name}
+
+        except Exception as e:
+            logger.exception("Failed to play emotion")
+            return {"error": f"Failed to play emotion: {e!s}"}

src/reachy_mini_conversation_app/tools/stop_dance.py

@@ -0,0 +1,31 @@
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+class StopDance(Tool):
+    """Stop the current dance move."""
+
+    name = "stop_dance"
+    description = "Stop the current dance move"
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "dummy": {
+                "type": "boolean",
+                "description": "dummy boolean, set it to true",
+            },
+        },
+        "required": ["dummy"],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Stop the current dance move."""
+        logger.info("Tool call: stop_dance")
+        movement_manager = deps.movement_manager
+        movement_manager.clear_move_queue()
+        return {"status": "stopped dance and cleared queue"}

src/reachy_mini_conversation_app/tools/stop_emotion.py

@@ -0,0 +1,31 @@
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+class StopEmotion(Tool):
+    """Stop the current emotion."""
+
+    name = "stop_emotion"
+    description = "Stop the current emotion"
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "dummy": {
+                "type": "boolean",
+                "description": "dummy boolean, set it to true",
+            },
+        },
+        "required": ["dummy"],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Stop the current emotion."""
+        logger.info("Tool call: stop_emotion")
+        movement_manager = deps.movement_manager
+        movement_manager.clear_move_queue()
+        return {"status": "stopped emotion and cleared queue"}

tests/test_openai_realtime.py

@@ -7,8 +7,8 @@ from unittest.mock import MagicMock
 import pytest
 
 import reachy_mini_conversation_app.openai_realtime as rt_mod
-from reachy_mini_conversation_app.tools import ToolDependencies
 from reachy_mini_conversation_app.openai_realtime import OpenaiRealtimeHandler
+from reachy_mini_conversation_app.tools.core_tools import ToolDependencies
 
 
 def _build_handler(loop: asyncio.AbstractEventLoop) -> OpenaiRealtimeHandler:

uv.lock

@@ -379,6 +379,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/92/15/5e713098a085f970ccf88550194d277d244464d7b3a7365ad92acb4b6dc1/av-16.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:6368d4ff153d75469d2a3217bc403630dc870a72fe0a014d9135de550d731a86", size = 32460624, upload-time = "2025-10-13T12:28:48.767Z" },
 ]
 
+[[package]]
+name = "backports-asyncio-runner"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8e/ff/70dca7d7cb1cbc0edb2c6cc0c38b65cba36cccc491eca64cabd5fe7f8670/backports_asyncio_runner-1.2.0.tar.gz", hash = "sha256:a5aa7b2b7d8f8bfcaa2b57313f70792df84e32a2a746f585213373f900b42162", size = 69893, upload-time = "2025-07-02T02:27:15.685Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/59/76ab57e3fe74484f48a53f8e337171b4a2349e506eabe136d7e01d059086/backports_asyncio_runner-1.2.0-py3-none-any.whl", hash = "sha256:0da0a936a8aeb554eccb426dc55af3ba63bcdc69fa1a600b5bb305413a4477b5", size = 12313, upload-time = "2025-07-02T02:27:14.263Z" },
+]
+
 [[package]]
 name = "brotli"
 version = "1.1.0"
@@ -540,6 +549,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
 ]
 
+[[package]]
+name = "cfgv"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/11/74/539e56497d9bd1d484fd863dd69cbbfa653cd2aa27abfe35653494d85e94/cfgv-3.4.0.tar.gz", hash = "sha256:e52591d4c5f5dead8e0f673fb16db7949d2cfb3f7da4582893288f0ded8fe560", size = 7114, upload-time = "2023-08-12T20:38:17.776Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c5/55/51844dd50c4fc7a33b653bfaba4c2456f06955289ca770a5dbd5fd267374/cfgv-3.4.0-py2.py3-none-any.whl", hash = "sha256:b7265b1f29fd3316bfcd2b330d63d024f2bfd8bcb8b0272f8e19a504856c48f9", size = 7249, upload-time = "2023-08-12T20:38:16.269Z" },
+]
+
 [[package]]
 name = "charset-normalizer"
 version = "3.4.4"
@@ -917,6 +935,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/07/6c/aa3f2f849e01cb6a001cd8554a88d4c77c5c1a31c95bdf1cf9301e6d9ef4/defusedxml-0.7.1-py2.py3-none-any.whl", hash = "sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61", size = 25604, upload-time = "2021-03-08T10:59:24.45Z" },
 ]
 
+[[package]]
+name = "distlib"
+version = "0.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/96/8e/709914eb2b5749865801041647dc7f4e6d00b549cfe88b65ca192995f07c/distlib-0.4.0.tar.gz", hash = "sha256:feec40075be03a04501a973d81f633735b4b69f98b05450592310c0f401a4e0d", size = 614605, upload-time = "2025-07-17T16:52:00.465Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/33/6b/e0547afaf41bf2c42e52430072fa5658766e3d65bd4b03a563d1b6336f57/distlib-0.4.0-py2.py3-none-any.whl", hash = "sha256:9659f7d87e46584a30b5780e43ac7a2143098441670ff0a49d5f9034c54a6c16", size = 469047, upload-time = "2025-07-17T16:51:58.613Z" },
+]
+
 [[package]]
 name = "distro"
 version = "1.9.0"
@@ -962,7 +989,7 @@ name = "exceptiongroup"
 version = "1.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.12'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" }
 wheels = [
@@ -1431,6 +1458,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/39/7b/bb06b061991107cd8783f300adff3e7b7f284e330fd82f507f2a1417b11d/huggingface_hub-0.34.4-py3-none-any.whl", hash = "sha256:9b365d781739c93ff90c359844221beef048403f1bc1f1c123c191257c3c890a", size = 561452, upload-time = "2025-08-08T09:14:50.159Z" },
 ]
 
+[[package]]
+name = "identify"
+version = "2.6.15"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ff/e7/685de97986c916a6d93b3876139e00eef26ad5bbbd61925d670ae8013449/identify-2.6.15.tar.gz", hash = "sha256:e4f4864b96c6557ef2a1e1c951771838f4edc9df3a72ec7118b338801b11c7bf", size = 99311, upload-time = "2025-10-02T17:43:40.631Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0f/1c/e5fd8f973d4f375adb21565739498e2e9a1e54c858a97b9a8ccfdc81da9b/identify-2.6.15-py2.py3-none-any.whl", hash = "sha256:1181ef7608e00704db228516541eb83a88a9f94433a8c80bb9b5bd54b1d81757", size = 99183, upload-time = "2025-10-02T17:43:39.137Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.11"
@@ -2428,6 +2464,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/eb/8d/776adee7bbf76365fdd7f2552710282c79a4ead5d2a46408c9043a2b70ba/networkx-3.5-py3-none-any.whl", hash = "sha256:0030d386a9a06dee3565298b4a734b68589749a544acbb6c412dc9e2489ec6ec", size = 2034406, upload-time = "2025-05-29T11:35:04.961Z" },
 ]
 
+[[package]]
+name = "nodeenv"
+version = "1.9.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/16/fc88b08840de0e0a72a2f9d8c6bae36be573e475a6326ae854bcc549fc45/nodeenv-1.9.1.tar.gz", hash = "sha256:6ec12890a2dab7946721edbfbcd91f3319c6ccc9aec47be7c7e6b7011ee6645f", size = 47437, upload-time = "2024-06-04T18:44:11.171Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d2/1d/1b658dbd2b9fa9c4c9f32accbfc0205d532c8c6194dc0f2a4c0428e7128a/nodeenv-1.9.1-py2.py3-none-any.whl", hash = "sha256:ba11c9782d29c27c70ffbdda2d7415098754709be8a7056d79a737cd901155c9", size = 22314, upload-time = "2024-06-04T18:44:08.352Z" },
+]
+
 [[package]]
 name = "num2words"
 version = "0.5.14"
@@ -2571,7 +2616,7 @@ name = "nvidia-cudnn-cu12"
 version = "9.10.2.21"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ba/51/e123d997aa098c61d029f76663dedbfb9bc8dcf8c60cbd6adbe42f76d049/nvidia_cudnn_cu12-9.10.2.21-py3-none-manylinux_2_27_x86_64.whl", hash = "sha256:949452be657fa16687d0930933f032835951ef0892b37d2d53824d1a84dc97a8", size = 706758467, upload-time = "2025-06-06T21:54:08.597Z" },
@@ -2582,7 +2627,7 @@ name = "nvidia-cufft-cu12"
 version = "11.3.3.83"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/1f/13/ee4e00f30e676b66ae65b4f08cb5bcbb8392c03f54f2d5413ea99a5d1c80/nvidia_cufft_cu12-11.3.3.83-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d2dd21ec0b88cf61b62e6b43564355e5222e4a3fb394cac0db101f2dd0d4f74", size = 193118695, upload-time = "2025-03-07T01:45:27.821Z" },
@@ -2609,9 +2654,9 @@ name = "nvidia-cusolver-cu12"
 version = "11.7.3.90"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
-    { name = "nvidia-cusparse-cu12" },
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "sys_platform != 'win32'" },
+    { name = "nvidia-cusparse-cu12", marker = "sys_platform != 'win32'" },
+    { name = "nvidia-nvjitlink-cu12", marker = "sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/85/48/9a13d2975803e8cf2777d5ed57b87a0b6ca2cc795f9a4f59796a910bfb80/nvidia_cusolver_cu12-11.7.3.90-py3-none-manylinux_2_27_x86_64.whl", hash = "sha256:4376c11ad263152bd50ea295c05370360776f8c3427b30991df774f9fb26c450", size = 267506905, upload-time = "2025-03-07T01:47:16.273Z" },
@@ -2622,7 +2667,7 @@ name = "nvidia-cusparse-cu12"
 version = "12.5.8.93"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/c2/f5/e1854cb2f2bcd4280c44736c93550cc300ff4b8c95ebe370d0aa7d2b473d/nvidia_cusparse_cu12-12.5.8.93-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1ec05d76bbbd8b61b06a80e1eaf8cf4959c3d4ce8e711b65ebd0443bb0ebb13b", size = 288216466, upload-time = "2025-03-07T01:48:13.779Z" },
@@ -3046,6 +3091,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a8/87/77cc11c7a9ea9fd05503def69e3d18605852cd0d4b0d3b8f15bbeb3ef1d1/pooch-1.8.2-py3-none-any.whl", hash = "sha256:3529a57096f7198778a5ceefd5ac3ef0e4d06a6ddaf9fc2d609b806f25302c47", size = 64574, upload-time = "2024-06-06T16:53:44.343Z" },
 ]
 
+[[package]]
+name = "pre-commit"
+version = "4.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cfgv" },
+    { name = "identify" },
+    { name = "nodeenv" },
+    { name = "pyyaml" },
+    { name = "virtualenv" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a6/49/7845c2d7bf6474efd8e27905b51b11e6ce411708c91e829b93f324de9929/pre_commit-4.4.0.tar.gz", hash = "sha256:f0233ebab440e9f17cabbb558706eb173d19ace965c68cdce2c081042b4fab15", size = 197501, upload-time = "2025-11-08T21:12:11.607Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/27/11/574fe7d13acf30bfd0a8dd7fa1647040f2b8064f13f43e8c963b1e65093b/pre_commit-4.4.0-py2.py3-none-any.whl", hash = "sha256:b35ea52957cbf83dcc5d8ee636cbead8624e3a15fbfa61a370e42158ac8a5813", size = 226049, upload-time = "2025-11-08T21:12:10.228Z" },
+]
+
 [[package]]
 name = "propcache"
 version = "0.4.1"
@@ -3514,6 +3575,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a8/a4/20da314d277121d6534b3a980b29035dcd51e6744bd79075a6ce8fa4eb8d/pytest-8.4.2-py3-none-any.whl", hash = "sha256:872f880de3fc3a5bdc88a11b39c9710c3497a547cfa9320bc3c5e62fbf272e79", size = 365750, upload-time = "2025-09-04T14:34:20.226Z" },
 ]
 
+[[package]]
+name = "pytest-asyncio"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-asyncio-runner", marker = "python_full_version < '3.11'" },
+    { name = "pytest" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/2c/8af215c0f776415f3590cac4f9086ccefd6fd463befeae41cd4d3f193e5a/pytest_asyncio-1.3.0.tar.gz", hash = "sha256:d7f52f36d231b80ee124cd216ffb19369aa168fc10095013c6b014a34d3ee9e5", size = 50087, upload-time = "2025-11-10T16:07:47.256Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl", hash = "sha256:611e26147c7f77640e6d0a92a38ed17c3e9848063698d5c93d5aa7aa11cebff5", size = 15075, upload-time = "2025-11-10T16:07:45.537Z" },
+]
+
 [[package]]
 name = "python-dateutil"
 version = "2.9.0.post0"
@@ -3688,8 +3763,11 @@ yolo-vision = [
 [package.dev-dependencies]
 dev = [
     { name = "mypy" },
+    { name = "pre-commit" },
     { name = "pytest" },
+    { name = "pytest-asyncio" },
     { name = "ruff" },
+    { name = "types-requests" },
 ]
 
 [package.metadata]
@@ -3698,20 +3776,23 @@ requires-dist = [
     { name = "fastrtc", specifier = ">=0.0.33" },
     { name = "gradio", specifier = ">=5.49.0" },
     { name = "huggingface-hub", specifier = ">=0.34.4" },
+    { name = "mediapipe", marker = "extra == 'all-vision'", specifier = ">=0.10.14" },
     { name = "mediapipe", marker = "extra == 'mediapipe-vision'", specifier = ">=0.10.14" },
+    { name = "num2words", marker = "extra == 'all-vision'" },
     { name = "num2words", marker = "extra == 'local-vision'" },
     { name = "openai", specifier = ">=2.1" },
     { name = "opencv-python", specifier = ">=4.12.0.88" },
     { name = "python-dotenv" },
     { name = "reachy-mini", specifier = ">=1.0.0rc4" },
-    { name = "reachy-mini-conversation-app", extras = ["local-vision"], marker = "extra == 'all-vision'" },
-    { name = "reachy-mini-conversation-app", extras = ["mediapipe-vision"], marker = "extra == 'all-vision'" },
-    { name = "reachy-mini-conversation-app", extras = ["yolo-vision"], marker = "extra == 'all-vision'" },
     { name = "reachy-mini-dances-library" },
     { name = "reachy-mini-toolbox" },
+    { name = "supervision", marker = "extra == 'all-vision'" },
     { name = "supervision", marker = "extra == 'yolo-vision'" },
+    { name = "torch", marker = "extra == 'all-vision'" },
     { name = "torch", marker = "extra == 'local-vision'" },
+    { name = "transformers", marker = "extra == 'all-vision'" },
     { name = "transformers", marker = "extra == 'local-vision'" },
+    { name = "ultralytics", marker = "extra == 'all-vision'" },
     { name = "ultralytics", marker = "extra == 'yolo-vision'" },
 ]
 provides-extras = ["local-vision", "yolo-vision", "mediapipe-vision", "all-vision"]
@@ -3719,8 +3800,11 @@ provides-extras = ["local-vision", "yolo-vision", "mediapipe-vision", "all-visio
 [package.metadata.requires-dev]
 dev = [
     { name = "mypy", specifier = "==1.18.2" },
+    { name = "pre-commit" },
     { name = "pytest" },
+    { name = "pytest-asyncio" },
     { name = "ruff", specifier = "==0.12.0" },
+    { name = "types-requests" },
 ]
 
 [[package]]
@@ -4638,6 +4722,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/78/64/7713ffe4b5983314e9d436a90d5bd4f63b6054e2aca783a3cfc44cb95bbf/typer-0.20.0-py3-none-any.whl", hash = "sha256:5b463df6793ec1dca6213a3cf4c0f03bc6e322ac5e16e13ddd622a889489784a", size = 47028, upload-time = "2025-10-20T17:03:47.617Z" },
 ]
 
+[[package]]
+name = "types-requests"
+version = "2.32.4.20250913"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/36/27/489922f4505975b11de2b5ad07b4fe1dca0bca9be81a703f26c5f3acfce5/types_requests-2.32.4.20250913.tar.gz", hash = "sha256:abd6d4f9ce3a9383f269775a9835a4c24e5cd6b9f647d64f88aa4613c33def5d", size = 23113, upload-time = "2025-09-13T02:40:02.309Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/20/9a227ea57c1285986c4cf78400d0a91615d25b24e257fd9e2969606bdfae/types_requests-2.32.4.20250913-py3-none-any.whl", hash = "sha256:78c9c1fffebbe0fa487a418e0fa5252017e9c60d1a2da394077f1780f655d7e1", size = 20658, upload-time = "2025-09-13T02:40:01.115Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.15.0"
@@ -4782,6 +4878,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e4/16/c1fd27e9549f3c4baf1dc9c20c456cd2f822dbf8de9f463824b0c0357e06/uvloop-0.22.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6cde23eeda1a25c75b2e07d39970f3374105d5eafbaab2a4482be82f272d5a5e", size = 4296730, upload-time = "2025-10-16T22:17:00.744Z" },
 ]
 
+[[package]]
+name = "virtualenv"
+version = "20.35.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "distlib" },
+    { name = "filelock" },
+    { name = "platformdirs" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/20/28/e6f1a6f655d620846bd9df527390ecc26b3805a0c5989048c210e22c5ca9/virtualenv-20.35.4.tar.gz", hash = "sha256:643d3914d73d3eeb0c552cbb12d7e82adf0e504dbf86a3182f8771a153a1971c", size = 6028799, upload-time = "2025-10-29T06:57:40.511Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/79/0c/c05523fa3181fdf0c9c52a6ba91a23fbf3246cc095f26f6516f9c60e6771/virtualenv-20.35.4-py3-none-any.whl", hash = "sha256:c21c9cede36c9753eeade68ba7d523529f228a403463376cf821eaae2b650f1b", size = 6005095, upload-time = "2025-10-29T06:57:37.598Z" },
+]
+
 [[package]]
 name = "watchfiles"
 version = "1.1.1"