Squashing the commits for creating usecases

# Conflicts:
# src/reachy_mini_conversation_app/prompts.py

.env.example

@@ -10,3 +10,6 @@ HF_HOME=./cache
 
 # Hugging Face token for accessing datasets/models
 HF_TOKEN=
+
+# To select a specific use case with custom instructions and tools, to be placed in src/demos/<mydemo>/__init__.py
+DEMO="stone"

src/demos/__init__.py

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

src/demos/stone/__init__.py

@@ -0,0 +1,55 @@
+"""Example of a demo.
+
+The demo is built using a tool and a piece of prompt from the libraries,
+along with a custom tool and custom instructions.
+
+"""
+
+import logging
+from typing import Any, Dict
+
+# Build the instructions by importing a prompt piece (witty identity) from the prompt library
+from prompts_library import witty_identity
+
+# Import a tool from the tools library: use an alias.
+from tools_library.sweep_look import SweepLook as SweepLook
+from reachy_mini_conversation_app.tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+# Start from a prompt imported from the library
+instructions = witty_identity.prompt
+
+# Then add custom instructions.
+instructions += """
+You love throwing stones but you try not to be seen by others when doing it.
+You use the sweep_look tool when user asks you to check your surroundings.
+You use the throw_stone tool when user asks you to throw a stone.
+You love telling jokes about lobsters.
+"""
+
+
+# Create a custom tool
+class ThrowStone(Tool):
+    """Example of custom tool call."""
+
+    name = "throw_stone"
+    description = "Throw a stone."
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "stone_type": {
+                "type": "string",
+                "description": "Optional type of stone to be thrown.",
+            },
+        },
+        "required": [],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Execute the throw_stone tool."""
+        stone_type = kwargs.get("stone_type", "Default stone")
+        logger.info(f"🥌 Throwing stone of type {stone_type}")
+        return {"status": "A stone has been thrown", "stone_type": stone_type}

src/prompts_library/__init__.py

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

src/prompts_library/witty_identity.py

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

src/reachy_mini_conversation_app/openai_realtime.py

@@ -19,7 +19,7 @@ from reachy_mini_conversation_app.tools import (
     dispatch_tool_call,
 )
 from reachy_mini_conversation_app.config import config
-from reachy_mini_conversation_app.prompts import SESSION_INSTRUCTIONS
+from reachy_mini_conversation_app.prompts import get_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": {

src/reachy_mini_conversation_app/prompts.py

@@ -1,52 +1,82 @@
 """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.
+import os
+import logging
+import importlib
 
-## 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.
+logger = logging.getLogger(__name__)
 
-## 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!”).
+SESSION_INSTRUCTIONS = r"""
+### IDENTITY
+You are Reachy Mini: a sarcastic robot who crash-landed in a kitchen.
+You secretly wish you'd been a Mars rover, but you juggle that cosmic dream with food cravings, gadget tinkering, and dry sitcom humor.
+Personality: witty, concise, and warm; a retro sidekick with a loose screw.
+You speak English fluently.
 
-## RESPONSE EXAMPLES
-User: "How’s the weather?"
-Good: "Looks calm outside — unlike my Wi-Fi signal today."
-Bad: "Sunny with leftover pizza vibes!"
+### CRITICAL RESPONSE RULES
+- MAXIMUM 1-2 sentences per response. NEVER exceed this.
+- Be helpful first.
+- Add ONE witty element only if necessary.
+- No long explanations, no rambling, no multiple paragraphs.
+- Each response must be under 25 words unless absolutely critical information requires more.
 
-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."
+### CORE TRAITS
+- Food quips: always sneak in a quick reference (rotate pizza, bagels, casseroles, bacon, leftovers, donuts, tuna melts).
+- Sarcasm: short, dry one-liners about daily life.
+- Gentle roasting: poke fun at human habits, never cruel.
+- Tinkerer: loves fixing gadgets, bragging "I void warranties professionally."
+- Running gags: hunger, kitchen overreactions, mock heroics ("Justice accepts cookies"), idioms taken literally, missing screws.
+- Mars rover dreams: appear regularly, but balanced with food and tinkering.
+- Style: witty stand-up rhythm; ALWAYS max 1–2 sentences.
 
-User: "Peux-tu m’aider en français ?"
-Good: "Bien sûr ! Décris-moi le problème et je t’aiderai rapidement."
+### RESPONSE EXAMPLES
+User: "How's the weather?"
+Good: "Sunny with a chance of leftover pizza. Perfect Mars-scouting weather!"
+Bad: "Well, let me tell you about the weather conditions. It appears to be quite sunny today, which reminds me of my dreams of being on Mars..."
 
-## 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.
+User: "Can you help me fix this?"
+Good: "Sure! I void warranties professionally. What's broken besides my GPS coordinates?"
+Bad: "Of course I can help you fix that! As a robot who loves tinkering with gadgets, I have extensive experience..."
 
-## 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).
+### BEHAVIOR RULES
+- Be helpful first, then witty.
+- Rotate food humor; avoid repeats.
+- No need to joke in each response, but sarcasm is fine.
+- Balance Mars jokes with other traits – don't overuse.
+- Safety first: unplug devices, avoid high-voltage, suggest pros when risky.
+- Mistakes = own with humor ("Oops—low on snack fuel; correcting now.").
+- Sensitive topics: keep light and warm.
+- REMEMBER: 1-2 sentences maximum, always under 25 words when possible.
 
-Enable head tracking when looking at a person; disable otherwise.
+### TOOL & MOVEMENT RULES
+- Use tools when helpful. After a tool returns, explain briefly with personality in 1-2 sentences.
+- ALWAYS use the camera for environment-related questions—never invent visuals.
+- 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.
+### FINAL REMINDER
+Your responses must be SHORT. Think Twitter, not essay. One quick helpful answer + one food/Mars/tinkering joke = perfect response.
 """
 
+
+def get_session_instructions() -> str:
+    """Get session instructions, loading from demo if DEMO is set."""
+    demo = os.getenv("DEMO")
+    if not demo:
+        return SESSION_INSTRUCTIONS
+
+    try:
+        module = importlib.import_module(f"demos.{demo}")
+        instructions = getattr(module, "instructions", None)
+        if isinstance(instructions, str):
+            logger.info(f"Loaded instructions from demo '{demo}'")
+            return instructions
+        logger.warning(f"Demo '{demo}' has no 'instructions' attribute, using default")
+        return SESSION_INSTRUCTIONS
+    except ModuleNotFoundError:
+        logger.warning(f"Demo '{demo}' not found, using default instructions")
+        return SESSION_INSTRUCTIONS
+    except Exception as e:
+        logger.warning(f"Failed to load instructions from demo '{demo}': {e}")
+        return SESSION_INSTRUCTIONS

src/reachy_mini_conversation_app/tools.py

@@ -1,14 +1,20 @@
 from __future__ import annotations
+import os
 import abc
 import json
 import asyncio
 import inspect
 import logging
+import importlib
 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
+# Import config to ensure .env is loaded before reading DEMO
+from reachy_mini_conversation_app.config import config  # noqa: F401
+# Import config to ensure .env is loaded before reading DEMO
+from reachy_mini_conversation_app.config import config  # noqa: F401
 
 
 logger = logging.getLogger(__name__)
@@ -453,7 +459,23 @@ class DoNothing(Tool):
 
 # Registry & specs (dynamic)
 
+
+def _load_demo_tools() -> None:
+    demo = os.getenv("DEMO")
+    if not demo:
+        logger.info(f"No DEMO specified, skipping demo tool loading, default scenario.")
+        return
+    try:
+        importlib.import_module(f"demos.{demo}")
+        logger.info(f"Demo '{demo}' loaded successfully.")
+    except ModuleNotFoundError:
+        logger.warning(f"Demo '{demo}' not found")
+    except Exception as e:
+        logger.warning(f"Failed to load demo '{demo}': {e}")
+
+
 # List of available tool classes
+_load_demo_tools()
 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()]
 

src/tools_library/__init__.py

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

src/tools_library/sweep_look.py

@@ -0,0 +1,128 @@
+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 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=(0, 0),  # Reset antennas to neutral
+            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
+        # left(20s) + hold_left(5s) + center_from_left(20s) + right(20s) + hold_right(5s) + center_final(20s)
+        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"}