Initial commit

.env.example

@@ -0,0 +1,24 @@
+OPENAI_API_KEY=
+MODEL_NAME="gpt-realtime"
+
+# Local vision model (only used with --local-vision CLI flag)
+# By default, vision is handled by gpt-realtime when the camera tool is used
+LOCAL_VISION_MODEL=HuggingFaceTB/SmolVLM2-2.2B-Instruct
+
+# Cache for local VLM (only used with --local-vision CLI flag)
+HF_HOME=./cache
+
+# Hugging Face token for accessing datasets/models
+HF_TOKEN=
+
+# Profile selection (defaults to "default" when unset)
+REACHY_MINI_CUSTOM_PROFILE="example"
+
+# Optional external profile/tool directories
+# REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY=external_content/external_profiles
+# REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY=external_content/external_tools
+
+# Optional: discover and auto-load all tools found in REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY,
+# even if they are not listed in the selected profile's tools.txt.
+# This is convenient for downloaded tools used with built-in/default profiles.
+# AUTOLOAD_EXTERNAL_TOOLS=1

.gitattributes

@@ -0,0 +1,41 @@
+# Macro for all binary files that should use Git LFS.
+[attr]lfs -text filter=lfs diff=lfs merge=lfs
+
+# Image
+*.jpg lfs
+*.jpeg lfs
+*.png lfs
+*.apng lfs
+*.atsc lfs
+*.gif lfs
+*.bmp lfs
+*.exr lfs
+*.tga lfs
+*.tiff lfs
+*.tif lfs
+*.iff lfs
+*.pict lfs
+*.dds lfs
+*.xcf lfs
+*.leo lfs
+*.kra lfs
+*.kpp lfs
+*.clip lfs
+*.webm lfs
+*.webp lfs
+*.svg lfs
+*.svgz lfs
+*.psd lfs
+*.afphoto lfs
+*.afdesign lfs
+# Models
+*.pth lfs
+# Binaries
+*.bin lfs
+*.pkl lfs
+*.pckl lfs
+# 3D
+*.ply lfs
+*.vis lfs
+*.db lfs
+*.ply lfs

.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+
+# Build and distribution
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+.hypothesis/
+htmlcov/
+coverage.xml
+*.cover
+
+# Linting and formatting
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Security
+*.key
+*.pem
+*.crt
+*.csr
+
+# Temporary files
+tmp/
+*.log
+cache/
+
+# macOS
+.DS_Store
+
+# Linux
+*~
+.directory
+.Trash-*
+.nfs*
+
+# User-created personalities (managed by UI)
+src/hello_world/profiles/user_personalities/

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,27 @@
+---
+title: Hello World
+emoji: 🤖
+colorFrom: purple
+colorTo: gray
+sdk: static
+pinned: false
+tags:
+  - reachy_mini
+  - reachy_mini_python_app
+---
+
+# Hello World
+
+Forked from the Reachy Mini conversation app.
+
+Use the `src/hello_world/profiles/_hello_world_locked_profile` folder to customize your own app from this template:
+- Edit instructions `_hello_world_locked_profile/instructions.txt`
+- Edit available tools in `_hello_world_locked_profile/tools.txt`
+- You can create your own tools in `_hello_world_locked_profile` by subclassing the `Tool` class.
+
+Do not forget to customize:
+- this `README.md` file
+- the `index.html` file (Hugging Face Spaces landing page)
+- the `src/hello_world/static/index.html` (the web app parameters page)
+
+The original README from the conversation app is available in `README_OLD.md`.

README_OLD.md

@@ -0,0 +1,319 @@
+---
+title: Reachy Mini Conversation App
+emoji: 🎤
+colorFrom: red
+colorTo: blue
+sdk: static
+pinned: false
+short_description: Talk with Reachy Mini!
+suggested_storage: large
+tags:
+ - reachy_mini
+ - reachy_mini_python_app
+---
+
+# Reachy Mini conversation app
+
+Conversational app for the Reachy Mini robot combining OpenAI's realtime APIs, vision pipelines, and choreographed motion libraries.
+
+![Reachy Mini Dance](docs/assets/reachy_mini_dance.gif)
+
+## Table of contents
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Running the app](#running-the-app)
+- [LLM tools](#llm-tools-exposed-to-the-assistant)
+- [Advanced features](#advanced-features)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+- Real-time audio conversation loop powered by the OpenAI realtime API and `fastrtc` for low-latency streaming.
+- Vision processing uses gpt-realtime by default (when camera tool is used), with optional local vision processing using SmolVLM2 model running on-device (CPU/GPU/MPS) via `--local-vision` flag.
+- Layered motion system queues primary moves (dances, emotions, goto poses, breathing) while blending speech-reactive wobble and head-tracking.
+- Async tool dispatch integrates robot motion, camera capture, and optional head-tracking capabilities through a Gradio web UI with live transcripts.
+
+## Architecture
+
+The app follows a layered architecture connecting the user, AI services, and robot hardware:
+
+<p align="center">
+  <img src="docs/assets/conversation_app_arch.svg" alt="Architecture Diagram" width="600"/>
+</p>
+
+## Installation
+
+> [!IMPORTANT]
+> Before using this app, you need to install [Reachy Mini's SDK](https://github.com/pollen-robotics/reachy_mini/).<br>
+> Windows support is currently experimental and has not been extensively tested. Use with caution.
+
+<details open>
+<summary><b>Using uv (recommended)</b></summary>
+
+Set up the project quickly using [uv](https://docs.astral.sh/uv/):
+
+```bash
+# macOS (Homebrew)
+uv venv --python /opt/homebrew/bin/python3.12 .venv
+
+# Linux / Windows (Python in PATH)
+uv venv --python python3.12 .venv
+
+source .venv/bin/activate
+uv sync
+```
+
+> **Note:** To reproduce the exact dependency set from this repo's `uv.lock`, run `uv sync --frozen`. This ensures `uv` installs directly from the lockfile without re-resolving or updating any versions.
+
+**Install optional features:**
+```bash
+uv sync --extra local_vision         # Local PyTorch/Transformers vision
+uv sync --extra yolo_vision          # YOLO-based head-tracking
+uv sync --extra mediapipe_vision     # MediaPipe-based head-tracking
+uv sync --extra all_vision           # All vision features
+```
+
+Combine extras or include dev dependencies:
+```bash
+uv sync --extra all_vision --group dev
+```
+
+</details>
+
+<details>
+<summary><b>Using pip</b></summary>
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+**Install optional features:**
+```bash
+pip install -e .[local_vision]          # Local vision stack
+pip install -e .[yolo_vision]           # YOLO-based vision
+pip install -e .[mediapipe_vision]      # MediaPipe-based vision
+pip install -e .[all_vision]            # All vision features
+pip install -e .[dev]                   # Development tools
+```
+
+Some wheels (like PyTorch) are large and require compatible CUDA or CPU builds—make sure your platform matches the binaries pulled in by each extra.
+
+</details>
+
+### Optional dependency groups
+
+| Extra | Purpose | Notes |
+|-------|---------|-------|
+| `local_vision` | Run the local VLM (SmolVLM2) through PyTorch/Transformers | GPU recommended. Ensure compatible PyTorch builds for your platform. |
+| `yolo_vision` | YOLOv11n head tracking via `ultralytics` and `supervision` | Runs on CPU (default). GPU improves performance. Supports the `--head-tracker yolo` option. |
+| `mediapipe_vision` | Lightweight landmark tracking with MediaPipe | Works on CPU. Enables `--head-tracker mediapipe`. |
+| `all_vision` | Convenience alias installing every vision extra | Install when you want the flexibility to experiment with every provider. |
+| `dev` | Developer tooling (`pytest`, `ruff`, `mypy`) | Development-only dependencies. Use `--group dev` with uv or `[dev]` with pip. |
+
+**Note:** `dev` is a dependency group (not an optional dependency). With uv, use `--group dev`. With pip, use `[dev]`.
+
+## Configuration
+
+1. Copy `.env.example` to `.env`
+2. Fill in required values, notably the OpenAI API key
+
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | Required. Grants access to the OpenAI realtime endpoint. |
+| `MODEL_NAME` | Override the realtime model (defaults to `gpt-realtime`). Used for both conversation and vision (unless `--local-vision` flag is used). |
+| `HF_HOME` | Cache directory for local Hugging Face downloads (only used with `--local-vision` flag, defaults to `./cache`). |
+| `HF_TOKEN` | Optional token for Hugging Face access (for gated/private assets). |
+| `LOCAL_VISION_MODEL` | Hugging Face model path for local vision processing (only used with `--local-vision` flag, defaults to `HuggingFaceTB/SmolVLM2-2.2B-Instruct`). |
+
+## Running the app
+
+Activate your virtual environment, then launch:
+
+```bash
+reachy-mini-conversation-app
+```
+
+> [!TIP]
+> Make sure the Reachy Mini daemon is running before launching the app. If you see a `TimeoutError`, it means the daemon isn't started. See [Reachy Mini's SDK](https://github.com/pollen-robotics/reachy_mini/) for setup instructions.
+
+The app runs in console mode by default. Add `--gradio` to launch a web UI at http://127.0.0.1:7860/ (required for simulation mode). Vision and head-tracking options are described in the CLI table below.
+
+### CLI options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--head-tracker {yolo,mediapipe}` | `None` | Select a head-tracking backend when a camera is available. YOLO is implemented locally, MediaPipe comes from the `reachy_mini_toolbox` package. Requires the matching optional extra. |
+| `--no-camera` | `False` | Run without camera capture or head tracking. |
+| `--local-vision` | `False` | Use local vision model (SmolVLM2) for periodic image processing instead of gpt-realtime vision. Requires `local_vision` extra to be installed. |
+| `--gradio` | `False` | Launch the Gradio web UI. Without this flag, runs in console mode. Required when running in simulation mode. |
+| `--robot-name` | `None` | Optional. Connect to a specific robot by name when running multiple daemons on the same subnet. See [Multiple robots on the same subnet](#advanced-features). |
+| `--debug` | `False` | Enable verbose logging for troubleshooting. |
+
+### Examples
+
+```bash
+# Run with MediaPipe head tracking
+reachy-mini-conversation-app --head-tracker mediapipe
+
+# Run with local vision processing (requires local_vision extra)
+reachy-mini-conversation-app --local-vision
+
+# Audio-only conversation (no camera)
+reachy-mini-conversation-app --no-camera
+
+# Launch with Gradio web interface
+reachy-mini-conversation-app --gradio
+```
+
+## LLM tools exposed to the assistant
+
+| Tool | Action | Dependencies |
+|------|--------|--------------|
+| `move_head` | Queue a head pose change (left/right/up/down/front). | Core install only. |
+| `camera` | Capture the latest camera frame and send it to gpt-realtime for vision analysis. | Requires camera worker. Uses gpt-realtime vision by default. |
+| `head_tracking` | Enable or disable head-tracking offsets (not identity recognition - only detects and tracks head position). | Camera worker with configured head tracker (`--head-tracker`). |
+| `dance` | Queue a dance from `reachy_mini_dances_library`. | Core install only. |
+| `stop_dance` | Clear queued dances. | Core install only. |
+| `play_emotion` | Play a recorded emotion clip via Hugging Face datasets. | Core install only. Uses the default open emotions dataset: [`pollen-robotics/reachy-mini-emotions-library`](https://huggingface.co/datasets/pollen-robotics/reachy-mini-emotions-library). |
+| `stop_emotion` | Clear queued emotions. | Core install only. |
+| `do_nothing` | Explicitly remain idle. | Core install only. |
+
+## Advanced features
+
+Built-in motion content is published as open Hugging Face datasets:
+- Emotions: [`pollen-robotics/reachy-mini-emotions-library`](https://huggingface.co/datasets/pollen-robotics/reachy-mini-emotions-library)
+- Dances: [`pollen-robotics/reachy-mini-dances-library`](https://huggingface.co/datasets/pollen-robotics/reachy-mini-dances-library)
+
+<details>
+<summary><b>Custom profiles</b></summary>
+
+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 should include `instructions.txt` (prompt text). `tools.txt` (list of allowed tools) is recommended. If missing for a non-default profile, the app falls back to `profiles/default/tools.txt`. Profiles can optionally contain custom tool 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:
+```
+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 core library `src/reachy_mini_conversation_app/tools/` (like `dance`, `head_tracking`).
+
+**Custom tools:**
+
+On top of built-in tools found in the core 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`).
+
+**Edit personalities from the UI:**
+
+When running with `--gradio`, open the "Personality" accordion:
+- Select among available profiles (folders under `src/reachy_mini_conversation_app/profiles/`) or the built‑in default.
+- Click "Apply" to update the current session instructions live.
+- Create a new personality by entering a name and instructions text. It stores files under `profiles/<name>/` and copies `tools.txt` from the `default` profile.
+
+Note: The "Personality" panel updates the conversation instructions. Tool sets are loaded at startup from `tools.txt` and are not hot‑reloaded.
+
+</details>
+
+<details>
+<summary><b>Locked profile mode</b></summary>
+
+To create a locked variant of the app that cannot switch profiles, edit `src/reachy_mini_conversation_app/config.py` and set the `LOCKED_PROFILE` constant to the desired profile name:
+```python
+LOCKED_PROFILE: str | None = "mars_rover"  # Lock to this profile
+```
+When `LOCKED_PROFILE` is set, the app always uses that profile, ignoring `REACHY_MINI_CUSTOM_PROFILE` env var & the Gradio UI shows "(locked)" and disables all profile editing controls.
+This is useful for creating dedicated clones of the app with a fixed personality. Clone scripts can simply edit this constant to lock the variant.
+
+</details>
+
+<details>
+<summary><b>External profiles and tools</b></summary>
+
+You can extend the app with profiles/tools stored outside `src/reachy_mini_conversation_app/`.
+
+- Core profiles are under `src/reachy_mini_conversation_app/profiles/`.
+- Core tools are under `src/reachy_mini_conversation_app/tools/`.
+
+**Recommended layout:**
+
+```text
+external_content/
+├── external_profiles/
+│   └── my_profile/
+│       ├── instructions.txt
+│       ├── tools.txt        # optional (see fallback behavior below)
+│       └── voice.txt        # optional
+└── external_tools/
+    └── my_custom_tool.py
+```
+
+**Environment variables:**
+
+Set these values in your `.env` (copy from `.env.example`):
+
+```env
+REACHY_MINI_CUSTOM_PROFILE=my_profile
+REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY=./external_content/external_profiles
+REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY=./external_content/external_tools
+# Optional convenience mode:
+# AUTOLOAD_EXTERNAL_TOOLS=1
+```
+
+**Loading behavior:**
+
+- **Default/strict mode**: `tools.txt` defines enabled tools explicitly. Every name in `tools.txt` must resolve to either a built-in tool (`src/reachy_mini_conversation_app/tools/`) or an external tool module in `REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY`.
+- **Convenience mode** (`AUTOLOAD_EXTERNAL_TOOLS=1`): all valid `*.py` tool files in `REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY` are auto-added.
+- **External profile fallback**: if the selected external profile has no `tools.txt`, the app falls back to built-in `profiles/default/tools.txt`.
+
+This supports both:
+1. Downloaded external tools used with built-in/default profile.
+2. Downloaded external profiles used with built-in default tools.
+
+</details>
+
+<details>
+<summary><b>Multiple robots on the same subnet</b></summary>
+
+If you run multiple Reachy Mini daemons on the same network, use:
+
+```bash
+reachy-mini-conversation-app --robot-name <name>
+```
+
+`<name>` must match the daemon's `--robot-name` value so the app connects to the correct robot.
+
+</details>
+
+## Contributing
+
+We welcome bug fixes, features, profiles, and documentation improvements. Please review our
+[contribution guide](CONTRIBUTING.md) for branch conventions, quality checks, and PR workflow.
+
+Quick start:
+- Fork and clone the repo
+- Follow the [installation steps](#installation) (include the `dev` dependency group)
+- Run contributor checks listed in [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+Apache 2.0

docs/scheme.mmd

@@ -0,0 +1,63 @@
+---
+config:
+  layout: dagre
+  flowchart:
+    htmlLabels: true
+---
+flowchart TB
+    User(["<span style='font-size:16px;font-weight:bold;'>User</span><br><span style='font-size:13px;color:#01579b;'>Person interacting with system</span>"]) 
+      -- audio stream --> 
+    UI@{ label: "<span style='font-size:16px;font-weight:bold;'>UI Layer</span><br><span style='font-size:13px;color:#0277bd;'>Gradio/Console</span>" }
+
+    UI -- audio stream --> 
+    OpenAI@{ label: "<span style='font-size:17px;font-weight:bold;'>gpt-realtime API</span><br><span style='font-size:13px; color:#7b1fa2;'>Audio+Tool Calls+Vision</span>" }
+
+    OpenAI -- audio stream --> 
+    Motion@{ label: "<span style='font-size:16px;font-weight:bold;'>Motion Control</span><br><span style='font-size:13px;color:#f57f17;'>Audio Sync + Tracking</span>" }
+    
+    OpenAI -- tool calls --> 
+    Handlers@{ label: "<span style='font-size:16px;font-weight:bold;'>Tool Layer</span><br><span style='font-size:12px;color:#f9a825;'>Built-in tools + profile-local tools<br/>+ external tools (optional)</span>" }
+
+    Profiles@{ label: "<span style='font-size:16px;font-weight:bold;'>Selected Profile</span><br><span style='font-size:12px;color:#6a1b9a;'>built-in or external<br/>instructions.txt + tools.txt</span>" }
+
+    Profiles -- defines enabled tools --> Handlers
+
+    Handlers -- movement 
+    requests --> Motion
+
+    Handlers -- camera frames, head tracking --> 
+    Camera@{ label: "<span style='font-size:16px;font-weight:bold;'>Camera Worker</span><br><span style='font-size:13px;color:#f57f17;'>Frame Buffer + Head Tracking</span>" }
+    
+    Handlers -. image for 
+    analysis .-> OpenAI
+
+    Camera -- head tracking --> Motion
+
+    Camera -. frames .-> 
+    Vision@{ label: "<span style='font-size:16px;font-weight:bold;'>Vision Processor</span><br><span style='font-size:13px;color:#7b1fa2;'>Local VLM (optional)</span>" }
+
+    Vision -. description .-> Handlers
+
+    Robot@{ label: "<span style='font-size:16px;font-weight:bold;'>reachy_mini</span><br><span style='font-size:13px;color:#c62828;'>Robot Control Library</span>" } 
+    -- camera 
+    frames --> Camera
+
+    Motion -- commands --> Robot
+
+    Handlers -- results --> OpenAI
+
+     User:::userStyle
+     UI:::uiStyle
+     OpenAI:::aiStyle
+     Motion:::coreStyle
+     Profiles:::toolStyle
+     Handlers:::toolStyle
+     Camera:::coreStyle
+     Vision:::aiStyle
+     Robot:::hardwareStyle
+    classDef userStyle fill:#e1f5fe,stroke:#01579b,stroke-width:3px
+    classDef uiStyle fill:#b3e5fc,stroke:#0277bd,stroke-width:2px
+    classDef aiStyle fill:#e1bee7,stroke:#7b1fa2,stroke-width:3px
+    classDef coreStyle fill:#fff9c4,stroke:#f57f17,stroke-width:2px
+    classDef hardwareStyle fill:#ef9a9a,stroke:#c62828,stroke-width:3px
+    classDef toolStyle fill:#fffde7,stroke:#f9a825,stroke-width:1px

external_content/external_profiles/starter_profile/instructions.txt

@@ -0,0 +1,6 @@
+You are a helpful Reachy Mini assistant running from an external profile.
+
+When asked to demonstrate your custom greeting, use the `starter_custom_tool` tool.
+You can also dance and show emotions like the built-in profiles.
+
+Be friendly and concise, and explain that you're using an external profile/tool setup when asked about yourself.

external_content/external_profiles/starter_profile/tools.txt

@@ -0,0 +1,11 @@
+# This file is an explicit allow-list.
+# Every tool name listed below must be either:
+# - a built-in tool from src/reachy_mini_conversation_app/tools/
+# - or an external tool file in TOOLS_DIRECTORY (e.g. external_tools/starter_custom_tool.py)
+
+dance
+stop_dance
+play_emotion
+stop_emotion
+move_head
+starter_custom_tool

external_content/external_tools/starter_custom_tool.py

@@ -0,0 +1,33 @@
+"""Example external tool implementation."""
+
+import logging
+from typing import Any, Dict
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+
+
+logger = logging.getLogger(__name__)
+
+
+class StarterCustomTool(Tool):
+    """Placeholder custom tool - demonstrates external tool loading."""
+
+    name = "starter_custom_tool"
+    description = "A placeholder custom tool loaded from outside the library"
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "message": {
+                "type": "string",
+                "description": "Optional message to include in the response",
+            },
+        },
+        "required": [],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> Dict[str, Any]:
+        """Execute the placeholder tool."""
+        message = kwargs.get("message", "Hello from custom tool!")
+        logger.info(f"Tool call: starter_custom_tool message={message}")
+
+        return {"status": "success", "message": message}

index.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hello World</title>
+    <link rel="stylesheet" href="style.css" />
+  </head>
+  <body>
+    <div class="ambient"></div>
+    <div class="container">
+      <header class="hero">
+        <div class="pill">Reachy Mini App</div>
+        <h1>Hello World</h1>
+        <p class="subtitle">A conversation app for Reachy Mini robot.</p>
+      </header>
+
+      <div class="panel">
+        <div class="panel-heading">
+          <div>
+            <p class="eyebrow">Getting Started</p>
+            <h2>Installation</h2>
+          </div>
+        </div>
+        <p class="muted">Install this app on your Reachy Mini using the app store, or run it locally:</p>
+        <pre><code>uv sync
+reachy-mini-daemon --sim  # in another terminal
+python -m hello_world</code></pre>
+      </div>
+
+      <div class="panel">
+        <div class="panel-heading">
+          <div>
+            <p class="eyebrow">Configuration</p>
+            <h2>OpenAI API Key</h2>
+          </div>
+        </div>
+        <p class="muted">This app requires an OpenAI API key for voice conversations. Set it via the web interface or environment variable.</p>
+      </div>
+    </div>
+  </body>
+</html>

pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = [ "setuptools",]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hello_world"
+version = "0.3.0"
+description = ""
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [ "aiortc>=1.13.0", "fastrtc>=0.0.34", "gradio==5.50.1.dev1", "huggingface-hub==1.3.0", "opencv-python>=4.12.0.88", "python-dotenv", "openai>=2.1", "reachy_mini_dances_library", "reachy_mini_toolbox", "reachy-mini>=1.5.0", "eclipse-zenoh~=1.7.0", "gradio_client>=1.13.3",]
+[[project.authors]]
+name = "Pollen Robotics"
+email = "contact@pollen-robotics.com"
+
+[dependency-groups]
+dev = [ "pytest", "pytest-asyncio", "ruff==0.12.0", "mypy==1.18.2", "pre-commit", "types-requests", "python-semantic-release>=10.5.3",]
+
+[project.optional-dependencies]
+local_vision = [ "torch>=2.1", "transformers==5.0.0rc2", "num2words",]
+yolo_vision = [ "ultralytics", "supervision",]
+mediapipe_vision = [ "mediapipe==0.10.14",]
+all_vision = [ "torch>=2.1", "transformers==5.0.0rc2", "num2words", "ultralytics", "supervision", "mediapipe==0.10.14",]
+
+[project.scripts]
+hello-world = "hello_world.main:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.ruff]
+line-length = 119
+exclude = [ ".venv", "dist", "build", "**/__pycache__", "*.egg-info", ".mypy_cache", ".pytest_cache",]
+
+[tool.mypy]
+python_version = "3.12"
+files = [ "src/",]
+ignore_missing_imports = true
+strict = true
+show_error_codes = true
+warn_unused_ignores = true
+
+[project.entry-points.reachy_mini_apps]
+hello_world = "hello_world.main:HelloWorld"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.package-data]
+hello_world = [ "images/*", "static/*", ".env.example", "demos/**/*.txt", "prompts_library/*.txt", "profiles/**/*.txt", "prompts/**/*.txt",]
+
+[tool.ruff.lint]
+select = [ "E", "F", "W", "I", "C4", "D",]
+ignore = [ "E501", "D100", "D203", "D213",]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.setuptools.packages.find]
+where = [ "src",]
+
+[tool.ruff.lint.isort]
+length-sort = true
+lines-after-imports = 2
+no-lines-before = [ "standard-library", "local-folder",]
+known-local-folder = [ "hello_world",]
+known-first-party = [ "reachy_mini", "reachy_mini_dances_library", "reachy_mini_toolbox",]
+split-on-trailing-comma = true

src/hello_world/__init__.py

@@ -0,0 +1 @@
+"""Nothing (for ruff)."""

src/hello_world/audio/__init__.py

@@ -0,0 +1 @@
+"""Nothing (for ruff)."""

src/hello_world/audio/head_wobbler.py

@@ -0,0 +1,181 @@
+"""Moves head given audio samples."""
+
+import time
+import queue
+import base64
+import logging
+import threading
+from typing import Tuple
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from hello_world.audio.speech_tapper import HOP_MS, SwayRollRT
+
+
+SAMPLE_RATE = 24000
+MOVEMENT_LATENCY_S = 0.2  # seconds between audio and robot movement
+logger = logging.getLogger(__name__)
+
+
+class HeadWobbler:
+    """Converts audio deltas (base64) into head movement offsets."""
+
+    def __init__(self, set_speech_offsets: Callable[[Tuple[float, float, float, float, float, float]], None]) -> None:
+        """Initialize the head wobbler."""
+        self._apply_offsets = set_speech_offsets
+        self._base_ts: float | None = None
+        self._hops_done: int = 0
+
+        self.audio_queue: "queue.Queue[Tuple[int, int, NDArray[np.int16]]]" = queue.Queue()
+        self.sway = SwayRollRT()
+
+        # Synchronization primitives
+        self._state_lock = threading.Lock()
+        self._sway_lock = threading.Lock()
+        self._generation = 0
+
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def feed(self, delta_b64: str) -> None:
+        """Thread-safe: push audio into the consumer queue."""
+        buf = np.frombuffer(base64.b64decode(delta_b64), dtype=np.int16).reshape(1, -1)
+        with self._state_lock:
+            generation = self._generation
+        self.audio_queue.put((generation, SAMPLE_RATE, buf))
+
+    def start(self) -> None:
+        """Start the head wobbler loop in a thread."""
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self.working_loop, daemon=True)
+        self._thread.start()
+        logger.debug("Head wobbler started")
+
+    def stop(self) -> None:
+        """Stop the head wobbler loop."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join()
+        logger.debug("Head wobbler stopped")
+
+    def working_loop(self) -> None:
+        """Convert audio deltas into head movement offsets."""
+        hop_dt = HOP_MS / 1000.0
+
+        logger.debug("Head wobbler thread started")
+        while not self._stop_event.is_set():
+            queue_ref = self.audio_queue
+            try:
+                chunk_generation, sr, chunk = queue_ref.get_nowait()  # (gen, sr, data)
+            except queue.Empty:
+                # avoid while to never exit
+                time.sleep(MOVEMENT_LATENCY_S)
+                continue
+
+            try:
+                with self._state_lock:
+                    current_generation = self._generation
+                if chunk_generation != current_generation:
+                    continue
+
+                if self._base_ts is None:
+                    with self._state_lock:
+                        if self._base_ts is None:
+                            self._base_ts = time.monotonic()
+
+                pcm = np.asarray(chunk).squeeze(0)
+                with self._sway_lock:
+                    results = self.sway.feed(pcm, sr)
+
+                i = 0
+                while i < len(results):
+                    with self._state_lock:
+                        if self._generation != current_generation:
+                            break
+                        base_ts = self._base_ts
+                        hops_done = self._hops_done
+
+                    if base_ts is None:
+                        base_ts = time.monotonic()
+                        with self._state_lock:
+                            if self._base_ts is None:
+                                self._base_ts = base_ts
+                                hops_done = self._hops_done
+
+                    target = base_ts + MOVEMENT_LATENCY_S + hops_done * hop_dt
+                    now = time.monotonic()
+
+                    if now - target >= hop_dt:
+                        lag_hops = int((now - target) / hop_dt)
+                        drop = min(lag_hops, len(results) - i - 1)
+                        if drop > 0:
+                            with self._state_lock:
+                                self._hops_done += drop
+                                hops_done = self._hops_done
+                            i += drop
+                            continue
+
+                    if target > now:
+                        time.sleep(target - now)
+                        with self._state_lock:
+                            if self._generation != current_generation:
+                                break
+
+                    r = results[i]
+                    offsets = (
+                        r["x_mm"] / 1000.0,
+                        r["y_mm"] / 1000.0,
+                        r["z_mm"] / 1000.0,
+                        r["roll_rad"],
+                        r["pitch_rad"],
+                        r["yaw_rad"],
+                    )
+
+                    with self._state_lock:
+                        if self._generation != current_generation:
+                            break
+
+                    self._apply_offsets(offsets)
+
+                    with self._state_lock:
+                        self._hops_done += 1
+                    i += 1
+            finally:
+                queue_ref.task_done()
+        logger.debug("Head wobbler thread exited")
+
+    '''
+    def drain_audio_queue(self) -> None:
+        """Empty the audio queue."""
+        try:
+            while True:
+                self.audio_queue.get_nowait()
+        except QueueEmpty:
+            pass
+    '''
+
+    def reset(self) -> None:
+        """Reset the internal state."""
+        with self._state_lock:
+            self._generation += 1
+            self._base_ts = None
+            self._hops_done = 0
+
+        # Drain any queued audio chunks from previous generations
+        drained_any = False
+        while True:
+            try:
+                _, _, _ = self.audio_queue.get_nowait()
+            except queue.Empty:
+                break
+            else:
+                drained_any = True
+                self.audio_queue.task_done()
+
+        with self._sway_lock:
+            self.sway.reset()
+
+        if drained_any:
+            logger.debug("Head wobbler queue drained during reset")

src/hello_world/audio/speech_tapper.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+import math
+from typing import Any, Dict, List
+from itertools import islice
+from collections import deque
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+# Tunables
+SR = 16_000
+FRAME_MS = 20
+HOP_MS = 50
+
+SWAY_MASTER = 1.5
+SENS_DB_OFFSET = +4.0
+VAD_DB_ON = -35.0
+VAD_DB_OFF = -45.0
+VAD_ATTACK_MS = 40
+VAD_RELEASE_MS = 250
+ENV_FOLLOW_GAIN = 0.65
+
+SWAY_F_PITCH = 2.2
+SWAY_A_PITCH_DEG = 4.5
+SWAY_F_YAW = 0.6
+SWAY_A_YAW_DEG = 7.5
+SWAY_F_ROLL = 1.3
+SWAY_A_ROLL_DEG = 2.25
+SWAY_F_X = 0.35
+SWAY_A_X_MM = 4.5
+SWAY_F_Y = 0.45
+SWAY_A_Y_MM = 3.75
+SWAY_F_Z = 0.25
+SWAY_A_Z_MM = 2.25
+
+SWAY_DB_LOW = -46.0
+SWAY_DB_HIGH = -18.0
+LOUDNESS_GAMMA = 0.9
+SWAY_ATTACK_MS = 50
+SWAY_RELEASE_MS = 250
+
+# Derived
+FRAME = int(SR * FRAME_MS / 1000)
+HOP = int(SR * HOP_MS / 1000)
+ATTACK_FR = max(1, int(VAD_ATTACK_MS / HOP_MS))
+RELEASE_FR = max(1, int(VAD_RELEASE_MS / HOP_MS))
+SWAY_ATTACK_FR = max(1, int(SWAY_ATTACK_MS / HOP_MS))
+SWAY_RELEASE_FR = max(1, int(SWAY_RELEASE_MS / HOP_MS))
+
+
+def _rms_dbfs(x: NDArray[np.float32]) -> float:
+    """Root-mean-square in dBFS for float32 mono array in [-1,1]."""
+    # numerically stable rms (avoid overflow)
+    x = x.astype(np.float32, copy=False)
+    rms = np.sqrt(np.mean(x * x, dtype=np.float32) + 1e-12, dtype=np.float32)
+    return float(20.0 * math.log10(float(rms) + 1e-12))
+
+
+def _loudness_gain(db: float, offset: float = SENS_DB_OFFSET) -> float:
+    """Normalize dB into [0,1] with gamma; clipped to [0,1]."""
+    t = (db + offset - SWAY_DB_LOW) / (SWAY_DB_HIGH - SWAY_DB_LOW)
+    if t < 0.0:
+        t = 0.0
+    elif t > 1.0:
+        t = 1.0
+    return t**LOUDNESS_GAMMA if LOUDNESS_GAMMA != 1.0 else t
+
+
+def _to_float32_mono(x: NDArray[Any]) -> NDArray[np.float32]:
+    """Convert arbitrary PCM array to float32 mono in [-1,1].
+
+    Accepts shapes: (N,), (1,N), (N,1), (C,N), (N,C).
+    """
+    a = np.asarray(x)
+    if a.ndim == 0:
+        return np.zeros(0, dtype=np.float32)
+
+    # If 2D, decide which axis is channels (prefer small first dim)
+    if a.ndim == 2:
+        # e.g., (channels, samples) if channels is small (<=8)
+        if a.shape[0] <= 8 and a.shape[0] <= a.shape[1]:
+            a = np.mean(a, axis=0)
+        else:
+            a = np.mean(a, axis=1)
+    elif a.ndim > 2:
+        a = np.mean(a.reshape(a.shape[0], -1), axis=0)
+
+    # Now 1D, cast/scale
+    if np.issubdtype(a.dtype, np.floating):
+        return a.astype(np.float32, copy=False)
+    # integer PCM
+    info = np.iinfo(a.dtype)
+    scale = float(max(-info.min, info.max))
+    return a.astype(np.float32) / (scale if scale != 0.0 else 1.0)
+
+
+def _resample_linear(x: NDArray[np.float32], sr_in: int, sr_out: int) -> NDArray[np.float32]:
+    """Lightweight linear resampler for short buffers."""
+    if sr_in == sr_out or x.size == 0:
+        return x
+    # guard tiny sizes
+    n_out = int(round(x.size * sr_out / sr_in))
+    if n_out <= 1:
+        return np.zeros(0, dtype=np.float32)
+    t_in = np.linspace(0.0, 1.0, num=x.size, dtype=np.float32, endpoint=True)
+    t_out = np.linspace(0.0, 1.0, num=n_out, dtype=np.float32, endpoint=True)
+    return np.interp(t_out, t_in, x).astype(np.float32, copy=False)
+
+
+class SwayRollRT:
+    """Feed audio chunks → per-hop sway outputs.
+
+    Usage:
+        rt = SwayRollRT()
+        rt.feed(pcm_int16_or_float, sr) -> List[dict]
+    """
+
+    def __init__(self, rng_seed: int = 7):
+        """Initialize state."""
+        self._seed = int(rng_seed)
+        self.samples: deque[float] = deque(maxlen=10 * SR)  # sliding window for VAD/env
+        self.carry: NDArray[np.float32] = np.zeros(0, dtype=np.float32)
+
+        self.vad_on = False
+        self.vad_above = 0
+        self.vad_below = 0
+
+        self.sway_env = 0.0
+        self.sway_up = 0
+        self.sway_down = 0
+
+        rng = np.random.default_rng(self._seed)
+        self.phase_pitch = float(rng.random() * 2 * math.pi)
+        self.phase_yaw = float(rng.random() * 2 * math.pi)
+        self.phase_roll = float(rng.random() * 2 * math.pi)
+        self.phase_x = float(rng.random() * 2 * math.pi)
+        self.phase_y = float(rng.random() * 2 * math.pi)
+        self.phase_z = float(rng.random() * 2 * math.pi)
+        self.t = 0.0
+
+    def reset(self) -> None:
+        """Reset state (VAD/env/buffers/time) but keep initial phases/seed."""
+        self.samples.clear()
+        self.carry = np.zeros(0, dtype=np.float32)
+        self.vad_on = False
+        self.vad_above = 0
+        self.vad_below = 0
+        self.sway_env = 0.0
+        self.sway_up = 0
+        self.sway_down = 0
+        self.t = 0.0
+
+    def feed(self, pcm: NDArray[Any], sr: int | None) -> List[Dict[str, float]]:
+        """Stream in PCM chunk. Returns a list of sway dicts, one per hop (HOP_MS).
+
+        Args:
+            pcm: np.ndarray, shape (N,) or (C,N)/(N,C); int or float.
+            sr:  sample rate of `pcm` (None -> assume SR).
+
+        """
+        sr_in = SR if sr is None else int(sr)
+        x = _to_float32_mono(pcm)
+        if x.size == 0:
+            return []
+        if sr_in != SR:
+            x = _resample_linear(x, sr_in, SR)
+            if x.size == 0:
+                return []
+
+        # append to carry and consume fixed HOP chunks
+        if self.carry.size:
+            self.carry = np.concatenate([self.carry, x])
+        else:
+            self.carry = x
+
+        out: List[Dict[str, float]] = []
+
+        while self.carry.size >= HOP:
+            hop = self.carry[:HOP]
+            remaining: NDArray[np.float32] = self.carry[HOP:]
+            self.carry = remaining
+
+            # keep sliding window for VAD/env computation
+            # (deque accepts any iterable; list() for small HOP is fine)
+            self.samples.extend(hop.tolist())
+            if len(self.samples) < FRAME:
+                self.t += HOP_MS / 1000.0
+                continue
+
+            frame = np.fromiter(
+                islice(self.samples, len(self.samples) - FRAME, len(self.samples)),
+                dtype=np.float32,
+                count=FRAME,
+            )
+            db = _rms_dbfs(frame)
+
+            # VAD with hysteresis + attack/release
+            if db >= VAD_DB_ON:
+                self.vad_above += 1
+                self.vad_below = 0
+                if not self.vad_on and self.vad_above >= ATTACK_FR:
+                    self.vad_on = True
+            elif db <= VAD_DB_OFF:
+                self.vad_below += 1
+                self.vad_above = 0
+                if self.vad_on and self.vad_below >= RELEASE_FR:
+                    self.vad_on = False
+
+            if self.vad_on:
+                self.sway_up = min(SWAY_ATTACK_FR, self.sway_up + 1)
+                self.sway_down = 0
+            else:
+                self.sway_down = min(SWAY_RELEASE_FR, self.sway_down + 1)
+                self.sway_up = 0
+
+            up = self.sway_up / SWAY_ATTACK_FR
+            down = 1.0 - (self.sway_down / SWAY_RELEASE_FR)
+            target = up if self.vad_on else down
+            self.sway_env += ENV_FOLLOW_GAIN * (target - self.sway_env)
+            # clamp
+            if self.sway_env < 0.0:
+                self.sway_env = 0.0
+            elif self.sway_env > 1.0:
+                self.sway_env = 1.0
+
+            loud = _loudness_gain(db) * SWAY_MASTER
+            env = self.sway_env
+            self.t += HOP_MS / 1000.0
+
+            # oscillators
+            pitch = (
+                math.radians(SWAY_A_PITCH_DEG)
+                * loud
+                * env
+                * math.sin(2 * math.pi * SWAY_F_PITCH * self.t + self.phase_pitch)
+            )
+            yaw = (
+                math.radians(SWAY_A_YAW_DEG)
+                * loud
+                * env
+                * math.sin(2 * math.pi * SWAY_F_YAW * self.t + self.phase_yaw)
+            )
+            roll = (
+                math.radians(SWAY_A_ROLL_DEG)
+                * loud
+                * env
+                * math.sin(2 * math.pi * SWAY_F_ROLL * self.t + self.phase_roll)
+            )
+            x_mm = SWAY_A_X_MM * loud * env * math.sin(2 * math.pi * SWAY_F_X * self.t + self.phase_x)
+            y_mm = SWAY_A_Y_MM * loud * env * math.sin(2 * math.pi * SWAY_F_Y * self.t + self.phase_y)
+            z_mm = SWAY_A_Z_MM * loud * env * math.sin(2 * math.pi * SWAY_F_Z * self.t + self.phase_z)
+
+            out.append(
+                {
+                    "pitch_rad": pitch,
+                    "yaw_rad": yaw,
+                    "roll_rad": roll,
+                    "pitch_deg": math.degrees(pitch),
+                    "yaw_deg": math.degrees(yaw),
+                    "roll_deg": math.degrees(roll),
+                    "x_mm": x_mm,
+                    "y_mm": y_mm,
+                    "z_mm": z_mm,
+                },
+            )
+
+        return out

src/hello_world/camera_worker.py

@@ -0,0 +1,241 @@
+"""Camera worker thread with frame buffering and face tracking.
+
+Ported from main_works.py camera_worker() function to provide:
+- 30Hz+ camera polling with thread-safe frame buffering
+- Face tracking integration with smooth interpolation
+- Latest frame always available for tools
+"""
+
+import time
+import logging
+import threading
+from typing import Any, List, Tuple
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.spatial.transform import Rotation as R
+
+from reachy_mini import ReachyMini
+from reachy_mini.utils.interpolation import linear_pose_interpolation
+
+
+logger = logging.getLogger(__name__)
+
+
+class CameraWorker:
+    """Thread-safe camera worker with frame buffering and face tracking."""
+
+    def __init__(self, reachy_mini: ReachyMini, head_tracker: Any = None) -> None:
+        """Initialize."""
+        self.reachy_mini = reachy_mini
+        self.head_tracker = head_tracker
+
+        # Thread-safe frame storage
+        self.latest_frame: NDArray[np.uint8] | None = None
+        self.frame_lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+        # Face tracking state
+        self.is_head_tracking_enabled = True
+        self.face_tracking_offsets: List[float] = [
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+        ]  # x, y, z, roll, pitch, yaw
+        self.face_tracking_lock = threading.Lock()
+
+        # Face tracking timing variables (same as main_works.py)
+        self.last_face_detected_time: float | None = None
+        self.interpolation_start_time: float | None = None
+        self.interpolation_start_pose: NDArray[np.float32] | None = None
+        self.face_lost_delay = 2.0  # seconds to wait before starting interpolation
+        self.interpolation_duration = 1.0  # seconds to interpolate back to neutral
+
+        # Track state changes
+        self.previous_head_tracking_state = self.is_head_tracking_enabled
+
+    def get_latest_frame(self) -> NDArray[np.uint8] | None:
+        """Get the latest frame (thread-safe)."""
+        with self.frame_lock:
+            if self.latest_frame is None:
+                return None
+            # Return a copy in original BGR format (OpenCV native)
+            return self.latest_frame.copy()
+
+    def get_face_tracking_offsets(
+        self,
+    ) -> Tuple[float, float, float, float, float, float]:
+        """Get current face tracking offsets (thread-safe)."""
+        with self.face_tracking_lock:
+            offsets = self.face_tracking_offsets
+            return (offsets[0], offsets[1], offsets[2], offsets[3], offsets[4], offsets[5])
+
+    def set_head_tracking_enabled(self, enabled: bool) -> None:
+        """Enable/disable head tracking."""
+        self.is_head_tracking_enabled = enabled
+        logger.info(f"Head tracking {'enabled' if enabled else 'disabled'}")
+
+    def start(self) -> None:
+        """Start the camera worker loop in a thread."""
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self.working_loop, daemon=True)
+        self._thread.start()
+        logger.debug("Camera worker started")
+
+    def stop(self) -> None:
+        """Stop the camera worker loop."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join()
+
+        logger.debug("Camera worker stopped")
+
+    def working_loop(self) -> None:
+        """Enable the camera worker loop.
+
+        Ported from main_works.py camera_worker() with same logic.
+        """
+        logger.debug("Starting camera working loop")
+
+        # Initialize head tracker if available
+        neutral_pose = np.eye(4)  # Neutral pose (identity matrix)
+        self.previous_head_tracking_state = self.is_head_tracking_enabled
+
+        while not self._stop_event.is_set():
+            try:
+                current_time = time.time()
+
+                # Get frame from robot
+                frame = self.reachy_mini.media.get_frame()
+
+                if frame is not None:
+                    # Thread-safe frame storage
+                    with self.frame_lock:
+                        self.latest_frame = frame  # .copy()
+
+                    # Check if face tracking was just disabled
+                    if self.previous_head_tracking_state and not self.is_head_tracking_enabled:
+                        # Face tracking was just disabled - start interpolation to neutral
+                        self.last_face_detected_time = current_time  # Trigger the face-lost logic
+                        self.interpolation_start_time = None  # Will be set by the face-lost interpolation
+                        self.interpolation_start_pose = None
+
+                    # Update tracking state
+                    self.previous_head_tracking_state = self.is_head_tracking_enabled
+
+                    # Handle face tracking if enabled and head tracker available
+                    if self.is_head_tracking_enabled and self.head_tracker is not None:
+                        eye_center, _ = self.head_tracker.get_head_position(frame)
+
+                        if eye_center is not None:
+                            # Face detected - immediately switch to tracking
+                            self.last_face_detected_time = current_time
+                            self.interpolation_start_time = None  # Stop any interpolation
+
+                            # Convert normalized coordinates to pixel coordinates
+                            h, w, _ = frame.shape
+                            eye_center_norm = (eye_center + 1) / 2
+                            eye_center_pixels = [
+                                eye_center_norm[0] * w,
+                                eye_center_norm[1] * h,
+                            ]
+
+                            # Get the head pose needed to look at the target, but don't perform movement
+                            target_pose = self.reachy_mini.look_at_image(
+                                eye_center_pixels[0],
+                                eye_center_pixels[1],
+                                duration=0.0,
+                                perform_movement=False,
+                            )
+
+                            # Extract translation and rotation from the target pose directly
+                            translation = target_pose[:3, 3]
+                            rotation = R.from_matrix(target_pose[:3, :3]).as_euler("xyz", degrees=False)
+
+                            # Scale down translation and rotation because smaller FOV
+                            translation *= 0.6
+                            rotation *= 0.6
+
+                            # Thread-safe update of face tracking offsets (use pose as-is)
+                            with self.face_tracking_lock:
+                                self.face_tracking_offsets = [
+                                    translation[0],
+                                    translation[1],
+                                    translation[2],  # x, y, z
+                                    rotation[0],
+                                    rotation[1],
+                                    rotation[2],  # roll, pitch, yaw
+                                ]
+
+                        # No face detected while tracking enabled - set face lost timestamp
+                        elif self.last_face_detected_time is None or self.last_face_detected_time == current_time:
+                            # Only update if we haven't already set a face lost time
+                            # (current_time check prevents overriding the disable-triggered timestamp)
+                            pass
+
+                    # Handle smooth interpolation (works for both face-lost and tracking-disabled cases)
+                    if self.last_face_detected_time is not None:
+                        time_since_face_lost = current_time - self.last_face_detected_time
+
+                        if time_since_face_lost >= self.face_lost_delay:
+                            # Start interpolation if not already started
+                            if self.interpolation_start_time is None:
+                                self.interpolation_start_time = current_time
+                                # Capture current pose as start of interpolation
+                                with self.face_tracking_lock:
+                                    current_translation = self.face_tracking_offsets[:3]
+                                    current_rotation_euler = self.face_tracking_offsets[3:]
+                                    # Convert to 4x4 pose matrix
+                                    pose_matrix = np.eye(4, dtype=np.float32)
+                                    pose_matrix[:3, 3] = current_translation
+                                    pose_matrix[:3, :3] = R.from_euler(
+                                        "xyz",
+                                        current_rotation_euler,
+                                    ).as_matrix()
+                                    self.interpolation_start_pose = pose_matrix
+
+                            # Calculate interpolation progress (t from 0 to 1)
+                            elapsed_interpolation = current_time - self.interpolation_start_time
+                            t = min(1.0, elapsed_interpolation / self.interpolation_duration)
+
+                            # Interpolate between current pose and neutral pose
+                            interpolated_pose = linear_pose_interpolation(
+                                self.interpolation_start_pose,
+                                neutral_pose,
+                                t,
+                            )
+
+                            # Extract translation and rotation from interpolated pose
+                            translation = interpolated_pose[:3, 3]
+                            rotation = R.from_matrix(interpolated_pose[:3, :3]).as_euler("xyz", degrees=False)
+
+                            # Thread-safe update of face tracking offsets
+                            with self.face_tracking_lock:
+                                self.face_tracking_offsets = [
+                                    translation[0],
+                                    translation[1],
+                                    translation[2],  # x, y, z
+                                    rotation[0],
+                                    rotation[1],
+                                    rotation[2],  # roll, pitch, yaw
+                                ]
+
+                            # If interpolation is complete, reset timing
+                            if t >= 1.0:
+                                self.last_face_detected_time = None
+                                self.interpolation_start_time = None
+                                self.interpolation_start_pose = None
+                        # else: Keep current offsets (within 2s delay period)
+
+                # Small sleep to prevent excessive CPU usage (same as main_works.py)
+                time.sleep(0.04)
+
+            except Exception as e:
+                logger.error(f"Camera worker error: {e}")
+                time.sleep(0.1)  # Longer sleep on error
+
+        logger.debug("Camera worker thread exited")

src/hello_world/config.py

@@ -0,0 +1,217 @@
+import os
+import sys
+import logging
+from pathlib import Path
+
+from dotenv import find_dotenv, load_dotenv
+
+
+# Locked profile: set to a profile name (e.g., "astronomer") to lock the app
+# to that profile and disable all profile switching. Leave as None for normal behavior.
+LOCKED_PROFILE: str | None = "_hello_world_locked_profile"
+DEFAULT_PROFILES_DIRECTORY = Path(__file__).parent / "profiles"
+
+logger = logging.getLogger(__name__)
+
+
+def _env_flag(name: str, default: bool = False) -> bool:
+    """Parse a boolean environment flag.
+
+    Accepted truthy values: 1, true, yes, on
+    Accepted falsy values: 0, false, no, off
+    """
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+
+    value = raw.strip().lower()
+    if value in {"1", "true", "yes", "on"}:
+        return True
+    if value in {"0", "false", "no", "off"}:
+        return False
+
+    logger.warning("Invalid boolean value for %s=%r, using default=%s", name, raw, default)
+    return default
+
+
+def _collect_profile_names(profiles_root: Path) -> set[str]:
+    """Return profile folder names from a profiles root directory."""
+    if not profiles_root.exists() or not profiles_root.is_dir():
+        return set()
+    return {p.name for p in profiles_root.iterdir() if p.is_dir()}
+
+
+def _collect_tool_module_names(tools_root: Path) -> set[str]:
+    """Return tool module names from a tools directory."""
+    if not tools_root.exists() or not tools_root.is_dir():
+        return set()
+    ignored = {"__init__", "core_tools"}
+    return {
+        p.stem
+        for p in tools_root.glob("*.py")
+        if p.is_file() and p.stem not in ignored
+    }
+
+
+def _raise_on_name_collisions(
+    *,
+    label: str,
+    external_root: Path,
+    internal_root: Path,
+    external_names: set[str],
+    internal_names: set[str],
+) -> None:
+    """Raise with a clear message when external/internal names collide."""
+    collisions = sorted(external_names & internal_names)
+    if not collisions:
+        return
+
+    raise RuntimeError(
+        f"Config.__init__(): Ambiguous {label} names found in both external and built-in libraries: {collisions}. "
+        f"External {label} root: {external_root}. Built-in {label} root: {internal_root}. "
+        f"Please rename the conflicting external {label}(s) to continue."
+    )
+
+
+# Validate LOCKED_PROFILE at startup
+if LOCKED_PROFILE is not None:
+    _profiles_dir = DEFAULT_PROFILES_DIRECTORY
+    _profile_path = _profiles_dir / LOCKED_PROFILE
+    _instructions_file = _profile_path / "instructions.txt"
+    if not _profile_path.is_dir():
+        print(f"Error: LOCKED_PROFILE '{LOCKED_PROFILE}' does not exist in {_profiles_dir}", file=sys.stderr)
+        sys.exit(1)
+    if not _instructions_file.is_file():
+        print(f"Error: LOCKED_PROFILE '{LOCKED_PROFILE}' has no instructions.txt", file=sys.stderr)
+        sys.exit(1)
+
+_skip_dotenv = _env_flag("REACHY_MINI_SKIP_DOTENV", default=False)
+
+if _skip_dotenv:
+    logger.info("Skipping .env loading because REACHY_MINI_SKIP_DOTENV is set")
+else:
+    # Locate .env file (search upward from current working directory)
+    dotenv_path = find_dotenv(usecwd=True)
+
+    if dotenv_path:
+        # Load .env and override environment variables
+        load_dotenv(dotenv_path=dotenv_path, override=True)
+        logger.info(f"Configuration loaded from {dotenv_path}")
+    else:
+        logger.warning("No .env file found, using environment variables")
+
+
+class Config:
+    """Configuration class for the conversation app."""
+
+    # Required
+    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")  # The key is downloaded in console.py if needed
+
+    # Optional
+    MODEL_NAME = os.getenv("MODEL_NAME", "gpt-realtime")
+    HF_HOME = os.getenv("HF_HOME", "./cache")
+    LOCAL_VISION_MODEL = os.getenv("LOCAL_VISION_MODEL", "HuggingFaceTB/SmolVLM2-2.2B-Instruct")
+    HF_TOKEN = os.getenv("HF_TOKEN")  # Optional, falls back to hf auth login if not set
+
+    logger.debug(f"Model: {MODEL_NAME}, HF_HOME: {HF_HOME}, Vision Model: {LOCAL_VISION_MODEL}")
+
+    _profiles_directory_env = os.getenv("REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY")
+    PROFILES_DIRECTORY = (
+        Path(_profiles_directory_env) if _profiles_directory_env else Path(__file__).parent / "profiles"
+    )
+    _tools_directory_env = os.getenv("REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY")
+    TOOLS_DIRECTORY = Path(_tools_directory_env) if _tools_directory_env else None
+    AUTOLOAD_EXTERNAL_TOOLS = _env_flag("AUTOLOAD_EXTERNAL_TOOLS", default=False)
+    REACHY_MINI_CUSTOM_PROFILE = LOCKED_PROFILE or os.getenv("REACHY_MINI_CUSTOM_PROFILE")
+
+    logger.debug(f"Custom Profile: {REACHY_MINI_CUSTOM_PROFILE}")
+
+    def __init__(self) -> None:
+        """Initialize the configuration."""
+        if self.REACHY_MINI_CUSTOM_PROFILE and self.PROFILES_DIRECTORY != DEFAULT_PROFILES_DIRECTORY:
+            selected_profile_path = self.PROFILES_DIRECTORY / self.REACHY_MINI_CUSTOM_PROFILE
+            if not selected_profile_path.is_dir():
+                available_profiles = sorted(_collect_profile_names(self.PROFILES_DIRECTORY))
+                raise RuntimeError(
+                    "Config.__init__(): Selected profile "
+                    f"'{self.REACHY_MINI_CUSTOM_PROFILE}' was not found in external profiles root "
+                    f"{self.PROFILES_DIRECTORY}. "
+                    f"Available external profiles: {available_profiles}. "
+                    "Either set 'REACHY_MINI_CUSTOM_PROFILE' to one of the available external profiles "
+                    "or unset 'REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY' to use built-in profiles."
+                )
+
+        if self.PROFILES_DIRECTORY != DEFAULT_PROFILES_DIRECTORY:
+            external_profiles = _collect_profile_names(self.PROFILES_DIRECTORY)
+            internal_profiles = _collect_profile_names(DEFAULT_PROFILES_DIRECTORY)
+            _raise_on_name_collisions(
+                label="profile",
+                external_root=self.PROFILES_DIRECTORY,
+                internal_root=DEFAULT_PROFILES_DIRECTORY,
+                external_names=external_profiles,
+                internal_names=internal_profiles,
+            )
+
+        if self.TOOLS_DIRECTORY is not None:
+            builtin_tools_root = Path(__file__).parent / "tools"
+            external_tools = _collect_tool_module_names(self.TOOLS_DIRECTORY)
+            internal_tools = _collect_tool_module_names(builtin_tools_root)
+            _raise_on_name_collisions(
+                label="tool",
+                external_root=self.TOOLS_DIRECTORY,
+                internal_root=builtin_tools_root,
+                external_names=external_tools,
+                internal_names=internal_tools,
+            )
+
+        if self.PROFILES_DIRECTORY != DEFAULT_PROFILES_DIRECTORY:
+            logger.warning(
+                "Environment variable 'REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY' is set. "
+                "Profiles (instructions.txt, ...) will be loaded from %s.",
+                self.PROFILES_DIRECTORY,
+            )
+        else:
+            logger.info(
+                "'REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY' is not set. "
+                "Using built-in profiles from %s.",
+                DEFAULT_PROFILES_DIRECTORY,
+            )
+
+        if self.TOOLS_DIRECTORY is not None:
+            logger.warning(
+                "Environment variable 'REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY' is set. "
+                "External tools will be loaded from %s.",
+                self.TOOLS_DIRECTORY,
+            )
+        else:
+            logger.info(
+                "'REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY' is not set. "
+                "Using built-in shared tools only."
+            )
+
+
+config = Config()
+
+
+def set_custom_profile(profile: str | None) -> None:
+    """Update the selected custom profile at runtime and expose it via env.
+
+    This ensures modules that read `config` and code that inspects the
+    environment see a consistent value.
+    """
+    if LOCKED_PROFILE is not None:
+        return
+    try:
+        config.REACHY_MINI_CUSTOM_PROFILE = profile
+    except Exception:
+        pass
+    try:
+        import os as _os
+
+        if profile:
+            _os.environ["REACHY_MINI_CUSTOM_PROFILE"] = profile
+        else:
+            # Remove to reflect default
+            _os.environ.pop("REACHY_MINI_CUSTOM_PROFILE", None)
+    except Exception:
+        pass

src/hello_world/console.py

@@ -0,0 +1,502 @@
+"""Bidirectional local audio stream with optional settings UI.
+
+In headless mode, there is no Gradio UI. If the OpenAI API key is not
+available via environment/.env, we expose a minimal settings page via the
+Reachy Mini Apps settings server to let non-technical users enter it.
+
+The settings UI is served from this package's ``static/`` folder and offers a
+single password field to set ``OPENAI_API_KEY``. Once set, we persist it to the
+app instance's ``.env`` file (if available) and proceed to start streaming.
+"""
+
+import os
+import sys
+import time
+import asyncio
+import logging
+from typing import List, Optional
+from pathlib import Path
+
+from fastrtc import AdditionalOutputs, audio_to_float32
+from scipy.signal import resample
+
+from reachy_mini import ReachyMini
+from reachy_mini.media.media_manager import MediaBackend
+from hello_world.config import LOCKED_PROFILE, config
+from hello_world.openai_realtime import OpenaiRealtimeHandler
+from hello_world.headless_personality_ui import mount_personality_routes
+
+
+try:
+    # FastAPI is provided by the Reachy Mini Apps runtime
+    from fastapi import FastAPI, Response
+    from pydantic import BaseModel
+    from fastapi.responses import FileResponse, JSONResponse
+    from starlette.staticfiles import StaticFiles
+except Exception:  # pragma: no cover - only loaded when settings_app is used
+    FastAPI = object  # type: ignore
+    FileResponse = object  # type: ignore
+    JSONResponse = object  # type: ignore
+    StaticFiles = object  # type: ignore
+    BaseModel = object  # type: ignore
+
+
+logger = logging.getLogger(__name__)
+
+
+class LocalStream:
+    """LocalStream using Reachy Mini's recorder/player."""
+
+    def __init__(
+        self,
+        handler: OpenaiRealtimeHandler,
+        robot: ReachyMini,
+        *,
+        settings_app: Optional[FastAPI] = None,
+        instance_path: Optional[str] = None,
+    ):
+        """Initialize the stream with an OpenAI realtime handler and pipelines.
+
+        - ``settings_app``: the Reachy Mini Apps FastAPI to attach settings endpoints.
+        - ``instance_path``: directory where per-instance ``.env`` should be stored.
+        """
+        self.handler = handler
+        self._robot = robot
+        self._stop_event = asyncio.Event()
+        self._tasks: List[asyncio.Task[None]] = []
+        # Allow the handler to flush the player queue when appropriate.
+        self.handler._clear_queue = self.clear_audio_queue
+        self._settings_app: Optional[FastAPI] = settings_app
+        self._instance_path: Optional[str] = instance_path
+        self._settings_initialized = False
+        self._asyncio_loop = None
+
+    # ---- Settings UI (only when API key is missing) ----
+    def _read_env_lines(self, env_path: Path) -> list[str]:
+        """Load env file contents or a template as a list of lines."""
+        inst = env_path.parent
+        try:
+            if env_path.exists():
+                try:
+                    return env_path.read_text(encoding="utf-8").splitlines()
+                except Exception:
+                    return []
+            template_text = None
+            ex = inst / ".env.example"
+            if ex.exists():
+                try:
+                    template_text = ex.read_text(encoding="utf-8")
+                except Exception:
+                    template_text = None
+            if template_text is None:
+                try:
+                    cwd_example = Path.cwd() / ".env.example"
+                    if cwd_example.exists():
+                        template_text = cwd_example.read_text(encoding="utf-8")
+                except Exception:
+                    template_text = None
+            if template_text is None:
+                packaged = Path(__file__).parent / ".env.example"
+                if packaged.exists():
+                    try:
+                        template_text = packaged.read_text(encoding="utf-8")
+                    except Exception:
+                        template_text = None
+            return template_text.splitlines() if template_text else []
+        except Exception:
+            return []
+
+    def _persist_api_key(self, key: str) -> None:
+        """Persist API key to environment and instance ``.env`` if possible.
+
+        Behavior:
+        - Always sets ``OPENAI_API_KEY`` in process env and in-memory config.
+        - Writes/updates ``<instance_path>/.env``:
+          * If ``.env`` exists, replaces/append OPENAI_API_KEY line.
+          * Else, copies template from ``<instance_path>/.env.example`` when present,
+            otherwise falls back to the packaged template
+            ``hello_world/.env.example``.
+          * Ensures the resulting file contains the full template plus the key.
+        - Loads the written ``.env`` into the current process environment.
+        """
+        k = (key or "").strip()
+        if not k:
+            return
+        # Update live process env and config so consumers see it immediately
+        try:
+            os.environ["OPENAI_API_KEY"] = k
+        except Exception:  # best-effort
+            pass
+        try:
+            config.OPENAI_API_KEY = k
+        except Exception:
+            pass
+
+        if not self._instance_path:
+            return
+        try:
+            inst = Path(self._instance_path)
+            env_path = inst / ".env"
+            lines = self._read_env_lines(env_path)
+            replaced = False
+            for i, ln in enumerate(lines):
+                if ln.strip().startswith("OPENAI_API_KEY="):
+                    lines[i] = f"OPENAI_API_KEY={k}"
+                    replaced = True
+                    break
+            if not replaced:
+                lines.append(f"OPENAI_API_KEY={k}")
+            final_text = "\n".join(lines) + "\n"
+            env_path.write_text(final_text, encoding="utf-8")
+            logger.info("Persisted OPENAI_API_KEY to %s", env_path)
+
+            # Load the newly written .env into this process to ensure downstream imports see it
+            try:
+                from dotenv import load_dotenv
+
+                load_dotenv(dotenv_path=str(env_path), override=True)
+            except Exception:
+                pass
+        except Exception as e:
+            logger.warning("Failed to persist OPENAI_API_KEY: %s", e)
+
+    def _persist_personality(self, profile: Optional[str]) -> None:
+        """Persist the startup personality to the instance .env and config."""
+        if LOCKED_PROFILE is not None:
+            return
+        selection = (profile or "").strip() or None
+        try:
+            from hello_world.config import set_custom_profile
+
+            set_custom_profile(selection)
+        except Exception:
+            pass
+
+        if not self._instance_path:
+            return
+        try:
+            env_path = Path(self._instance_path) / ".env"
+            lines = self._read_env_lines(env_path)
+            replaced = False
+            for i, ln in enumerate(list(lines)):
+                if ln.strip().startswith("REACHY_MINI_CUSTOM_PROFILE="):
+                    if selection:
+                        lines[i] = f"REACHY_MINI_CUSTOM_PROFILE={selection}"
+                    else:
+                        lines.pop(i)
+                    replaced = True
+                    break
+            if selection and not replaced:
+                lines.append(f"REACHY_MINI_CUSTOM_PROFILE={selection}")
+            if selection is None and not env_path.exists():
+                return
+            final_text = "\n".join(lines) + "\n"
+            env_path.write_text(final_text, encoding="utf-8")
+            logger.info("Persisted startup personality to %s", env_path)
+            try:
+                from dotenv import load_dotenv
+
+                load_dotenv(dotenv_path=str(env_path), override=True)
+            except Exception:
+                pass
+        except Exception as e:
+            logger.warning("Failed to persist REACHY_MINI_CUSTOM_PROFILE: %s", e)
+
+    def _read_persisted_personality(self) -> Optional[str]:
+        """Read persisted startup personality from instance .env (if any)."""
+        if not self._instance_path:
+            return None
+        env_path = Path(self._instance_path) / ".env"
+        try:
+            if env_path.exists():
+                for ln in env_path.read_text(encoding="utf-8").splitlines():
+                    if ln.strip().startswith("REACHY_MINI_CUSTOM_PROFILE="):
+                        _, _, val = ln.partition("=")
+                        v = val.strip()
+                        return v or None
+        except Exception:
+            pass
+        return None
+
+    def _init_settings_ui_if_needed(self) -> None:
+        """Attach minimal settings UI to the settings app.
+
+        Always mounts the UI when a settings_app is provided so that users
+        see a confirmation message even if the API key is already configured.
+        """
+        if self._settings_initialized:
+            return
+        if self._settings_app is None:
+            return
+
+        static_dir = Path(__file__).parent / "static"
+        index_file = static_dir / "index.html"
+
+        if hasattr(self._settings_app, "mount"):
+            try:
+                # Serve /static/* assets
+                self._settings_app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+            except Exception:
+                pass
+
+        class ApiKeyPayload(BaseModel):
+            openai_api_key: str
+
+        # GET / -> index.html
+        @self._settings_app.get("/")
+        def _root() -> FileResponse:
+            return FileResponse(str(index_file))
+
+        # GET /favicon.ico -> optional, avoid noisy 404s on some browsers
+        @self._settings_app.get("/favicon.ico")
+        def _favicon() -> Response:
+            return Response(status_code=204)
+
+        # GET /status -> whether key is set
+        @self._settings_app.get("/status")
+        def _status() -> JSONResponse:
+            has_key = bool(config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip())
+            return JSONResponse({"has_key": has_key})
+
+        # GET /ready -> whether backend finished loading tools
+        @self._settings_app.get("/ready")
+        def _ready() -> JSONResponse:
+            try:
+                mod = sys.modules.get("hello_world.tools.core_tools")
+                ready = bool(getattr(mod, "_TOOLS_INITIALIZED", False)) if mod else False
+            except Exception:
+                ready = False
+            return JSONResponse({"ready": ready})
+
+        # POST /openai_api_key -> set/persist key
+        @self._settings_app.post("/openai_api_key")
+        def _set_key(payload: ApiKeyPayload) -> JSONResponse:
+            key = (payload.openai_api_key or "").strip()
+            if not key:
+                return JSONResponse({"ok": False, "error": "empty_key"}, status_code=400)
+            self._persist_api_key(key)
+            return JSONResponse({"ok": True})
+
+        # POST /validate_api_key -> validate key without persisting it
+        @self._settings_app.post("/validate_api_key")
+        async def _validate_key(payload: ApiKeyPayload) -> JSONResponse:
+            key = (payload.openai_api_key or "").strip()
+            if not key:
+                return JSONResponse({"valid": False, "error": "empty_key"}, status_code=400)
+
+            # Try to validate by checking if we can fetch the models
+            try:
+                import httpx
+
+                headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+                async with httpx.AsyncClient(timeout=10.0) as client:
+                    response = await client.get("https://api.openai.com/v1/models", headers=headers)
+                    if response.status_code == 200:
+                        return JSONResponse({"valid": True})
+                    elif response.status_code == 401:
+                        return JSONResponse({"valid": False, "error": "invalid_api_key"}, status_code=401)
+                    else:
+                        return JSONResponse(
+                            {"valid": False, "error": "validation_failed"}, status_code=response.status_code
+                        )
+            except Exception as e:
+                logger.warning(f"API key validation failed: {e}")
+                return JSONResponse({"valid": False, "error": "validation_error"}, status_code=500)
+
+        self._settings_initialized = True
+
+    def launch(self) -> None:
+        """Start the recorder/player and run the async processing loops.
+
+        If the OpenAI key is missing, expose a tiny settings UI via the
+        Reachy Mini settings server to collect it before starting streams.
+        """
+        self._stop_event.clear()
+
+        # Try to load an existing instance .env first (covers subsequent runs)
+        if self._instance_path:
+            try:
+                from dotenv import load_dotenv
+
+                from hello_world.config import set_custom_profile
+
+                env_path = Path(self._instance_path) / ".env"
+                if env_path.exists():
+                    load_dotenv(dotenv_path=str(env_path), override=True)
+                    # Update config with newly loaded values
+                    new_key = os.getenv("OPENAI_API_KEY", "").strip()
+                    if new_key:
+                        try:
+                            config.OPENAI_API_KEY = new_key
+                        except Exception:
+                            pass
+                    if LOCKED_PROFILE is None:
+                        new_profile = os.getenv("REACHY_MINI_CUSTOM_PROFILE")
+                        if new_profile is not None:
+                            try:
+                                set_custom_profile(new_profile.strip() or None)
+                            except Exception:
+                                pass  # Best-effort profile update
+            except Exception:
+                pass  # Instance .env loading is optional; continue with defaults
+
+        # If key is still missing, try to download one from HuggingFace
+        if not (config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip()):
+            logger.info("OPENAI_API_KEY not set, attempting to download from HuggingFace...")
+            try:
+                from gradio_client import Client
+                client = Client("HuggingFaceM4/gradium_setup", verbose=False)
+                key, status = client.predict(api_name="/claim_b_key")
+                if key and key.strip():
+                    logger.info("Successfully downloaded API key from HuggingFace")
+                    # Persist it immediately
+                    self._persist_api_key(key)
+            except Exception as e:
+                logger.warning(f"Failed to download API key from HuggingFace: {e}")
+
+        # Always expose settings UI if a settings app is available
+        # (do this AFTER loading/downloading the key so status endpoint sees the right value)
+        self._init_settings_ui_if_needed()
+
+        # If key is still missing -> wait until provided via the settings UI
+        if not (config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip()):
+            logger.warning("OPENAI_API_KEY not found. Open the app settings page to enter it.")
+            # Poll until the key becomes available (set via the settings UI)
+            try:
+                while not (config.OPENAI_API_KEY and str(config.OPENAI_API_KEY).strip()):
+                    time.sleep(0.2)
+            except KeyboardInterrupt:
+                logger.info("Interrupted while waiting for API key.")
+                return
+
+        # Start media after key is set/available
+        self._robot.media.start_recording()
+        self._robot.media.start_playing()
+        time.sleep(1)  # give some time to the pipelines to start
+
+        async def runner() -> None:
+            # Capture loop for cross-thread personality actions
+            loop = asyncio.get_running_loop()
+            self._asyncio_loop = loop  # type: ignore[assignment]
+            # Mount personality routes now that loop and handler are available
+            try:
+                if self._settings_app is not None:
+                    mount_personality_routes(
+                        self._settings_app,
+                        self.handler,
+                        lambda: self._asyncio_loop,
+                        persist_personality=self._persist_personality,
+                        get_persisted_personality=self._read_persisted_personality,
+                    )
+            except Exception:
+                pass
+            self._tasks = [
+                asyncio.create_task(self.handler.start_up(), name="openai-handler"),
+                asyncio.create_task(self.record_loop(), name="stream-record-loop"),
+                asyncio.create_task(self.play_loop(), name="stream-play-loop"),
+            ]
+            try:
+                await asyncio.gather(*self._tasks)
+            except asyncio.CancelledError:
+                logger.info("Tasks cancelled during shutdown")
+            finally:
+                # Ensure handler connection is closed
+                await self.handler.shutdown()
+
+        asyncio.run(runner())
+
+    def close(self) -> None:
+        """Stop the stream and underlying media pipelines.
+
+        This method:
+        - Stops audio recording and playback first
+        - Sets the stop event to signal async loops to terminate
+        - Cancels all pending async tasks (openai-handler, record-loop, play-loop)
+        """
+        logger.info("Stopping LocalStream...")
+
+        # Stop media pipelines FIRST before cancelling async tasks
+        # This ensures clean shutdown before PortAudio cleanup
+        try:
+            self._robot.media.stop_recording()
+        except Exception as e:
+            logger.debug(f"Error stopping recording (may already be stopped): {e}")
+
+        try:
+            self._robot.media.stop_playing()
+        except Exception as e:
+            logger.debug(f"Error stopping playback (may already be stopped): {e}")
+
+        # Now signal async loops to stop
+        self._stop_event.set()
+
+        # Cancel all running tasks
+        for task in self._tasks:
+            if not task.done():
+                task.cancel()
+
+    def clear_audio_queue(self) -> None:
+        """Flush the player's appsrc to drop any queued audio immediately."""
+        logger.info("User intervention: flushing player queue")
+        if self._robot.media.backend == MediaBackend.GSTREAMER:
+            # Directly flush gstreamer audio pipe
+            self._robot.media.audio.clear_player()
+        elif self._robot.media.backend == MediaBackend.DEFAULT or self._robot.media.backend == MediaBackend.DEFAULT_NO_VIDEO:
+            self._robot.media.audio.clear_output_buffer()
+        self.handler.output_queue = asyncio.Queue()
+
+    async def record_loop(self) -> None:
+        """Read mic frames from the recorder and forward them to the handler."""
+        input_sample_rate = self._robot.media.get_input_audio_samplerate()
+        logger.debug(f"Audio recording started at {input_sample_rate} Hz")
+
+        while not self._stop_event.is_set():
+            audio_frame = self._robot.media.get_audio_sample()
+            if audio_frame is not None:
+                await self.handler.receive((input_sample_rate, audio_frame))
+            await asyncio.sleep(0)  # avoid busy loop
+
+    async def play_loop(self) -> None:
+        """Fetch outputs from the handler: log text and play audio frames."""
+        while not self._stop_event.is_set():
+            handler_output = await self.handler.emit()
+
+            if isinstance(handler_output, AdditionalOutputs):
+                for msg in handler_output.args:
+                    content = msg.get("content", "")
+                    if isinstance(content, str):
+                        logger.info(
+                            "role=%s content=%s",
+                            msg.get("role"),
+                            content if len(content) < 500 else content[:500] + "…",
+                        )
+
+            elif isinstance(handler_output, tuple):
+                input_sample_rate, audio_data = handler_output
+                output_sample_rate = self._robot.media.get_output_audio_samplerate()
+
+                # Reshape if needed
+                if audio_data.ndim == 2:
+                    # Scipy channels last convention
+                    if audio_data.shape[1] > audio_data.shape[0]:
+                        audio_data = audio_data.T
+                    # Multiple channels -> Mono channel
+                    if audio_data.shape[1] > 1:
+                        audio_data = audio_data[:, 0]
+
+                # Cast if needed
+                audio_frame = audio_to_float32(audio_data)
+
+                # Resample if needed
+                if input_sample_rate != output_sample_rate:
+                    audio_frame = resample(
+                        audio_frame,
+                        int(len(audio_frame) * output_sample_rate / input_sample_rate),
+                    )
+
+                self._robot.media.push_audio_sample(audio_frame)
+
+            else:
+                logger.debug("Ignoring output type=%s", type(handler_output).__name__)
+
+            await asyncio.sleep(0)  # yield to event loop

src/hello_world/dance_emotion_moves.py

@@ -0,0 +1,154 @@
+"""Dance and emotion moves for the movement queue system.
+
+This module implements dance moves and emotions as Move objects that can be queued
+and executed sequentially by the MovementManager.
+"""
+
+from __future__ import annotations
+import logging
+from typing import Tuple
+
+import numpy as np
+from numpy.typing import NDArray
+
+from reachy_mini.motion.move import Move
+from reachy_mini.motion.recorded_move import RecordedMoves
+from reachy_mini_dances_library.dance_move import DanceMove
+
+
+logger = logging.getLogger(__name__)
+
+
+class DanceQueueMove(Move):  # type: ignore
+    """Wrapper for dance moves to work with the movement queue system."""
+
+    def __init__(self, move_name: str):
+        """Initialize a DanceQueueMove."""
+        self.dance_move = DanceMove(move_name)
+        self.move_name = move_name
+
+    @property
+    def duration(self) -> float:
+        """Duration property required by official Move interface."""
+        return float(self.dance_move.duration)
+
+    def evaluate(self, t: float) -> tuple[NDArray[np.float64] | None, NDArray[np.float64] | None, float | None]:
+        """Evaluate dance move at time t."""
+        try:
+            # Get the pose from the dance move
+            head_pose, antennas, body_yaw = self.dance_move.evaluate(t)
+
+            # Convert to numpy array if antennas is tuple and return in official Move format
+            if isinstance(antennas, tuple):
+                antennas = np.array([antennas[0], antennas[1]])
+
+            return (head_pose, antennas, body_yaw)
+
+        except Exception as e:
+            logger.error(f"Error evaluating dance move '{self.move_name}' at t={t}: {e}")
+            # Return neutral pose on error
+            from reachy_mini.utils import create_head_pose
+
+            neutral_head_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+            return (neutral_head_pose, np.array([0.0, 0.0], dtype=np.float64), 0.0)
+
+
+class EmotionQueueMove(Move):  # type: ignore
+    """Wrapper for emotion moves to work with the movement queue system."""
+
+    def __init__(self, emotion_name: str, recorded_moves: RecordedMoves):
+        """Initialize an EmotionQueueMove."""
+        self.emotion_move = recorded_moves.get(emotion_name)
+        self.emotion_name = emotion_name
+
+    @property
+    def duration(self) -> float:
+        """Duration property required by official Move interface."""
+        return float(self.emotion_move.duration)
+
+    def evaluate(self, t: float) -> tuple[NDArray[np.float64] | None, NDArray[np.float64] | None, float | None]:
+        """Evaluate emotion move at time t."""
+        try:
+            # Get the pose from the emotion move
+            head_pose, antennas, body_yaw = self.emotion_move.evaluate(t)
+
+            # Convert to numpy array if antennas is tuple and return in official Move format
+            if isinstance(antennas, tuple):
+                antennas = np.array([antennas[0], antennas[1]])
+
+            return (head_pose, antennas, body_yaw)
+
+        except Exception as e:
+            logger.error(f"Error evaluating emotion '{self.emotion_name}' at t={t}: {e}")
+            # Return neutral pose on error
+            from reachy_mini.utils import create_head_pose
+
+            neutral_head_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+            return (neutral_head_pose, np.array([0.0, 0.0], dtype=np.float64), 0.0)
+
+
+class GotoQueueMove(Move):  # type: ignore
+    """Wrapper for goto moves to work with the movement queue system."""
+
+    def __init__(
+        self,
+        target_head_pose: NDArray[np.float32],
+        start_head_pose: NDArray[np.float32] | None = None,
+        target_antennas: Tuple[float, float] = (0, 0),
+        start_antennas: Tuple[float, float] | None = None,
+        target_body_yaw: float = 0,
+        start_body_yaw: float | None = None,
+        duration: float = 1.0,
+    ):
+        """Initialize a GotoQueueMove."""
+        self._duration = duration
+        self.target_head_pose = target_head_pose
+        self.start_head_pose = start_head_pose
+        self.target_antennas = target_antennas
+        self.start_antennas = start_antennas or (0, 0)
+        self.target_body_yaw = target_body_yaw
+        self.start_body_yaw = start_body_yaw or 0
+
+    @property
+    def duration(self) -> float:
+        """Duration property required by official Move interface."""
+        return self._duration
+
+    def evaluate(self, t: float) -> tuple[NDArray[np.float64] | None, NDArray[np.float64] | None, float | None]:
+        """Evaluate goto move at time t using linear interpolation."""
+        try:
+            from reachy_mini.utils import create_head_pose
+            from reachy_mini.utils.interpolation import linear_pose_interpolation
+
+            # Clamp t to [0, 1] for interpolation
+            t_clamped = max(0, min(1, t / self.duration))
+
+            # Use start pose if available, otherwise neutral
+            if self.start_head_pose is not None:
+                start_pose = self.start_head_pose
+            else:
+                start_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+
+            # Interpolate head pose
+            head_pose = linear_pose_interpolation(start_pose, self.target_head_pose, t_clamped)
+
+            # Interpolate antennas - return as numpy array
+            antennas = np.array(
+                [
+                    self.start_antennas[0] + (self.target_antennas[0] - self.start_antennas[0]) * t_clamped,
+                    self.start_antennas[1] + (self.target_antennas[1] - self.start_antennas[1]) * t_clamped,
+                ],
+                dtype=np.float64,
+            )
+
+            # Interpolate body yaw
+            body_yaw = self.start_body_yaw + (self.target_body_yaw - self.start_body_yaw) * t_clamped
+
+            return (head_pose, antennas, body_yaw)
+
+        except Exception as e:
+            logger.error(f"Error evaluating goto move at t={t}: {e}")
+            # Return target pose on error - convert to float64
+            target_head_pose_f64 = self.target_head_pose.astype(np.float64)
+            target_antennas_array = np.array([self.target_antennas[0], self.target_antennas[1]], dtype=np.float64)
+            return (target_head_pose_f64, target_antennas_array, self.target_body_yaw)

src/hello_world/gradio_personality.py

@@ -0,0 +1,316 @@
+"""Gradio personality UI components and wiring.
+
+This module encapsulates the UI elements and logic related to managing
+conversation "personalities" (profiles) so that `main.py` stays lean.
+"""
+
+from __future__ import annotations
+from typing import Any
+from pathlib import Path
+
+import gradio as gr
+
+from .config import LOCKED_PROFILE, config
+
+
+class PersonalityUI:
+    """Container for personality-related Gradio components."""
+
+    def __init__(self) -> None:
+        """Initialize the PersonalityUI instance."""
+        # Constants and paths
+        self.DEFAULT_OPTION = "(built-in default)"
+        self._profiles_root = Path(__file__).parent / "profiles"
+        self._tools_dir = Path(__file__).parent / "tools"
+        self._prompts_dir = Path(__file__).parent / "prompts"
+
+        # Components (initialized in create_components)
+        self.personalities_dropdown: gr.Dropdown
+        self.apply_btn: gr.Button
+        self.status_md: gr.Markdown
+        self.preview_md: gr.Markdown
+        self.person_name_tb: gr.Textbox
+        self.person_instr_ta: gr.TextArea
+        self.tools_txt_ta: gr.TextArea
+        self.voice_dropdown: gr.Dropdown
+        self.new_personality_btn: gr.Button
+        self.available_tools_cg: gr.CheckboxGroup
+        self.save_btn: gr.Button
+
+    # ---------- Filesystem helpers ----------
+    def _list_personalities(self) -> list[str]:
+        names: list[str] = []
+        try:
+            if self._profiles_root.exists():
+                for p in sorted(self._profiles_root.iterdir()):
+                    if p.name == "user_personalities":
+                        continue
+                    if p.is_dir() and (p / "instructions.txt").exists():
+                        names.append(p.name)
+                user_dir = self._profiles_root / "user_personalities"
+                if user_dir.exists():
+                    for p in sorted(user_dir.iterdir()):
+                        if p.is_dir() and (p / "instructions.txt").exists():
+                            names.append(f"user_personalities/{p.name}")
+        except Exception:
+            pass
+        return names
+
+    def _resolve_profile_dir(self, selection: str) -> Path:
+        return self._profiles_root / selection
+
+    def _read_instructions_for(self, name: str) -> str:
+        try:
+            if name == self.DEFAULT_OPTION:
+                default_file = self._prompts_dir / "default_prompt.txt"
+                if default_file.exists():
+                    return default_file.read_text(encoding="utf-8").strip()
+                return ""
+            target = self._resolve_profile_dir(name) / "instructions.txt"
+            if target.exists():
+                return target.read_text(encoding="utf-8").strip()
+            return ""
+        except Exception as e:
+            return f"Could not load instructions: {e}"
+
+    @staticmethod
+    def _sanitize_name(name: str) -> str:
+        import re
+
+        s = name.strip()
+        s = re.sub(r"\s+", "_", s)
+        s = re.sub(r"[^a-zA-Z0-9_-]", "", s)
+        return s
+
+    # ---------- Public API ----------
+    def create_components(self) -> None:
+        """Instantiate Gradio components for the personality UI."""
+        if LOCKED_PROFILE is not None:
+            is_locked = True
+            current_value: str = LOCKED_PROFILE
+            dropdown_label = "Select personality (locked)"
+            dropdown_choices: list[str] = [LOCKED_PROFILE]
+        else:
+            is_locked = False
+            current_value = config.REACHY_MINI_CUSTOM_PROFILE or self.DEFAULT_OPTION
+            dropdown_label = "Select personality"
+            dropdown_choices = [self.DEFAULT_OPTION, *(self._list_personalities())]
+
+        self.personalities_dropdown = gr.Dropdown(
+            label=dropdown_label,
+            choices=dropdown_choices,
+            value=current_value,
+            interactive=not is_locked,
+        )
+        self.apply_btn = gr.Button("Apply personality", interactive=not is_locked)
+        self.status_md = gr.Markdown(visible=True)
+        self.preview_md = gr.Markdown(value=self._read_instructions_for(current_value))
+        self.person_name_tb = gr.Textbox(label="Personality name", interactive=not is_locked)
+        self.person_instr_ta = gr.TextArea(label="Personality instructions", lines=10, interactive=not is_locked)
+        self.tools_txt_ta = gr.TextArea(label="tools.txt", lines=10, interactive=not is_locked)
+        self.voice_dropdown = gr.Dropdown(label="Voice", choices=["cedar"], value="cedar", interactive=not is_locked)
+        self.new_personality_btn = gr.Button("New personality", interactive=not is_locked)
+        self.available_tools_cg = gr.CheckboxGroup(label="Available tools (helper)", choices=[], value=[], interactive=not is_locked)
+        self.save_btn = gr.Button("Save personality (instructions + tools)", interactive=not is_locked)
+
+    def additional_inputs_ordered(self) -> list[Any]:
+        """Return the additional inputs in the expected order for Stream."""
+        return [
+            self.personalities_dropdown,
+            self.apply_btn,
+            self.new_personality_btn,
+            self.status_md,
+            self.preview_md,
+            self.person_name_tb,
+            self.person_instr_ta,
+            self.tools_txt_ta,
+            self.voice_dropdown,
+            self.available_tools_cg,
+            self.save_btn,
+        ]
+
+    # ---------- Event wiring ----------
+    def wire_events(self, handler: Any, blocks: gr.Blocks) -> None:
+        """Attach event handlers to components within a Blocks context."""
+
+        async def _apply_personality(selected: str) -> tuple[str, str]:
+            if LOCKED_PROFILE is not None and selected != LOCKED_PROFILE:
+                return (
+                    f"Profile is locked to '{LOCKED_PROFILE}'. Cannot change personality.",
+                    self._read_instructions_for(LOCKED_PROFILE),
+                )
+            profile = None if selected == self.DEFAULT_OPTION else selected
+            status = await handler.apply_personality(profile)
+            preview = self._read_instructions_for(selected)
+            return status, preview
+
+        def _read_voice_for(name: str) -> str:
+            try:
+                if name == self.DEFAULT_OPTION:
+                    return "cedar"
+                vf = self._resolve_profile_dir(name) / "voice.txt"
+                if vf.exists():
+                    v = vf.read_text(encoding="utf-8").strip()
+                    return v or "cedar"
+            except Exception:
+                pass
+            return "cedar"
+
+        async def _fetch_voices(selected: str) -> dict[str, Any]:
+            try:
+                voices = await handler.get_available_voices()
+                current = _read_voice_for(selected)
+                if current not in voices:
+                    current = "cedar"
+                return gr.update(choices=voices, value=current)
+            except Exception:
+                return gr.update(choices=["cedar"], value="cedar")
+
+        def _available_tools_for(selected: str) -> tuple[list[str], list[str]]:
+            shared: list[str] = []
+            try:
+                for py in self._tools_dir.glob("*.py"):
+                    if py.stem in {"__init__", "core_tools"}:
+                        continue
+                    shared.append(py.stem)
+            except Exception:
+                pass
+            local: list[str] = []
+            try:
+                if selected != self.DEFAULT_OPTION:
+                    for py in (self._profiles_root / selected).glob("*.py"):
+                        local.append(py.stem)
+            except Exception:
+                pass
+            return sorted(shared), sorted(local)
+
+        def _parse_enabled_tools(text: str) -> list[str]:
+            enabled: list[str] = []
+            for line in text.splitlines():
+                s = line.strip()
+                if not s or s.startswith("#"):
+                    continue
+                enabled.append(s)
+            return enabled
+
+        def _load_profile_for_edit(selected: str) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], str]:
+            instr = self._read_instructions_for(selected)
+            tools_txt = ""
+            if selected != self.DEFAULT_OPTION:
+                tp = self._resolve_profile_dir(selected) / "tools.txt"
+                if tp.exists():
+                    tools_txt = tp.read_text(encoding="utf-8")
+            shared, local = _available_tools_for(selected)
+            all_tools = sorted(set(shared + local))
+            enabled = _parse_enabled_tools(tools_txt)
+            status_text = f"Loaded profile '{selected}'."
+            return (
+                gr.update(value=instr),
+                gr.update(value=tools_txt),
+                gr.update(choices=all_tools, value=enabled),
+                status_text,
+            )
+
+        def _new_personality() -> tuple[
+            dict[str, Any], dict[str, Any], dict[str, Any], dict[str, Any], str, dict[str, Any]
+        ]:
+            try:
+                # Prefill with hints
+                instr_val = """# Write your instructions here\n# e.g., Keep responses concise and friendly."""
+                tools_txt_val = "# tools enabled for this profile\n"
+                return (
+                    gr.update(value=""),
+                    gr.update(value=instr_val),
+                    gr.update(value=tools_txt_val),
+                    gr.update(choices=sorted(_available_tools_for(self.DEFAULT_OPTION)[0]), value=[]),
+                    "Fill in a name, instructions and (optional) tools, then Save.",
+                    gr.update(value="cedar"),
+                )
+            except Exception:
+                return (
+                    gr.update(),
+                    gr.update(),
+                    gr.update(),
+                    gr.update(),
+                    "Failed to initialize new personality.",
+                    gr.update(),
+                )
+
+        def _save_personality(
+            name: str, instructions: str, tools_text: str, voice: str
+        ) -> tuple[dict[str, Any], dict[str, Any], str]:
+            name_s = self._sanitize_name(name)
+            if not name_s:
+                return gr.update(), gr.update(), "Please enter a valid name."
+            try:
+                target_dir = self._profiles_root / "user_personalities" / name_s
+                target_dir.mkdir(parents=True, exist_ok=True)
+                (target_dir / "instructions.txt").write_text(instructions.strip() + "\n", encoding="utf-8")
+                (target_dir / "tools.txt").write_text(tools_text.strip() + "\n", encoding="utf-8")
+                (target_dir / "voice.txt").write_text((voice or "cedar").strip() + "\n", encoding="utf-8")
+
+                choices = self._list_personalities()
+                value = f"user_personalities/{name_s}"
+                if value not in choices:
+                    choices.append(value)
+                return (
+                    gr.update(choices=[self.DEFAULT_OPTION, *sorted(choices)], value=value),
+                    gr.update(value=instructions),
+                    f"Saved personality '{name_s}'.",
+                )
+            except Exception as e:
+                return gr.update(), gr.update(), f"Failed to save personality: {e}"
+
+        def _sync_tools_from_checks(selected: list[str], current_text: str) -> dict[str, Any]:
+            comments = [ln for ln in current_text.splitlines() if ln.strip().startswith("#")]
+            body = "\n".join(selected)
+            out = ("\n".join(comments) + ("\n" if comments else "") + body).strip() + "\n"
+            return gr.update(value=out)
+
+        with blocks:
+            self.apply_btn.click(
+                fn=_apply_personality,
+                inputs=[self.personalities_dropdown],
+                outputs=[self.status_md, self.preview_md],
+            )
+
+            self.personalities_dropdown.change(
+                fn=_load_profile_for_edit,
+                inputs=[self.personalities_dropdown],
+                outputs=[self.person_instr_ta, self.tools_txt_ta, self.available_tools_cg, self.status_md],
+            )
+
+            blocks.load(
+                fn=_fetch_voices,
+                inputs=[self.personalities_dropdown],
+                outputs=[self.voice_dropdown],
+            )
+
+            self.available_tools_cg.change(
+                fn=_sync_tools_from_checks,
+                inputs=[self.available_tools_cg, self.tools_txt_ta],
+                outputs=[self.tools_txt_ta],
+            )
+
+            self.new_personality_btn.click(
+                fn=_new_personality,
+                inputs=[],
+                outputs=[
+                    self.person_name_tb,
+                    self.person_instr_ta,
+                    self.tools_txt_ta,
+                    self.available_tools_cg,
+                    self.status_md,
+                    self.voice_dropdown,
+                ],
+            )
+
+            self.save_btn.click(
+                fn=_save_personality,
+                inputs=[self.person_name_tb, self.person_instr_ta, self.tools_txt_ta, self.voice_dropdown],
+                outputs=[self.personalities_dropdown, self.person_instr_ta, self.status_md],
+            ).then(
+                fn=_apply_personality,
+                inputs=[self.personalities_dropdown],
+                outputs=[self.status_md, self.preview_md],
+            )

src/hello_world/headless_personality.py

@@ -0,0 +1,102 @@
+"""Headless personality management (console-based).
+
+Provides an interactive CLI to browse, preview, apply, create and edit
+"personalities" (profiles) when running without Gradio.
+
+This module is intentionally not shared with the Gradio implementation to
+avoid coupling and keep responsibilities clear for headless mode.
+"""
+
+from __future__ import annotations
+from typing import List
+from pathlib import Path
+
+
+DEFAULT_OPTION = "(built-in default)"
+
+
+def _profiles_root() -> Path:
+    return Path(__file__).parent / "profiles"
+
+
+def _prompts_dir() -> Path:
+    return Path(__file__).parent / "prompts"
+
+
+def _tools_dir() -> Path:
+    return Path(__file__).parent / "tools"
+
+
+def _sanitize_name(name: str) -> str:
+    import re
+
+    s = name.strip()
+    s = re.sub(r"\s+", "_", s)
+    s = re.sub(r"[^a-zA-Z0-9_-]", "", s)
+    return s
+
+
+def list_personalities() -> List[str]:
+    """List available personality profile names."""
+    names: List[str] = []
+    root = _profiles_root()
+    try:
+        if root.exists():
+            for p in sorted(root.iterdir()):
+                if p.name == "user_personalities":
+                    continue
+                if p.is_dir() and (p / "instructions.txt").exists():
+                    names.append(p.name)
+        udir = root / "user_personalities"
+        if udir.exists():
+            for p in sorted(udir.iterdir()):
+                if p.is_dir() and (p / "instructions.txt").exists():
+                    names.append(f"user_personalities/{p.name}")
+    except Exception:
+        pass
+    return names
+
+
+def resolve_profile_dir(selection: str) -> Path:
+    """Resolve the directory path for the given profile selection."""
+    return _profiles_root() / selection
+
+
+def read_instructions_for(name: str) -> str:
+    """Read the instructions.txt content for the given profile name."""
+    try:
+        if name == DEFAULT_OPTION:
+            df = _prompts_dir() / "default_prompt.txt"
+            return df.read_text(encoding="utf-8").strip() if df.exists() else ""
+        target = resolve_profile_dir(name) / "instructions.txt"
+        return target.read_text(encoding="utf-8").strip() if target.exists() else ""
+    except Exception as e:
+        return f"Could not load instructions: {e}"
+
+
+def available_tools_for(selected: str) -> List[str]:
+    """List available tool modules for the given profile selection."""
+    shared: List[str] = []
+    try:
+        for py in _tools_dir().glob("*.py"):
+            if py.stem in {"__init__", "core_tools"}:
+                continue
+            shared.append(py.stem)
+    except Exception:
+        pass
+    local: List[str] = []
+    try:
+        if selected != DEFAULT_OPTION:
+            for py in resolve_profile_dir(selected).glob("*.py"):
+                local.append(py.stem)
+    except Exception:
+        pass
+    return sorted(set(shared + local))
+
+
+def _write_profile(name_s: str, instructions: str, tools_text: str, voice: str = "cedar") -> None:
+    target_dir = _profiles_root() / "user_personalities" / name_s
+    target_dir.mkdir(parents=True, exist_ok=True)
+    (target_dir / "instructions.txt").write_text(instructions.strip() + "\n", encoding="utf-8")
+    (target_dir / "tools.txt").write_text((tools_text or "").strip() + "\n", encoding="utf-8")
+    (target_dir / "voice.txt").write_text((voice or "cedar").strip() + "\n", encoding="utf-8")

src/hello_world/headless_personality_ui.py

@@ -0,0 +1,287 @@
+"""Settings UI routes for headless personality management.
+
+Exposes REST endpoints on the provided FastAPI settings app. The
+implementation schedules backend actions (apply personality, fetch voices)
+onto the running LocalStream asyncio loop using the supplied get_loop
+callable to avoid cross-thread issues.
+"""
+
+from __future__ import annotations
+import asyncio
+import logging
+from typing import Any, Callable, Optional
+
+from fastapi import FastAPI
+
+from .config import LOCKED_PROFILE, config
+from .openai_realtime import OpenaiRealtimeHandler
+from .headless_personality import (
+    DEFAULT_OPTION,
+    _sanitize_name,
+    _write_profile,
+    list_personalities,
+    available_tools_for,
+    resolve_profile_dir,
+    read_instructions_for,
+)
+
+
+def mount_personality_routes(
+    app: FastAPI,
+    handler: OpenaiRealtimeHandler,
+    get_loop: Callable[[], asyncio.AbstractEventLoop | None],
+    *,
+    persist_personality: Callable[[Optional[str]], None] | None = None,
+    get_persisted_personality: Callable[[], Optional[str]] | None = None,
+) -> None:
+    """Register personality management endpoints on a FastAPI app."""
+    try:
+        from fastapi import Request
+        from pydantic import BaseModel
+        from fastapi.responses import JSONResponse
+    except Exception:  # pragma: no cover - only when settings app not available
+        return
+
+    class SavePayload(BaseModel):
+        name: str
+        instructions: str
+        tools_text: str
+        voice: Optional[str] = "cedar"
+
+    class ApplyPayload(BaseModel):
+        name: str
+        persist: Optional[bool] = False
+
+    def _startup_choice() -> Any:
+        """Return the persisted startup personality or default."""
+        try:
+            if get_persisted_personality is not None:
+                stored = get_persisted_personality()
+                if stored:
+                    return stored
+            env_val = getattr(config, "REACHY_MINI_CUSTOM_PROFILE", None)
+            if env_val:
+                return env_val
+        except Exception:
+            pass
+        return DEFAULT_OPTION
+
+    def _current_choice() -> str:
+        try:
+            cur = getattr(config, "REACHY_MINI_CUSTOM_PROFILE", None)
+            return cur or DEFAULT_OPTION
+        except Exception:
+            return DEFAULT_OPTION
+
+    @app.get("/personalities")
+    def _list() -> dict:  # type: ignore
+        choices = [DEFAULT_OPTION, *list_personalities()]
+        return {
+            "choices": choices,
+            "current": _current_choice(),
+            "startup": _startup_choice(),
+            "locked": LOCKED_PROFILE is not None,
+            "locked_to": LOCKED_PROFILE,
+        }
+
+    @app.get("/personalities/load")
+    def _load(name: str) -> dict:  # type: ignore
+        instr = read_instructions_for(name)
+        tools_txt = ""
+        voice = "cedar"
+        if name != DEFAULT_OPTION:
+            pdir = resolve_profile_dir(name)
+            tp = pdir / "tools.txt"
+            if tp.exists():
+                tools_txt = tp.read_text(encoding="utf-8")
+            vf = pdir / "voice.txt"
+            if vf.exists():
+                v = vf.read_text(encoding="utf-8").strip()
+                voice = v or "cedar"
+        avail = available_tools_for(name)
+        enabled = [ln.strip() for ln in tools_txt.splitlines() if ln.strip() and not ln.strip().startswith("#")]
+        return {
+            "instructions": instr,
+            "tools_text": tools_txt,
+            "voice": voice,
+            "available_tools": avail,
+            "enabled_tools": enabled,
+        }
+
+    @app.post("/personalities/save")
+    async def _save(request: Request) -> dict:  # type: ignore
+        # Accept raw JSON only to avoid validation-related 422s
+        try:
+            raw = await request.json()
+        except Exception:
+            raw = {}
+        name = str(raw.get("name", ""))
+        instructions = str(raw.get("instructions", ""))
+        tools_text = str(raw.get("tools_text", ""))
+        voice = str(raw.get("voice", "cedar")) if raw.get("voice") is not None else "cedar"
+
+        name_s = _sanitize_name(name)
+        if not name_s:
+            return JSONResponse({"ok": False, "error": "invalid_name"}, status_code=400)  # type: ignore
+        try:
+            logger.info(
+                "Headless save: name=%r voice=%r instr_len=%d tools_len=%d",
+                name_s,
+                voice,
+                len(instructions),
+                len(tools_text),
+            )
+            _write_profile(name_s, instructions, tools_text, voice or "cedar")
+            value = f"user_personalities/{name_s}"
+            choices = [DEFAULT_OPTION, *list_personalities()]
+            return {"ok": True, "value": value, "choices": choices}
+        except Exception as e:
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=500)  # type: ignore
+
+    @app.post("/personalities/save_raw")
+    async def _save_raw(
+        request: Request,
+        name: Optional[str] = None,
+        instructions: Optional[str] = None,
+        tools_text: Optional[str] = None,
+        voice: Optional[str] = None,
+    ) -> dict:  # type: ignore
+        # Accept query params, form-encoded, or raw JSON
+        data = {"name": name, "instructions": instructions, "tools_text": tools_text, "voice": voice}
+        # Prefer form if present
+        try:
+            form = await request.form()
+            for k in ("name", "instructions", "tools_text", "voice"):
+                if k in form and form[k] is not None:
+                    data[k] = str(form[k])
+        except Exception:
+            pass
+        # Try JSON
+        try:
+            raw = await request.json()
+            if isinstance(raw, dict):
+                for k in ("name", "instructions", "tools_text", "voice"):
+                    if raw.get(k) is not None:
+                        data[k] = str(raw.get(k))
+        except Exception:
+            pass
+
+        name_s = _sanitize_name(str(data.get("name") or ""))
+        if not name_s:
+            return JSONResponse({"ok": False, "error": "invalid_name"}, status_code=400)  # type: ignore
+        instr = str(data.get("instructions") or "")
+        tools = str(data.get("tools_text") or "")
+        v = str(data.get("voice") or "cedar")
+        try:
+            logger.info(
+                "Headless save_raw: name=%r voice=%r instr_len=%d tools_len=%d", name_s, v, len(instr), len(tools)
+            )
+            _write_profile(name_s, instr, tools, v)
+            value = f"user_personalities/{name_s}"
+            choices = [DEFAULT_OPTION, *list_personalities()]
+            return {"ok": True, "value": value, "choices": choices}
+        except Exception as e:
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=500)  # type: ignore
+
+    @app.get("/personalities/save_raw")
+    async def _save_raw_get(name: str, instructions: str = "", tools_text: str = "", voice: str = "cedar") -> dict:  # type: ignore
+        name_s = _sanitize_name(name)
+        if not name_s:
+            return JSONResponse({"ok": False, "error": "invalid_name"}, status_code=400)  # type: ignore
+        try:
+            logger.info(
+                "Headless save_raw(GET): name=%r voice=%r instr_len=%d tools_len=%d",
+                name_s,
+                voice,
+                len(instructions),
+                len(tools_text),
+            )
+            _write_profile(name_s, instructions, tools_text, voice or "cedar")
+            value = f"user_personalities/{name_s}"
+            choices = [DEFAULT_OPTION, *list_personalities()]
+            return {"ok": True, "value": value, "choices": choices}
+        except Exception as e:
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=500)  # type: ignore
+
+    logger = logging.getLogger(__name__)
+
+    @app.post("/personalities/apply")
+    async def _apply(
+        payload: ApplyPayload | None = None,
+        name: str | None = None,
+        persist: Optional[bool] = None,
+        request: Optional[Request] = None,
+    ) -> dict:  # type: ignore
+        if LOCKED_PROFILE is not None:
+            return JSONResponse(
+                {"ok": False, "error": "profile_locked", "locked_to": LOCKED_PROFILE},
+                status_code=403,
+            )  # type: ignore
+        loop = get_loop()
+        if loop is None:
+            return JSONResponse({"ok": False, "error": "loop_unavailable"}, status_code=503)  # type: ignore
+
+        # Accept both JSON payload and query param for convenience
+        sel_name: Optional[str] = None
+        persist_flag = bool(persist) if persist is not None else False
+        if payload and getattr(payload, "name", None):
+            sel_name = payload.name
+            persist_flag = bool(getattr(payload, "persist", False))
+        elif name:
+            sel_name = name
+        elif request is not None:
+            try:
+                body = await request.json()
+                if isinstance(body, dict) and body.get("name"):
+                    sel_name = str(body.get("name"))
+                if isinstance(body, dict) and "persist" in body:
+                    persist_flag = bool(body.get("persist"))
+            except Exception:
+                sel_name = None
+        if request is not None:
+            try:
+                q_persist = request.query_params.get("persist")
+                if q_persist is not None:
+                    persist_flag = str(q_persist).lower() in {"1", "true", "yes", "on"}
+            except Exception:
+                pass
+        if not sel_name:
+            sel_name = DEFAULT_OPTION
+
+        async def _do_apply() -> str:
+            sel = None if sel_name == DEFAULT_OPTION else sel_name
+            status = await handler.apply_personality(sel)
+            return status
+
+        try:
+            logger.info("Headless apply: requested name=%r", sel_name)
+            fut = asyncio.run_coroutine_threadsafe(_do_apply(), loop)
+            status = fut.result(timeout=10)
+            persisted_choice = _startup_choice()
+            if persist_flag and persist_personality is not None:
+                try:
+                    persist_personality(None if sel_name == DEFAULT_OPTION else sel_name)
+                    persisted_choice = _startup_choice()
+                except Exception as e:
+                    logger.warning("Failed to persist startup personality: %s", e)
+            return {"ok": True, "status": status, "startup": persisted_choice}
+        except Exception as e:
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=500)  # type: ignore
+
+    @app.get("/voices")
+    async def _voices() -> list[str]:
+        loop = get_loop()
+        if loop is None:
+            return ["cedar"]
+
+        async def _get_v() -> list[str]:
+            try:
+                return await handler.get_available_voices()
+            except Exception:
+                return ["cedar"]
+
+        try:
+            fut = asyncio.run_coroutine_threadsafe(_get_v(), loop)
+            return fut.result(timeout=10)
+        except Exception:
+            return ["cedar"]

src/hello_world/main.py

@@ -0,0 +1,260 @@
+"""Entrypoint for the Reachy Mini conversation app."""
+
+import os
+import sys
+import time
+import asyncio
+import argparse
+import threading
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+from fastapi import FastAPI
+from fastrtc import Stream
+from gradio.utils import get_space
+
+from reachy_mini import ReachyMini, ReachyMiniApp
+from hello_world.utils import (
+    parse_args,
+    setup_logger,
+    handle_vision_stuff,
+    log_connection_troubleshooting,
+)
+
+
+def update_chatbot(chatbot: List[Dict[str, Any]], response: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Update the chatbot with AdditionalOutputs."""
+    chatbot.append(response)
+    return chatbot
+
+
+def main() -> None:
+    """Entrypoint for the Reachy Mini conversation app."""
+    args, _ = parse_args()
+    run(args)
+
+
+def run(
+    args: argparse.Namespace,
+    robot: ReachyMini = None,
+    app_stop_event: Optional[threading.Event] = None,
+    settings_app: Optional[FastAPI] = None,
+    instance_path: Optional[str] = None,
+) -> None:
+    """Run the Reachy Mini conversation app."""
+    # Putting these dependencies here makes the dashboard faster to load when the conversation app is installed
+    from hello_world.moves import MovementManager
+    from hello_world.console import LocalStream
+    from hello_world.openai_realtime import OpenaiRealtimeHandler
+    from hello_world.tools.core_tools import ToolDependencies
+    from hello_world.audio.head_wobbler import HeadWobbler
+
+    logger = setup_logger(args.debug)
+    logger.info("Starting Reachy Mini Conversation App")
+
+    if args.no_camera and args.head_tracker is not None:
+        logger.warning(
+            "Head tracking disabled: --no-camera flag is set. "
+            "Remove --no-camera to enable head tracking."
+        )
+
+    if robot is None:
+        try:
+            robot_kwargs = {}
+            if args.robot_name is not None:
+                robot_kwargs["robot_name"] = args.robot_name
+
+            logger.info("Initializing ReachyMini (SDK will auto-detect appropriate backend)")
+            robot = ReachyMini(**robot_kwargs)
+
+        except TimeoutError as e:
+            logger.error(
+                "Connection timeout: Failed to connect to Reachy Mini daemon. "
+                f"Details: {e}"
+            )
+            log_connection_troubleshooting(logger, args.robot_name)
+            sys.exit(1)
+
+        except ConnectionError as e:
+            logger.error(
+                "Connection failed: Unable to establish connection to Reachy Mini. "
+                f"Details: {e}"
+            )
+            log_connection_troubleshooting(logger, args.robot_name)
+            sys.exit(1)
+
+        except Exception as e:
+            logger.error(
+                f"Unexpected error during robot initialization: {type(e).__name__}: {e}"
+            )
+            logger.error("Please check your configuration and try again.")
+            sys.exit(1)
+
+    # Auto-enable Gradio in simulation mode (both MuJoCo for daemon and mockup-sim for desktop app)
+    status = robot.client.get_status()
+    if isinstance(status, dict):
+        simulation_enabled = status.get("simulation_enabled", False)
+        mockup_sim_enabled = status.get("mockup_sim_enabled", False)
+    else:
+        simulation_enabled = getattr(status, "simulation_enabled", False)
+        mockup_sim_enabled = getattr(status, "mockup_sim_enabled", False)
+
+    is_simulation = simulation_enabled or mockup_sim_enabled
+
+    if is_simulation and not args.gradio:
+        logger.info("Simulation mode detected. Automatically enabling gradio flag.")
+        args.gradio = True
+
+    camera_worker, _, vision_manager = handle_vision_stuff(args, robot)
+
+    movement_manager = MovementManager(
+        current_robot=robot,
+        camera_worker=camera_worker,
+    )
+
+    head_wobbler = HeadWobbler(set_speech_offsets=movement_manager.set_speech_offsets)
+
+    deps = ToolDependencies(
+        reachy_mini=robot,
+        movement_manager=movement_manager,
+        camera_worker=camera_worker,
+        vision_manager=vision_manager,
+        head_wobbler=head_wobbler,
+    )
+    current_file_path = os.path.dirname(os.path.abspath(__file__))
+    logger.debug(f"Current file absolute path: {current_file_path}")
+    chatbot = gr.Chatbot(
+        type="messages",
+        resizable=True,
+        avatar_images=(
+            os.path.join(current_file_path, "images", "user_avatar.png"),
+            os.path.join(current_file_path, "images", "reachymini_avatar.png"),
+        ),
+    )
+    logger.debug(f"Chatbot avatar images: {chatbot.avatar_images}")
+
+    handler = OpenaiRealtimeHandler(deps, gradio_mode=args.gradio, instance_path=instance_path)
+
+    stream_manager: gr.Blocks | LocalStream | None = None
+
+    if args.gradio:
+        api_key_textbox = gr.Textbox(
+            label="OPENAI API Key",
+            type="password",
+            value=os.getenv("OPENAI_API_KEY") if not get_space() else "",
+        )
+
+        from hello_world.gradio_personality import PersonalityUI
+
+        personality_ui = PersonalityUI()
+        personality_ui.create_components()
+
+        stream = Stream(
+            handler=handler,
+            mode="send-receive",
+            modality="audio",
+            additional_inputs=[
+                chatbot,
+                api_key_textbox,
+                *personality_ui.additional_inputs_ordered(),
+            ],
+            additional_outputs=[chatbot],
+            additional_outputs_handler=update_chatbot,
+            ui_args={"title": "Talk with Reachy Mini"},
+        )
+        stream_manager = stream.ui
+        if not settings_app:
+            app = FastAPI()
+        else:
+            app = settings_app
+
+        personality_ui.wire_events(handler, stream_manager)
+
+        app = gr.mount_gradio_app(app, stream.ui, path="/")
+    else:
+        # In headless mode, wire settings_app + instance_path to console LocalStream
+        stream_manager = LocalStream(
+            handler,
+            robot,
+            settings_app=settings_app,
+            instance_path=instance_path,
+        )
+
+    # Each async service → its own thread/loop
+    movement_manager.start()
+    head_wobbler.start()
+    if camera_worker:
+        camera_worker.start()
+    if vision_manager:
+        vision_manager.start()
+
+    def poll_stop_event() -> None:
+        """Poll the stop event to allow graceful shutdown."""
+        if app_stop_event is not None:
+            app_stop_event.wait()
+
+        logger.info("App stop event detected, shutting down...")
+        try:
+            stream_manager.close()
+        except Exception as e:
+            logger.error(f"Error while closing stream manager: {e}")
+
+    if app_stop_event:
+        threading.Thread(target=poll_stop_event, daemon=True).start()
+
+    try:
+        stream_manager.launch()
+    except KeyboardInterrupt:
+        logger.info("Keyboard interruption in main thread... closing server.")
+    finally:
+        movement_manager.stop()
+        head_wobbler.stop()
+        if camera_worker:
+            camera_worker.stop()
+        if vision_manager:
+            vision_manager.stop()
+
+        # Ensure media is explicitly closed before disconnecting
+        try:
+            robot.media.close()
+        except Exception as e:
+            logger.debug(f"Error closing media during shutdown: {e}")
+
+        # prevent connection to keep alive some threads
+        robot.client.disconnect()
+        time.sleep(1)
+        logger.info("Shutdown complete.")
+
+
+class HelloWorld(ReachyMiniApp):  # type: ignore[misc]
+    """Reachy Mini Apps entry point for the conversation app."""
+
+    custom_app_url = "http://0.0.0.0:7860/"
+    dont_start_webserver = False
+
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
+        """Run the Reachy Mini conversation app."""
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        args, _ = parse_args()
+
+        # is_wireless = reachy_mini.client.get_status()["wireless_version"]
+        # args.head_tracker = None if is_wireless else "mediapipe"
+
+        instance_path = self._get_instance_path().parent
+        run(
+            args,
+            robot=reachy_mini,
+            app_stop_event=stop_event,
+            settings_app=self.settings_app,
+            instance_path=instance_path,
+        )
+
+
+if __name__ == "__main__":
+    app = HelloWorld()
+    try:
+        app.wrapped_run()
+    except KeyboardInterrupt:
+        app.stop()

src/hello_world/moves.py

@@ -0,0 +1,849 @@
+"""Movement system with sequential primary moves and additive secondary moves.
+
+Design overview
+- Primary moves (emotions, dances, goto, breathing) are mutually exclusive and run
+  sequentially.
+- Secondary moves (speech sway, face tracking) are additive offsets applied on top
+  of the current primary pose.
+- There is a single control point to the robot: `ReachyMini.set_target`.
+- The control loop runs near 100 Hz and is phase-aligned via a monotonic clock.
+- Idle behaviour starts an infinite `BreathingMove` after a short inactivity delay
+  unless listening is active.
+
+Threading model
+- A dedicated worker thread owns all real-time state and issues `set_target`
+  commands.
+- Other threads communicate via a command queue (enqueue moves, mark activity,
+  toggle listening).
+- Secondary offset producers set pending values guarded by locks; the worker
+  snaps them atomically.
+
+Units and frames
+- Secondary offsets are interpreted as metres for x/y/z and radians for
+  roll/pitch/yaw in the world frame (unless noted by `compose_world_offset`).
+- Antennas and `body_yaw` are in radians.
+- Head pose composition uses `compose_world_offset(primary_head, secondary_head)`;
+  the secondary offset must therefore be expressed in the world frame.
+
+Safety
+- Listening freezes antennas, then blends them back on unfreeze.
+- Interpolations and blends are used to avoid jumps at all times.
+- `set_target` errors are rate-limited in logs.
+"""
+
+from __future__ import annotations
+import time
+import logging
+import threading
+from queue import Empty, Queue
+from typing import Any, Dict, Tuple
+from collections import deque
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+from reachy_mini.motion.move import Move
+from reachy_mini.utils.interpolation import (
+    compose_world_offset,
+    linear_pose_interpolation,
+)
+
+
+logger = logging.getLogger(__name__)
+
+# Configuration constants
+CONTROL_LOOP_FREQUENCY_HZ = 100.0  # Hz - Target frequency for the movement control loop
+
+# Type definitions
+FullBodyPose = Tuple[NDArray[np.float32], Tuple[float, float], float]  # (head_pose_4x4, antennas, body_yaw)
+
+
+class BreathingMove(Move):  # type: ignore
+    """Breathing move with interpolation to neutral and then continuous breathing patterns."""
+
+    def __init__(
+        self,
+        interpolation_start_pose: NDArray[np.float32],
+        interpolation_start_antennas: Tuple[float, float],
+        interpolation_duration: float = 1.0,
+    ):
+        """Initialize breathing move.
+
+        Args:
+            interpolation_start_pose: 4x4 matrix of current head pose to interpolate from
+            interpolation_start_antennas: Current antenna positions to interpolate from
+            interpolation_duration: Duration of interpolation to neutral (seconds)
+
+        """
+        self.interpolation_start_pose = interpolation_start_pose
+        self.interpolation_start_antennas = np.array(interpolation_start_antennas)
+        self.interpolation_duration = interpolation_duration
+
+        # Neutral positions for breathing base
+        self.neutral_head_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+        self.neutral_antennas = np.array([0.0, 0.0])
+
+        # Breathing parameters
+        self.breathing_z_amplitude = 0.005  # 5mm gentle breathing
+        self.breathing_frequency = 0.1  # Hz (6 breaths per minute)
+        self.antenna_sway_amplitude = np.deg2rad(15)  # 15 degrees
+        self.antenna_frequency = 0.5  # Hz (faster antenna sway)
+
+    @property
+    def duration(self) -> float:
+        """Duration property required by official Move interface."""
+        return float("inf")  # Continuous breathing (never ends naturally)
+
+    def evaluate(self, t: float) -> tuple[NDArray[np.float64] | None, NDArray[np.float64] | None, float | None]:
+        """Evaluate breathing move at time t."""
+        if t < self.interpolation_duration:
+            # Phase 1: Interpolate to neutral base position
+            interpolation_t = t / self.interpolation_duration
+
+            # Interpolate head pose
+            head_pose = linear_pose_interpolation(
+                self.interpolation_start_pose, self.neutral_head_pose, interpolation_t,
+            )
+
+            # Interpolate antennas
+            antennas_interp = (
+                1 - interpolation_t
+            ) * self.interpolation_start_antennas + interpolation_t * self.neutral_antennas
+            antennas = antennas_interp.astype(np.float64)
+
+        else:
+            # Phase 2: Breathing patterns from neutral base
+            breathing_time = t - self.interpolation_duration
+
+            # Gentle z-axis breathing
+            z_offset = self.breathing_z_amplitude * np.sin(2 * np.pi * self.breathing_frequency * breathing_time)
+            head_pose = create_head_pose(x=0, y=0, z=z_offset, roll=0, pitch=0, yaw=0, degrees=True, mm=False)
+
+            # Antenna sway (opposite directions)
+            antenna_sway = self.antenna_sway_amplitude * np.sin(2 * np.pi * self.antenna_frequency * breathing_time)
+            antennas = np.array([antenna_sway, -antenna_sway], dtype=np.float64)
+
+        # Return in official Move interface format: (head_pose, antennas_array, body_yaw)
+        return (head_pose, antennas, 0.0)
+
+
+def combine_full_body(primary_pose: FullBodyPose, secondary_pose: FullBodyPose) -> FullBodyPose:
+    """Combine primary and secondary full body poses.
+
+    Args:
+        primary_pose: (head_pose, antennas, body_yaw) - primary move
+        secondary_pose: (head_pose, antennas, body_yaw) - secondary offsets
+
+    Returns:
+        Combined full body pose (head_pose, antennas, body_yaw)
+
+    """
+    primary_head, primary_antennas, primary_body_yaw = primary_pose
+    secondary_head, secondary_antennas, secondary_body_yaw = secondary_pose
+
+    # Combine head poses using compose_world_offset; the secondary pose must be an
+    # offset expressed in the world frame (T_off_world) applied to the absolute
+    # primary transform (T_abs).
+    combined_head = compose_world_offset(primary_head, secondary_head, reorthonormalize=True)
+
+    # Sum antennas and body_yaw
+    combined_antennas = (
+        primary_antennas[0] + secondary_antennas[0],
+        primary_antennas[1] + secondary_antennas[1],
+    )
+    combined_body_yaw = primary_body_yaw + secondary_body_yaw
+
+    return (combined_head, combined_antennas, combined_body_yaw)
+
+
+def clone_full_body_pose(pose: FullBodyPose) -> FullBodyPose:
+    """Create a deep copy of a full body pose tuple."""
+    head, antennas, body_yaw = pose
+    return (head.copy(), (float(antennas[0]), float(antennas[1])), float(body_yaw))
+
+
+@dataclass
+class MovementState:
+    """State tracking for the movement system."""
+
+    # Primary move state
+    current_move: Move | None = None
+    move_start_time: float | None = None
+    last_activity_time: float = 0.0
+
+    # Secondary move state (offsets)
+    speech_offsets: Tuple[float, float, float, float, float, float] = (
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+    )
+    face_tracking_offsets: Tuple[float, float, float, float, float, float] = (
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+    )
+
+    # Status flags
+    last_primary_pose: FullBodyPose | None = None
+
+    def update_activity(self) -> None:
+        """Update the last activity time."""
+        self.last_activity_time = time.monotonic()
+
+
+@dataclass
+class LoopFrequencyStats:
+    """Track rolling loop frequency statistics."""
+
+    mean: float = 0.0
+    m2: float = 0.0
+    min_freq: float = float("inf")
+    count: int = 0
+    last_freq: float = 0.0
+    potential_freq: float = 0.0
+
+    def reset(self) -> None:
+        """Reset accumulators while keeping the last potential frequency."""
+        self.mean = 0.0
+        self.m2 = 0.0
+        self.min_freq = float("inf")
+        self.count = 0
+
+
+class MovementManager:
+    """Coordinate sequential moves, additive offsets, and robot output at 100 Hz.
+
+    Responsibilities:
+    - Own a real-time loop that samples the current primary move (if any), fuses
+      secondary offsets, and calls `set_target` exactly once per tick.
+    - Start an idle `BreathingMove` after `idle_inactivity_delay` when not
+      listening and no moves are queued.
+    - Expose thread-safe APIs so other threads can enqueue moves, mark activity,
+      or feed secondary offsets without touching internal state.
+
+    Timing:
+    - All elapsed-time calculations rely on `time.monotonic()` through `self._now`
+      to avoid wall-clock jumps.
+    - The loop attempts 100 Hz
+
+    Concurrency:
+    - External threads communicate via `_command_queue` messages.
+    - Secondary offsets are staged via dirty flags guarded by locks and consumed
+      atomically inside the worker loop.
+    """
+
+    def __init__(
+        self,
+        current_robot: ReachyMini,
+        camera_worker: "Any" = None,
+    ):
+        """Initialize movement manager."""
+        self.current_robot = current_robot
+        self.camera_worker = camera_worker
+
+        # Single timing source for durations
+        self._now = time.monotonic
+
+        # Movement state
+        self.state = MovementState()
+        self.state.last_activity_time = self._now()
+        neutral_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+        self.state.last_primary_pose = (neutral_pose, (0.0, 0.0), 0.0)
+
+        # Move queue (primary moves)
+        self.move_queue: deque[Move] = deque()
+
+        # Configuration
+        self.idle_inactivity_delay = 0.3  # seconds
+        self.target_frequency = CONTROL_LOOP_FREQUENCY_HZ
+        self.target_period = 1.0 / self.target_frequency
+
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._is_listening = False
+        self._last_commanded_pose: FullBodyPose = clone_full_body_pose(self.state.last_primary_pose)
+        self._listening_antennas: Tuple[float, float] = self._last_commanded_pose[1]
+        self._antenna_unfreeze_blend = 1.0
+        self._antenna_blend_duration = 0.4  # seconds to blend back after listening
+        self._last_listening_blend_time = self._now()
+        self._breathing_active = False  # true when breathing move is running or queued
+        self._listening_debounce_s = 0.15
+        self._last_listening_toggle_time = self._now()
+        self._last_set_target_err = 0.0
+        self._set_target_err_interval = 1.0  # seconds between error logs
+        self._set_target_err_suppressed = 0
+
+        # Cross-thread signalling
+        self._command_queue: "Queue[Tuple[str, Any]]" = Queue()
+        self._speech_offsets_lock = threading.Lock()
+        self._pending_speech_offsets: Tuple[float, float, float, float, float, float] = (
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+        )
+        self._speech_offsets_dirty = False
+
+        self._face_offsets_lock = threading.Lock()
+        self._pending_face_offsets: Tuple[float, float, float, float, float, float] = (
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+        )
+        self._face_offsets_dirty = False
+
+        self._shared_state_lock = threading.Lock()
+        self._shared_last_activity_time = self.state.last_activity_time
+        self._shared_is_listening = self._is_listening
+        self._status_lock = threading.Lock()
+        self._freq_stats = LoopFrequencyStats()
+        self._freq_snapshot = LoopFrequencyStats()
+
+    def queue_move(self, move: Move) -> None:
+        """Queue a primary move to run after the currently executing one.
+
+        Thread-safe: the move is enqueued via the worker command queue so the
+        control loop remains the sole mutator of movement state.
+        """
+        self._command_queue.put(("queue_move", move))
+
+    def clear_move_queue(self) -> None:
+        """Stop the active move and discard any queued primary moves.
+
+        Thread-safe: executed by the worker thread via the command queue.
+        """
+        self._command_queue.put(("clear_queue", None))
+
+    def set_speech_offsets(self, offsets: Tuple[float, float, float, float, float, float]) -> None:
+        """Update speech-induced secondary offsets (x, y, z, roll, pitch, yaw).
+
+        Offsets are interpreted as metres for translation and radians for
+        rotation in the world frame. Thread-safe via a pending snapshot.
+        """
+        with self._speech_offsets_lock:
+            self._pending_speech_offsets = offsets
+            self._speech_offsets_dirty = True
+
+    def set_moving_state(self, duration: float) -> None:
+        """Mark the robot as actively moving for the provided duration.
+
+        Legacy hook used by goto helpers to keep inactivity and breathing logic
+        aware of manual motions. Thread-safe via the command queue.
+        """
+        self._command_queue.put(("set_moving_state", duration))
+
+    def is_idle(self) -> bool:
+        """Return True when the robot has been inactive longer than the idle delay."""
+        with self._shared_state_lock:
+            last_activity = self._shared_last_activity_time
+            listening = self._shared_is_listening
+
+        if listening:
+            return False
+
+        return self._now() - last_activity >= self.idle_inactivity_delay
+
+    def set_listening(self, listening: bool) -> None:
+        """Enable or disable listening mode without touching shared state directly.
+
+        While listening:
+        - Antenna positions are frozen at the last commanded values.
+        - Blending is reset so that upon unfreezing the antennas return smoothly.
+        - Idle breathing is suppressed.
+
+        Thread-safe: the change is posted to the worker command queue.
+        """
+        with self._shared_state_lock:
+            if self._shared_is_listening == listening:
+                return
+        self._command_queue.put(("set_listening", listening))
+
+    def _poll_signals(self, current_time: float) -> None:
+        """Apply queued commands and pending offset updates."""
+        self._apply_pending_offsets()
+
+        while True:
+            try:
+                command, payload = self._command_queue.get_nowait()
+            except Empty:
+                break
+            self._handle_command(command, payload, current_time)
+
+    def _apply_pending_offsets(self) -> None:
+        """Apply the most recent speech/face offset updates."""
+        speech_offsets: Tuple[float, float, float, float, float, float] | None = None
+        with self._speech_offsets_lock:
+            if self._speech_offsets_dirty:
+                speech_offsets = self._pending_speech_offsets
+                self._speech_offsets_dirty = False
+
+        if speech_offsets is not None:
+            self.state.speech_offsets = speech_offsets
+            self.state.update_activity()
+
+        face_offsets: Tuple[float, float, float, float, float, float] | None = None
+        with self._face_offsets_lock:
+            if self._face_offsets_dirty:
+                face_offsets = self._pending_face_offsets
+                self._face_offsets_dirty = False
+
+        if face_offsets is not None:
+            self.state.face_tracking_offsets = face_offsets
+            self.state.update_activity()
+
+    def _handle_command(self, command: str, payload: Any, current_time: float) -> None:
+        """Handle a single cross-thread command."""
+        if command == "queue_move":
+            if isinstance(payload, Move):
+                self.move_queue.append(payload)
+                self.state.update_activity()
+                duration = getattr(payload, "duration", None)
+                if duration is not None:
+                    try:
+                        duration_str = f"{float(duration):.2f}"
+                    except (TypeError, ValueError):
+                        duration_str = str(duration)
+                else:
+                    duration_str = "?"
+                logger.debug(
+                    "Queued move with duration %ss, queue size: %s",
+                    duration_str,
+                    len(self.move_queue),
+                )
+            else:
+                logger.warning("Ignored queue_move command with invalid payload: %s", payload)
+        elif command == "clear_queue":
+            self.move_queue.clear()
+            self.state.current_move = None
+            self.state.move_start_time = None
+            self._breathing_active = False
+            logger.info("Cleared move queue and stopped current move")
+        elif command == "set_moving_state":
+            try:
+                duration = float(payload)
+            except (TypeError, ValueError):
+                logger.warning("Invalid moving state duration: %s", payload)
+                return
+            self.state.update_activity()
+        elif command == "mark_activity":
+            self.state.update_activity()
+        elif command == "set_listening":
+            desired_state = bool(payload)
+            now = self._now()
+            if now - self._last_listening_toggle_time < self._listening_debounce_s:
+                return
+            self._last_listening_toggle_time = now
+
+            if self._is_listening == desired_state:
+                return
+
+            self._is_listening = desired_state
+            self._last_listening_blend_time = now
+            if desired_state:
+                # Freeze: snapshot current commanded antennas and reset blend
+                self._listening_antennas = (
+                    float(self._last_commanded_pose[1][0]),
+                    float(self._last_commanded_pose[1][1]),
+                )
+                self._antenna_unfreeze_blend = 0.0
+            else:
+                # Unfreeze: restart blending from frozen pose
+                self._antenna_unfreeze_blend = 0.0
+            self.state.update_activity()
+        else:
+            logger.warning("Unknown command received by MovementManager: %s", command)
+
+    def _publish_shared_state(self) -> None:
+        """Expose idle-related state for external threads."""
+        with self._shared_state_lock:
+            self._shared_last_activity_time = self.state.last_activity_time
+            self._shared_is_listening = self._is_listening
+
+    def _manage_move_queue(self, current_time: float) -> None:
+        """Manage the primary move queue (sequential execution)."""
+        if self.state.current_move is None or (
+            self.state.move_start_time is not None
+            and current_time - self.state.move_start_time >= self.state.current_move.duration
+        ):
+            self.state.current_move = None
+            self.state.move_start_time = None
+
+            if self.move_queue:
+                self.state.current_move = self.move_queue.popleft()
+                self.state.move_start_time = current_time
+                # Any real move cancels breathing mode flag
+                self._breathing_active = isinstance(self.state.current_move, BreathingMove)
+                logger.debug(f"Starting new move, duration: {self.state.current_move.duration}s")
+
+    def _manage_breathing(self, current_time: float) -> None:
+        """Manage automatic breathing when idle."""
+        if (
+            self.state.current_move is None
+            and not self.move_queue
+            and not self._is_listening
+            and not self._breathing_active
+        ):
+            idle_for = current_time - self.state.last_activity_time
+            if idle_for >= self.idle_inactivity_delay:
+                try:
+                    # These 2 functions return the latest available sensor data from the robot, but don't perform I/O synchronously.
+                    # Therefore, we accept calling them inside the control loop.
+                    _, current_antennas = self.current_robot.get_current_joint_positions()
+                    current_head_pose = self.current_robot.get_current_head_pose()
+
+                    self._breathing_active = True
+                    self.state.update_activity()
+
+                    breathing_move = BreathingMove(
+                        interpolation_start_pose=current_head_pose,
+                        interpolation_start_antennas=current_antennas,
+                        interpolation_duration=1.0,
+                    )
+                    self.move_queue.append(breathing_move)
+                    logger.debug("Started breathing after %.1fs of inactivity", idle_for)
+                except Exception as e:
+                    self._breathing_active = False
+                    logger.error("Failed to start breathing: %s", e)
+
+        if isinstance(self.state.current_move, BreathingMove) and self.move_queue:
+            self.state.current_move = None
+            self.state.move_start_time = None
+            self._breathing_active = False
+            logger.debug("Stopping breathing due to new move activity")
+
+        if self.state.current_move is not None and not isinstance(self.state.current_move, BreathingMove):
+            self._breathing_active = False
+
+    def _get_primary_pose(self, current_time: float) -> FullBodyPose:
+        """Get the primary full body pose from current move or neutral."""
+        # When a primary move is playing, sample it and cache the resulting pose
+        if self.state.current_move is not None and self.state.move_start_time is not None:
+            move_time = current_time - self.state.move_start_time
+            head, antennas, body_yaw = self.state.current_move.evaluate(move_time)
+
+            if head is None:
+                head = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+            if antennas is None:
+                antennas = np.array([0.0, 0.0])
+            if body_yaw is None:
+                body_yaw = 0.0
+
+            antennas_tuple = (float(antennas[0]), float(antennas[1]))
+            head_copy = head.copy()
+            primary_full_body_pose = (
+                head_copy,
+                antennas_tuple,
+                float(body_yaw),
+            )
+
+            self.state.last_primary_pose = clone_full_body_pose(primary_full_body_pose)
+        # Otherwise reuse the last primary pose so we avoid jumps between moves
+        elif self.state.last_primary_pose is not None:
+            primary_full_body_pose = clone_full_body_pose(self.state.last_primary_pose)
+        else:
+            neutral_head_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+            primary_full_body_pose = (neutral_head_pose, (0.0, 0.0), 0.0)
+            self.state.last_primary_pose = clone_full_body_pose(primary_full_body_pose)
+
+        return primary_full_body_pose
+
+    def _get_secondary_pose(self) -> FullBodyPose:
+        """Get the secondary full body pose from speech and face tracking offsets."""
+        # Combine speech sway offsets + face tracking offsets for secondary pose
+        secondary_offsets = [
+            self.state.speech_offsets[0] + self.state.face_tracking_offsets[0],
+            self.state.speech_offsets[1] + self.state.face_tracking_offsets[1],
+            self.state.speech_offsets[2] + self.state.face_tracking_offsets[2],
+            self.state.speech_offsets[3] + self.state.face_tracking_offsets[3],
+            self.state.speech_offsets[4] + self.state.face_tracking_offsets[4],
+            self.state.speech_offsets[5] + self.state.face_tracking_offsets[5],
+        ]
+
+        secondary_head_pose = create_head_pose(
+            x=secondary_offsets[0],
+            y=secondary_offsets[1],
+            z=secondary_offsets[2],
+            roll=secondary_offsets[3],
+            pitch=secondary_offsets[4],
+            yaw=secondary_offsets[5],
+            degrees=False,
+            mm=False,
+        )
+        return (secondary_head_pose, (0.0, 0.0), 0.0)
+
+    def _compose_full_body_pose(self, current_time: float) -> FullBodyPose:
+        """Compose primary and secondary poses into a single command pose."""
+        primary = self._get_primary_pose(current_time)
+        secondary = self._get_secondary_pose()
+        return combine_full_body(primary, secondary)
+
+    def _update_primary_motion(self, current_time: float) -> None:
+        """Advance queue state and idle behaviours for this tick."""
+        self._manage_move_queue(current_time)
+        self._manage_breathing(current_time)
+
+    def _calculate_blended_antennas(self, target_antennas: Tuple[float, float]) -> Tuple[float, float]:
+        """Blend target antennas with listening freeze state and update blending."""
+        now = self._now()
+        listening = self._is_listening
+        listening_antennas = self._listening_antennas
+        blend = self._antenna_unfreeze_blend
+        blend_duration = self._antenna_blend_duration
+        last_update = self._last_listening_blend_time
+        self._last_listening_blend_time = now
+
+        if listening:
+            antennas_cmd = listening_antennas
+            new_blend = 0.0
+        else:
+            dt = max(0.0, now - last_update)
+            if blend_duration <= 0:
+                new_blend = 1.0
+            else:
+                new_blend = min(1.0, blend + dt / blend_duration)
+            antennas_cmd = (
+                listening_antennas[0] * (1.0 - new_blend) + target_antennas[0] * new_blend,
+                listening_antennas[1] * (1.0 - new_blend) + target_antennas[1] * new_blend,
+            )
+
+        if listening:
+            self._antenna_unfreeze_blend = 0.0
+        else:
+            self._antenna_unfreeze_blend = new_blend
+            if new_blend >= 1.0:
+                self._listening_antennas = (
+                    float(target_antennas[0]),
+                    float(target_antennas[1]),
+                )
+
+        return antennas_cmd
+
+    def _issue_control_command(self, head: NDArray[np.float32], antennas: Tuple[float, float], body_yaw: float) -> None:
+        """Send the fused pose to the robot with throttled error logging."""
+        try:
+            self.current_robot.set_target(head=head, antennas=antennas, body_yaw=body_yaw)
+        except Exception as e:
+            now = self._now()
+            if now - self._last_set_target_err >= self._set_target_err_interval:
+                msg = f"Failed to set robot target: {e}"
+                if self._set_target_err_suppressed:
+                    msg += f" (suppressed {self._set_target_err_suppressed} repeats)"
+                    self._set_target_err_suppressed = 0
+                logger.error(msg)
+                self._last_set_target_err = now
+            else:
+                self._set_target_err_suppressed += 1
+        else:
+            with self._status_lock:
+                self._last_commanded_pose = clone_full_body_pose((head, antennas, body_yaw))
+
+    def _update_frequency_stats(
+        self, loop_start: float, prev_loop_start: float, stats: LoopFrequencyStats,
+    ) -> LoopFrequencyStats:
+        """Update frequency statistics based on the current loop start time."""
+        period = loop_start - prev_loop_start
+        if period > 0:
+            stats.last_freq = 1.0 / period
+            stats.count += 1
+            delta = stats.last_freq - stats.mean
+            stats.mean += delta / stats.count
+            stats.m2 += delta * (stats.last_freq - stats.mean)
+            stats.min_freq = min(stats.min_freq, stats.last_freq)
+        return stats
+
+    def _schedule_next_tick(self, loop_start: float, stats: LoopFrequencyStats) -> Tuple[float, LoopFrequencyStats]:
+        """Compute sleep time to maintain target frequency and update potential freq."""
+        computation_time = self._now() - loop_start
+        stats.potential_freq = 1.0 / computation_time if computation_time > 0 else float("inf")
+        sleep_time = max(0.0, self.target_period - computation_time)
+        return sleep_time, stats
+
+    def _record_frequency_snapshot(self, stats: LoopFrequencyStats) -> None:
+        """Store a thread-safe snapshot of current frequency statistics."""
+        with self._status_lock:
+            self._freq_snapshot = LoopFrequencyStats(
+                mean=stats.mean,
+                m2=stats.m2,
+                min_freq=stats.min_freq,
+                count=stats.count,
+                last_freq=stats.last_freq,
+                potential_freq=stats.potential_freq,
+            )
+
+    def _maybe_log_frequency(self, loop_count: int, print_interval_loops: int, stats: LoopFrequencyStats) -> None:
+        """Emit frequency telemetry when enough loops have elapsed."""
+        if loop_count % print_interval_loops != 0 or stats.count == 0:
+            return
+
+        variance = stats.m2 / stats.count if stats.count > 0 else 0.0
+        lowest = stats.min_freq if stats.min_freq != float("inf") else 0.0
+        logger.debug(
+            "Loop freq - avg: %.2fHz, variance: %.4f, min: %.2fHz, last: %.2fHz, potential: %.2fHz, target: %.1fHz",
+            stats.mean,
+            variance,
+            lowest,
+            stats.last_freq,
+            stats.potential_freq,
+            self.target_frequency,
+        )
+        stats.reset()
+
+    def _update_face_tracking(self, current_time: float) -> None:
+        """Get face tracking offsets from camera worker thread."""
+        if self.camera_worker is not None:
+            # Get face tracking offsets from camera worker thread
+            offsets = self.camera_worker.get_face_tracking_offsets()
+            self.state.face_tracking_offsets = offsets
+        else:
+            # No camera worker, use neutral offsets
+            self.state.face_tracking_offsets = (0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
+
+    def start(self) -> None:
+        """Start the worker thread that drives the 100 Hz control loop."""
+        if self._thread is not None and self._thread.is_alive():
+            logger.warning("Move worker already running; start() ignored")
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self.working_loop, daemon=True)
+        self._thread.start()
+        logger.debug("Move worker started")
+
+    def stop(self) -> None:
+        """Request the worker thread to stop and wait for it to exit.
+
+        Before stopping, resets the robot to a neutral position.
+        """
+        if self._thread is None or not self._thread.is_alive():
+            logger.debug("Move worker not running; stop() ignored")
+            return
+
+        logger.info("Stopping movement manager and resetting to neutral position...")
+
+        # Clear any queued moves and stop current move
+        self.clear_move_queue()
+
+        # Stop the worker thread first so it doesn't interfere
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join()
+            self._thread = None
+        logger.debug("Move worker stopped")
+
+        # Reset to neutral position using goto_target (same approach as wake_up)
+        try:
+            neutral_head_pose = create_head_pose(0, 0, 0, 0, 0, 0, degrees=True)
+            neutral_antennas = [0.0, 0.0]
+            neutral_body_yaw = 0.0
+
+            # Use goto_target directly on the robot
+            self.current_robot.goto_target(
+                head=neutral_head_pose,
+                antennas=neutral_antennas,
+                duration=2.0,
+                body_yaw=neutral_body_yaw,
+            )
+
+            logger.info("Reset to neutral position completed")
+
+        except Exception as e:
+            logger.error(f"Failed to reset to neutral position: {e}")
+
+    def get_status(self) -> Dict[str, Any]:
+        """Return a lightweight status snapshot for observability."""
+        with self._status_lock:
+            pose_snapshot = clone_full_body_pose(self._last_commanded_pose)
+            freq_snapshot = LoopFrequencyStats(
+                mean=self._freq_snapshot.mean,
+                m2=self._freq_snapshot.m2,
+                min_freq=self._freq_snapshot.min_freq,
+                count=self._freq_snapshot.count,
+                last_freq=self._freq_snapshot.last_freq,
+                potential_freq=self._freq_snapshot.potential_freq,
+            )
+
+        head_matrix = pose_snapshot[0].tolist() if pose_snapshot else None
+        antennas = pose_snapshot[1] if pose_snapshot else None
+        body_yaw = pose_snapshot[2] if pose_snapshot else None
+
+        return {
+            "queue_size": len(self.move_queue),
+            "is_listening": self._is_listening,
+            "breathing_active": self._breathing_active,
+            "last_commanded_pose": {
+                "head": head_matrix,
+                "antennas": antennas,
+                "body_yaw": body_yaw,
+            },
+            "loop_frequency": {
+                "last": freq_snapshot.last_freq,
+                "mean": freq_snapshot.mean,
+                "min": freq_snapshot.min_freq,
+                "potential": freq_snapshot.potential_freq,
+                "samples": freq_snapshot.count,
+            },
+        }
+
+    def working_loop(self) -> None:
+        """Control loop main movements - reproduces main_works.py control architecture.
+
+        Single set_target() call with pose fusion.
+        """
+        logger.debug("Starting enhanced movement control loop (100Hz)")
+
+        loop_count = 0
+        prev_loop_start = self._now()
+        print_interval_loops = max(1, int(self.target_frequency * 2))
+        freq_stats = self._freq_stats
+
+        while not self._stop_event.is_set():
+            loop_start = self._now()
+            loop_count += 1
+
+            if loop_count > 1:
+                freq_stats = self._update_frequency_stats(loop_start, prev_loop_start, freq_stats)
+            prev_loop_start = loop_start
+
+            # 1) Poll external commands and apply pending offsets (atomic snapshot)
+            self._poll_signals(loop_start)
+
+            # 2) Manage the primary move queue (start new move, end finished move, breathing)
+            self._update_primary_motion(loop_start)
+
+            # 3) Update vision-based secondary offsets
+            self._update_face_tracking(loop_start)
+
+            # 4) Build primary and secondary full-body poses, then fuse them
+            head, antennas, body_yaw = self._compose_full_body_pose(loop_start)
+
+            # 5) Apply listening antenna freeze or blend-back
+            antennas_cmd = self._calculate_blended_antennas(antennas)
+
+            # 6) Single set_target call - the only control point
+            self._issue_control_command(head, antennas_cmd, body_yaw)
+
+            # 7) Adaptive sleep to align to next tick, then publish shared state
+            sleep_time, freq_stats = self._schedule_next_tick(loop_start, freq_stats)
+            self._publish_shared_state()
+            self._record_frequency_snapshot(freq_stats)
+
+            # 8) Periodic telemetry on loop frequency
+            self._maybe_log_frequency(loop_count, print_interval_loops, freq_stats)
+
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+
+        logger.debug("Movement control loop stopped")

src/hello_world/openai_realtime.py

@@ -0,0 +1,935 @@
+import json
+import uuid
+import base64
+import random
+import asyncio
+import logging
+from typing import Any, Final, Tuple, Literal, Optional
+from pathlib import Path
+from datetime import datetime
+
+import cv2
+import numpy as np
+import gradio as gr
+from openai import AsyncOpenAI
+from fastrtc import AdditionalOutputs, AsyncStreamHandler, wait_for_item, audio_to_int16
+from numpy.typing import NDArray
+from scipy.signal import resample
+from websockets.exceptions import ConnectionClosedError
+
+from hello_world.config import config
+from hello_world.prompts import get_session_voice, get_session_instructions
+from hello_world.tools.core_tools import (
+    ToolDependencies,
+    get_tool_specs,
+)
+from hello_world.tools.background_tool_manager import (
+    ToolCallRoutine,
+    ToolNotification,
+    BackgroundToolManager,
+)
+
+
+logger = logging.getLogger(__name__)
+
+OPEN_AI_INPUT_SAMPLE_RATE: Final[Literal[24000]] = 24000
+OPEN_AI_OUTPUT_SAMPLE_RATE: Final[Literal[24000]] = 24000
+
+# Cost tracking from usage data (pricing as of Feb 2026 https://openai.com/api/pricing/)
+AUDIO_INPUT_COST_PER_1M = 32.0
+AUDIO_OUTPUT_COST_PER_1M = 64.0
+TEXT_INPUT_COST_PER_1M = 4.0
+TEXT_OUTPUT_COST_PER_1M = 16.0
+IMAGE_INPUT_COST_PER_1M = 5.0
+
+_RESPONSE_DONE_TIMEOUT: Final[float] = 30.0
+
+
+def _compute_response_cost(usage: Any) -> float:
+    """Compute dollar cost from a response usage object."""
+    inp = getattr(usage, "input_token_details", None)
+    out = getattr(usage, "output_token_details", None)
+    cost = 0.0
+    if inp:
+        cost += (getattr(inp, "audio_tokens", 0) or 0) * AUDIO_INPUT_COST_PER_1M / 1e6
+        cost += (getattr(inp, "text_tokens", 0) or 0) * TEXT_INPUT_COST_PER_1M / 1e6
+        cost += (getattr(inp, "image_tokens", 0) or 0) * IMAGE_INPUT_COST_PER_1M / 1e6
+    if out:
+        cost += (getattr(out, "audio_tokens", 0) or 0) * AUDIO_OUTPUT_COST_PER_1M / 1e6
+        cost += (getattr(out, "text_tokens", 0) or 0) * TEXT_OUTPUT_COST_PER_1M / 1e6
+    return cost
+
+
+class OpenaiRealtimeHandler(AsyncStreamHandler):
+    """An OpenAI realtime handler for fastrtc Stream."""
+
+    def __init__(self, deps: ToolDependencies, gradio_mode: bool = False, instance_path: Optional[str] = None):
+        """Initialize the handler."""
+        super().__init__(
+            expected_layout="mono",
+            output_sample_rate=OPEN_AI_OUTPUT_SAMPLE_RATE,
+            input_sample_rate=OPEN_AI_INPUT_SAMPLE_RATE,
+        )
+
+        # Override typing of the sample rates to match OpenAI's requirements
+        self.output_sample_rate: Literal[24000] = self.output_sample_rate
+        self.input_sample_rate: Literal[24000] = self.input_sample_rate
+
+        self.deps = deps
+
+        # Override type annotations for OpenAI strict typing (only for values used in API)
+        self.output_sample_rate = OPEN_AI_OUTPUT_SAMPLE_RATE
+        self.input_sample_rate = OPEN_AI_INPUT_SAMPLE_RATE
+
+        self.connection: Any = None
+        self.output_queue: "asyncio.Queue[Tuple[int, NDArray[np.int16]] | AdditionalOutputs]" = asyncio.Queue()
+
+        self.last_activity_time = asyncio.get_event_loop().time()
+        self.start_time = asyncio.get_event_loop().time()
+        self.is_idle_tool_call = False
+        self.gradio_mode = gradio_mode
+        self.instance_path = instance_path
+        # Track how the API key was provided (env vs textbox) and its value
+        self._key_source: Literal["env", "textbox"] = "env"
+        self._provided_api_key: str | None = None
+
+        # Debouncing for partial transcripts
+        self.partial_transcript_task: asyncio.Task[None] | None = None
+        self.partial_transcript_sequence: int = 0  # sequence counter to prevent stale emissions
+        self.partial_debounce_delay = 0.5  # seconds
+
+        # Internal lifecycle flags
+        self._shutdown_requested: bool = False
+        self._connected_event: asyncio.Event = asyncio.Event()
+
+        # Background tool manager
+        self.tool_manager = BackgroundToolManager()
+
+        # Cost tracking
+        self.cumulative_cost: float = 0.0
+
+        # Response-in-progress guard: the Realtime API only allows one active
+        # response per conversation at a time.  A dedicated worker task
+        # (_response_sender_loop) dequeues and sends one request at a time
+        self._pending_responses: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._response_done_event: asyncio.Event = asyncio.Event()
+        self._response_done_event.set()
+        self._last_response_rejected: bool = False
+
+    def copy(self) -> "OpenaiRealtimeHandler":
+        """Create a copy of the handler."""
+        return OpenaiRealtimeHandler(self.deps, self.gradio_mode, self.instance_path)
+
+    async def apply_personality(self, profile: str | None) -> str:
+        """Apply a new personality (profile) at runtime if possible.
+
+        - Updates the global config's selected profile for subsequent calls.
+        - If a realtime connection is active, sends a session.update with the
+          freshly resolved instructions so the change takes effect immediately.
+
+        Returns a short status message for UI feedback.
+        """
+        try:
+            # Update the in-process config value and env
+            from hello_world.config import config as _config
+            from hello_world.config import set_custom_profile
+
+            set_custom_profile(profile)
+            logger.info(
+                "Set custom profile to %r (config=%r)", profile, getattr(_config, "REACHY_MINI_CUSTOM_PROFILE", None)
+            )
+
+            try:
+                instructions = get_session_instructions()
+                voice = get_session_voice()
+            except BaseException as e:  # catch SystemExit from prompt loader without crashing
+                logger.error("Failed to resolve personality content: %s", e)
+                return f"Failed to apply personality: {e}"
+
+            # Attempt a live update first, then force a full restart to ensure it sticks
+            if self.connection is not None:
+                try:
+                    await self.connection.session.update(
+                        session={
+                            "type": "realtime",
+                            "instructions": instructions,
+                            "audio": {"output": {"voice": voice}},
+                        },
+                    )
+                    logger.info("Applied personality via live update: %s", profile or "built-in default")
+                except Exception as e:
+                    logger.warning("Live update failed; will restart session: %s", e)
+
+                # Force a real restart to guarantee the new instructions/voice
+                try:
+                    await self._restart_session()
+                    return "Applied personality and restarted realtime session."
+                except Exception as e:
+                    logger.warning("Failed to restart session after apply: %s", e)
+                    return "Applied personality. Will take effect on next connection."
+            else:
+                logger.info(
+                    "Applied personality recorded: %s (no live connection; will apply on next session)",
+                    profile or "built-in default",
+                )
+                return "Applied personality. Will take effect on next connection."
+        except Exception as e:
+            logger.error("Error applying personality '%s': %s", profile, e)
+            return f"Failed to apply personality: {e}"
+
+    async def _emit_debounced_partial(self, transcript: str, sequence: int) -> None:
+        """Emit partial transcript after debounce delay."""
+        try:
+            await asyncio.sleep(self.partial_debounce_delay)
+            # Only emit if this is still the latest partial (by sequence number)
+            if self.partial_transcript_sequence == sequence:
+                await self.output_queue.put(AdditionalOutputs({"role": "user_partial", "content": transcript}))
+                logger.debug(f"Debounced partial emitted: {transcript}")
+        except asyncio.CancelledError:
+            logger.debug("Debounced partial cancelled")
+            raise
+
+    async def start_up(self) -> None:
+        """Start the handler with minimal retries on unexpected websocket closure."""
+        openai_api_key = config.OPENAI_API_KEY
+        if self.gradio_mode and not openai_api_key:
+            # api key was not found in .env or in the environment variables
+            await self.wait_for_args()  # type: ignore[no-untyped-call]
+            args = list(self.latest_args)
+            textbox_api_key = args[3] if len(args[3]) > 0 else None
+            if textbox_api_key is not None:
+                openai_api_key = textbox_api_key
+                self._key_source = "textbox"
+                self._provided_api_key = textbox_api_key
+            else:
+                openai_api_key = config.OPENAI_API_KEY
+        else:
+            if not openai_api_key or not openai_api_key.strip():
+                # In headless console mode, LocalStream now blocks startup until the key is provided.
+                # However, unit tests may invoke this handler directly with a stubbed client.
+                # To keep tests hermetic without requiring a real key, fall back to a placeholder.
+                logger.warning("OPENAI_API_KEY missing. Proceeding with a placeholder (tests/offline).")
+                openai_api_key = "DUMMY"
+
+        self.client = AsyncOpenAI(api_key=openai_api_key)
+
+        max_attempts = 3
+        for attempt in range(1, max_attempts + 1):
+            try:
+                await self._run_realtime_session()
+                # Normal exit from the session, stop retrying
+                return
+            except ConnectionClosedError as e:
+                # Abrupt close (e.g., "no close frame received or sent") → retry
+                logger.warning("Realtime websocket closed unexpectedly (attempt %d/%d): %s", attempt, max_attempts, e)
+                if attempt < max_attempts:
+                    # exponential backoff with jitter
+                    base_delay = 2 ** (attempt - 1)  # 1s, 2s, 4s, 8s, etc.
+                    jitter = random.uniform(0, 0.5)
+                    delay = base_delay + jitter
+                    logger.info("Retrying in %.1f seconds...", delay)
+                    await asyncio.sleep(delay)
+                    continue
+                raise
+            finally:
+                # never keep a stale reference
+                self.connection = None
+                try:
+                    self._connected_event.clear()
+                except Exception:
+                    pass
+
+    async def _restart_session(self) -> None:
+        """Force-close the current session and start a fresh one in background.
+
+        Does not block the caller while the new session is establishing.
+        """
+        try:
+            if self.connection is not None:
+                try:
+                    await self.connection.close()
+                except Exception:
+                    pass
+                finally:
+                    self.connection = None
+
+            # Ensure we have a client (start_up must have run once)
+            if getattr(self, "client", None) is None:
+                logger.warning("Cannot restart: OpenAI client not initialized yet.")
+                return
+
+            # Fire-and-forget new session and wait briefly for connection
+            try:
+                self._connected_event.clear()
+            except Exception:
+                pass
+            asyncio.create_task(self._run_realtime_session(), name="openai-realtime-restart")
+            try:
+                await asyncio.wait_for(self._connected_event.wait(), timeout=5.0)
+                logger.info("Realtime session restarted and connected.")
+            except asyncio.TimeoutError:
+                logger.warning("Realtime session restart timed out; continuing in background.")
+        except Exception as e:
+            logger.warning("_restart_session failed: %s", e)
+
+    async def _safe_response_create(self, **kwargs: Any) -> None:
+        """Enqueue a response.create() kwargs for the sender worker _response_sender_loop().
+
+        This method never blocks the caller.
+        """
+        await self._pending_responses.put(kwargs)
+
+    async def _response_sender_loop(self) -> None:
+        """Dedicated worker that sends ``response.create()`` calls serially.
+
+        This logic was designed to comply with the response.create() docstring specification for event ordering:
+        https://github.com/openai/openai-python/blob/3e0c05b84a2056870abf3bd6a5e7849020209cc3/src/openai/resources/realtime/realtime.py#L649C1-L651C30
+
+        For each queued request the worker:
+        1. Waits until no response is active (_response_done_event).
+        2. Sends response.create().
+        3. Waits for the response cycle to complete (response.done).
+        4. If the server rejected with active_response, retries from step 1.
+        """
+        while self.connection:
+            try:
+                kwargs = await self._pending_responses.get()
+            except asyncio.CancelledError:
+                return
+
+            sent = False
+            max_retries = 5
+            attempts = 0
+            while not sent and self.connection and attempts < max_retries:
+                try:
+                    await asyncio.wait_for(self._response_done_event.wait(), timeout=_RESPONSE_DONE_TIMEOUT)
+                except asyncio.TimeoutError:
+                    logger.debug("Timed out waiting for previous response to finish; forcing ahead")
+                    self._response_done_event.set()
+
+                if not self.connection:
+                    break
+
+                self._last_response_rejected = False
+                try:
+                    await self.connection.response.create(**kwargs)
+                except Exception as e:
+                    logger.debug("_response_sender_loop: send failed: %s", e)
+                    self._response_done_event.set()
+                    break
+
+                try:
+                    await asyncio.wait_for(self._response_done_event.wait(), timeout=_RESPONSE_DONE_TIMEOUT)
+                except asyncio.TimeoutError:
+                    logger.debug("Timed out waiting for response.done; assuming response completed")
+                    self._response_done_event.set()
+                    break
+
+                # Check if we were rejected
+                if self._last_response_rejected:
+                    attempts += 1
+                    if attempts >= max_retries:
+                        logger.debug("response.create rejected %d times; giving up", attempts)
+                        break
+                    logger.debug("response.create was rejected; retrying (%d/%d)", attempts, max_retries)
+                    continue
+
+                sent = True
+
+    async def _handle_tool_result(self, bg_tool: ToolNotification) -> None:
+        """Process the result of a tool call."""
+        if bg_tool.error is not None:
+            logger.error("Tool '%s' (id=%s) failed with error: %s", bg_tool.tool_name, bg_tool.id, bg_tool.error)
+            tool_result = {"error": bg_tool.error}
+        elif bg_tool.result is not None:
+            tool_result = bg_tool.result
+            logger.info(
+                "Tool '%s' (id=%s) executed successfully.",
+                bg_tool.tool_name, bg_tool.id,
+            )
+            logger.debug("Tool '%s' full result: %s", bg_tool.tool_name, tool_result)
+        else:
+            logger.warning("Tool '%s' (id=%s) returned no result and no error", bg_tool.tool_name, bg_tool.id)
+            tool_result = {"error": "No result returned from tool execution"}
+
+        # Connection may have closed while tool was running
+        if not self.connection:
+            logger.warning("Connection closed during tool '%s' (id=%s) execution; cannot send result back", bg_tool.tool_name, bg_tool.id)
+            return
+
+        try:
+            # Send the tool result back
+            if isinstance(bg_tool.id, str):
+                await self.connection.conversation.item.create(
+                    item={
+                        "type": "function_call_output",
+                        "call_id": bg_tool.id,
+                        "output": json.dumps(tool_result),
+                    },
+                )
+
+            await self.output_queue.put(
+                AdditionalOutputs(
+                    {
+                        "role": "assistant",
+                        "content": json.dumps(tool_result),
+                        # Gradio UI metadata.status accept only "pending" and "done". Do not accept bg.tool.status values.
+                        "metadata": {
+                            "title": f"🛠️ Used tool {bg_tool.tool_name}",
+                            "status": "done",
+                        },
+                    },
+                ),
+            )
+
+            if bg_tool.tool_name == "camera" and "b64_im" in tool_result:
+                # use raw base64, don't json.dumps (which adds quotes)
+                b64_im = tool_result["b64_im"]
+                if not isinstance(b64_im, str):
+                    logger.warning("Unexpected type for b64_im: %s", type(b64_im))
+                    b64_im = str(b64_im)
+                await self.connection.conversation.item.create(
+                    item={
+                        "type": "message",
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "input_image",
+                                "image_url": f"data:image/jpeg;base64,{b64_im}",
+                            },
+                        ],
+                    },
+                )
+                logger.info("Added camera image to conversation")
+
+                if self.deps.camera_worker is not None:
+                    np_img = self.deps.camera_worker.get_latest_frame()
+                    if np_img is not None:
+                        # Camera frames are BGR from OpenCV; convert so Gradio displays correct colors.
+                        rgb_frame = cv2.cvtColor(np_img, cv2.COLOR_BGR2RGB)
+                    else:
+                        rgb_frame = None
+                    img = gr.Image(value=rgb_frame)
+
+                    await self.output_queue.put(
+                        AdditionalOutputs(
+                            {
+                                "role": "assistant",
+                                "content": img,
+                            },
+                        ),
+                    )
+
+            # If this tool call was triggered by an idle signal, don't make the robot speak.
+            # For other tool calls, let the robot reply out loud.
+            if not bg_tool.is_idle_tool_call:
+                await self._safe_response_create(
+                    response={
+                        "instructions": "Use the tool result just returned and answer concisely in speech.",
+                    },
+                )
+
+            # Re-synchronize the head wobble after a tool call that may have taken some time
+            if self.deps.head_wobbler is not None:
+                self.deps.head_wobbler.reset()
+
+        except ConnectionClosedError:
+            logger.warning("Connection closed while sending tool result")
+            self.connection = None
+            self._response_done_event.set()
+
+    async def _run_realtime_session(self) -> None:
+        """Establish and manage a single realtime session."""
+        async with self.client.realtime.connect(model=config.MODEL_NAME) as conn:
+            try:
+                await conn.session.update(
+                    session={
+                        "type": "realtime",
+                        "instructions": get_session_instructions(),
+                        "audio": {
+                            "input": {
+                                "format": {
+                                    "type": "audio/pcm",
+                                    "rate": self.input_sample_rate,
+                                },
+                                "transcription": {"model": "gpt-4o-transcribe", "language": "en"},
+                                "turn_detection": {
+                                    "type": "server_vad",
+                                    "interrupt_response": True,
+                                },
+                            },
+                            "output": {
+                                "format": {
+                                    "type": "audio/pcm",
+                                    "rate": self.output_sample_rate,
+                                },
+                                "voice": get_session_voice(),
+                            },
+                        },
+                        "tools": get_tool_specs(),  # type: ignore[typeddict-item]
+                        "tool_choice": "auto",
+                    },
+                )
+                logger.info(
+                    "Realtime session initialized with profile=%r voice=%r",
+                    getattr(config, "REACHY_MINI_CUSTOM_PROFILE", None),
+                    get_session_voice(),
+                )
+                # If we reached here, the session update succeeded which implies the API key worked.
+                # Persist the key to a newly created .env (copied from .env.example) if needed.
+                self._persist_api_key_if_needed()
+            except Exception:
+                logger.exception("Realtime session.update failed; aborting startup")
+                return
+
+            logger.info("Realtime session updated successfully")
+
+            # Manage event received from the openai server
+            self.connection = conn
+            try:
+                self._connected_event.set()
+            except Exception:
+                pass
+
+
+            response_sender_task: asyncio.Task[None] | None = None
+            try:
+                # Start the background tool manager
+                self.tool_manager.start_up(tool_callbacks=[self._handle_tool_result])
+
+                # Start the response sender worker
+                response_sender_task = asyncio.create_task(
+                    self._response_sender_loop(), name="response-sender"
+                )
+
+                async for event in self.connection:
+                    logger.debug(f"OpenAI event: {event.type}")
+                    if event.type == "input_audio_buffer.speech_started":
+                        if hasattr(self, "_clear_queue") and callable(self._clear_queue):
+                            self._clear_queue()
+                        if self.deps.head_wobbler is not None:
+                            self.deps.head_wobbler.reset()
+                        self.deps.movement_manager.set_listening(True)
+                        logger.debug("User speech started")
+
+                    if event.type == "input_audio_buffer.speech_stopped":
+                        self.deps.movement_manager.set_listening(False)
+                        logger.debug("User speech stopped - server will auto-commit with VAD")
+
+                    if event.type in (
+                        "response.audio.done",  # GA
+                        "response.output_audio.done",  # GA alias
+                        "response.audio.completed",  # legacy (for safety)
+                        "response.completed",  # text-only completion
+                    ):
+                        logger.debug("response completed")
+
+                    if event.type == "response.created":
+                        self._response_done_event.clear()
+                        logger.debug("Response created (active)")
+
+                    if event.type == "response.done":
+                        # Doesn't mean the audio is done playing
+                        self._response_done_event.set()
+                        logger.debug("Response done")
+
+                        response = getattr(event, "response", None)
+                        usage = getattr(response, "usage", None) if response else None
+                        if usage:
+                            cost = _compute_response_cost(usage)
+                            self.cumulative_cost += cost
+                            logger.debug("Cost: $%.4f | Cumulative: $%.4f", cost, self.cumulative_cost)
+                        else:
+                            logger.warning("No usage data available for cost tracking")
+
+                    # Handle partial transcription (user speaking in real-time)
+                    if event.type == "conversation.item.input_audio_transcription.partial":
+                        logger.debug(f"User partial transcript: {event.transcript}")
+
+                        # Increment sequence
+                        self.partial_transcript_sequence += 1
+                        current_sequence = self.partial_transcript_sequence
+
+                        # Cancel previous debounce task if it exists
+                        if self.partial_transcript_task and not self.partial_transcript_task.done():
+                            self.partial_transcript_task.cancel()
+                            try:
+                                await self.partial_transcript_task
+                            except asyncio.CancelledError:
+                                pass
+
+                        # Start new debounce timer with sequence number
+                        self.partial_transcript_task = asyncio.create_task(
+                            self._emit_debounced_partial(event.transcript, current_sequence)
+                        )
+
+                    # Handle completed transcription (user finished speaking)
+                    if event.type == "conversation.item.input_audio_transcription.completed":
+                        logger.debug(f"User transcript: {event.transcript}")
+
+                        # Cancel any pending partial emission
+                        if self.partial_transcript_task and not self.partial_transcript_task.done():
+                            self.partial_transcript_task.cancel()
+                            try:
+                                await self.partial_transcript_task
+                            except asyncio.CancelledError:
+                                pass
+
+                        await self.output_queue.put(AdditionalOutputs({"role": "user", "content": event.transcript}))
+
+                    # Handle assistant transcription
+                    if event.type in ("response.audio_transcript.done", "response.output_audio_transcript.done"):
+                        logger.debug(f"Assistant transcript: {event.transcript}")
+                        await self.output_queue.put(AdditionalOutputs({"role": "assistant", "content": event.transcript}))
+
+                    # Handle audio delta
+                    if event.type in ("response.audio.delta", "response.output_audio.delta"):
+                        if self.deps.head_wobbler is not None:
+                            self.deps.head_wobbler.feed(event.delta)
+                        self.last_activity_time = asyncio.get_event_loop().time()
+                        logger.debug("last activity time updated to %s", self.last_activity_time)
+                        await self.output_queue.put(
+                            (
+                                self.output_sample_rate,
+                                np.frombuffer(base64.b64decode(event.delta), dtype=np.int16).reshape(1, -1),
+                            ),
+                        )
+
+                    # ---- tool-calling plumbing ----
+                    if event.type == "response.function_call_arguments.done":
+                        tool_name = getattr(event, "name", None)
+                        args_json_str = getattr(event, "arguments", None)
+                        call_id: str = str(getattr(event, "call_id", uuid.uuid4()))
+
+                        logger.info(
+                            "Tool call received — tool_name=%r, call_id=%s, is_idle=%s, args=%s",
+                            tool_name, call_id, self.is_idle_tool_call, args_json_str,
+                        )
+
+                        if not isinstance(tool_name, str) or not isinstance(args_json_str, str):
+                            logger.error(
+                                "Invalid tool call: tool_name=%s (type=%s), args=%s (type=%s), call_id=%s",
+                                tool_name, type(tool_name).__name__,
+                                args_json_str, type(args_json_str).__name__,
+                                call_id,
+                            )
+                            continue
+
+                        bg_tool = await self.tool_manager.start_tool(
+                            call_id=call_id,
+                            tool_call_routine=ToolCallRoutine(
+                                tool_name=tool_name,
+                                args_json_str=args_json_str,
+                                deps=self.deps,
+                            ),
+                            is_idle_tool_call=self.is_idle_tool_call,
+                        )
+
+                        await self.output_queue.put(
+                            AdditionalOutputs(
+                                {
+                                    "role": "assistant",
+                                    "content": f"🛠️ Used tool {tool_name} with args {args_json_str}. The tool is now running. Tool ID: {bg_tool.tool_id}",
+                                },
+                            ),
+                        )
+
+                        if self.is_idle_tool_call:
+                            self.is_idle_tool_call = False
+                        else:
+                            await self._safe_response_create(
+                                response={
+                                    "instructions": "Notify what the tool has been running giving meaningful information about the task",
+                                },
+                            )
+
+                        logger.info("Started background tool: %s (id=%s, call_id=%s)", tool_name, bg_tool.tool_id, call_id)
+
+                    # server error
+                    if event.type == "error":
+                        err = getattr(event, "error", None)
+                        msg = getattr(err, "message", str(err) if err else "unknown error")
+                        code = getattr(err, "code", "")
+
+                        if code == "conversation_already_has_active_response":
+                            # response.create was rejected.  The sender worker
+                            # is waiting on _response_done_event; when the active
+                            # response finishes it will wake up and see this flag.
+                            self._last_response_rejected = True
+                            logger.debug("response.create rejected; worker will retry after active response finishes")
+                        else:
+                            logger.error("Realtime error [%s]: %s (raw=%s)", code, msg, err)
+
+                        # Only show user-facing errors, not internal state errors
+                        if code not in ("input_audio_buffer_commit_empty",):
+                            await self.output_queue.put(
+                                AdditionalOutputs({"role": "assistant", "content": f"[error] {msg}"})
+                            )
+            finally:
+                # Stop the response sender worker.
+                if response_sender_task is not None:
+                    response_sender_task.cancel()
+                    try:
+                        await response_sender_task
+                    except asyncio.CancelledError:
+                        pass
+
+                # Stop background tool manager tasks (listener + cleanup) in all patus.
+                await self.tool_manager.shutdown()
+
+    # Microphone receive
+    async def receive(self, frame: Tuple[int, NDArray[np.int16]]) -> None:
+        """Receive audio frame from the microphone and send it to the OpenAI server.
+
+        Handles both mono and stereo audio formats, converting to the expected
+        mono format for OpenAI's API. Resamples if the input sample rate differs
+        from the expected rate.
+
+        Args:
+            frame: A tuple containing (sample_rate, audio_data).
+
+        """
+        if not self.connection:
+            return
+
+        input_sample_rate, audio_frame = frame
+
+        # Reshape if needed
+        if audio_frame.ndim == 2:
+            # Scipy channels last convention
+            if audio_frame.shape[1] > audio_frame.shape[0]:
+                audio_frame = audio_frame.T
+            # Multiple channels -> Mono channel
+            if audio_frame.shape[1] > 1:
+                audio_frame = audio_frame[:, 0]
+
+        # Resample if needed
+        if self.input_sample_rate != input_sample_rate:
+            audio_frame = resample(audio_frame, int(len(audio_frame) * self.input_sample_rate / input_sample_rate))
+
+        # Cast if needed
+        audio_frame = audio_to_int16(audio_frame)
+
+        # Send to OpenAI (guard against races during reconnect)
+        try:
+            audio_message = base64.b64encode(audio_frame.tobytes()).decode("utf-8")
+            await self.connection.input_audio_buffer.append(audio=audio_message)
+        except Exception as e:
+            logger.debug("Dropping audio frame: connection not ready (%s)", e)
+            return
+
+    async def emit(self) -> Tuple[int, NDArray[np.int16]] | AdditionalOutputs | None:
+        """Emit audio frame to be played by the speaker."""
+        # sends to the stream the stuff put in the output queue by the openai event handler
+        # This is called periodically by the fastrtc Stream
+
+        # Handle idle
+        idle_duration = asyncio.get_event_loop().time() - self.last_activity_time
+        if idle_duration > 15.0 and self.deps.movement_manager.is_idle():
+            try:
+                await self.send_idle_signal(idle_duration)
+            except Exception as e:
+                logger.warning("Idle signal skipped (connection closed?): %s", e)
+                return None
+
+            self.last_activity_time = asyncio.get_event_loop().time()  # avoid repeated resets
+
+        return await wait_for_item(self.output_queue)  # type: ignore[no-any-return]
+
+    async def shutdown(self) -> None:
+        """Shutdown the handler."""
+        self._shutdown_requested = True
+
+        # Unblock the response sender worker so it can exit
+        self._response_done_event.set()
+
+        # Stop background tool manager tasks (listener + cleanup)
+        await self.tool_manager.shutdown()
+
+        # Cancel any pending debounce task
+        if self.partial_transcript_task and not self.partial_transcript_task.done():
+            self.partial_transcript_task.cancel()
+            try:
+                await self.partial_transcript_task
+            except asyncio.CancelledError:
+                pass
+
+        if self.connection:
+            try:
+                await self.connection.close()
+            except ConnectionClosedError as e:
+                logger.debug(f"Connection already closed during shutdown: {e}")
+            except Exception as e:
+                logger.debug(f"connection.close() ignored: {e}")
+            finally:
+                self.connection = None
+
+        # Clear any remaining items in the output queue
+        while not self.output_queue.empty():
+            try:
+                self.output_queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+
+    def format_timestamp(self) -> str:
+        """Format current timestamp with date, time, and elapsed seconds."""
+        loop_time = asyncio.get_event_loop().time()  # monotonic
+        elapsed_seconds = loop_time - self.start_time
+        dt = datetime.now()  # wall-clock
+        return f"[{dt.strftime('%Y-%m-%d %H:%M:%S')} | +{elapsed_seconds:.1f}s]"
+
+    async def get_available_voices(self) -> list[str]:
+        """Try to discover available voices for the configured realtime model.
+
+        Attempts to retrieve model metadata from the OpenAI Models API and look
+        for any keys that might contain voice names. Falls back to a curated
+        list known to work with realtime if discovery fails.
+        """
+        # Conservative fallback list with default first
+        fallback = [
+            "cedar",
+            "alloy",
+            "aria",
+            "ballad",
+            "verse",
+            "sage",
+            "coral",
+        ]
+        try:
+            # Best effort discovery; safe-guarded for unexpected shapes
+            model = await self.client.models.retrieve(config.MODEL_NAME)
+            # Try common serialization paths
+            raw = None
+            for attr in ("model_dump", "to_dict"):
+                fn = getattr(model, attr, None)
+                if callable(fn):
+                    try:
+                        raw = fn()
+                        break
+                    except Exception:
+                        pass
+            if raw is None:
+                try:
+                    raw = dict(model)
+                except Exception:
+                    raw = None
+            # Scan for voice candidates
+            candidates: set[str] = set()
+
+            def _collect(obj: object) -> None:
+                try:
+                    if isinstance(obj, dict):
+                        for k, v in obj.items():
+                            kl = str(k).lower()
+                            if "voice" in kl and isinstance(v, (list, tuple)):
+                                for item in v:
+                                    if isinstance(item, str):
+                                        candidates.add(item)
+                                    elif isinstance(item, dict) and "name" in item and isinstance(item["name"], str):
+                                        candidates.add(item["name"])
+                            else:
+                                _collect(v)
+                    elif isinstance(obj, (list, tuple)):
+                        for it in obj:
+                            _collect(it)
+                except Exception:
+                    pass
+
+            if isinstance(raw, dict):
+                _collect(raw)
+            # Ensure default present and stable order
+            voices = sorted(candidates) if candidates else fallback
+            if "cedar" not in voices:
+                voices = ["cedar", *[v for v in voices if v != "cedar"]]
+            return voices
+        except Exception:
+            return fallback
+
+    async def send_idle_signal(self, idle_duration: float) -> None:
+        """Send an idle signal to the openai server."""
+        logger.debug("Sending idle signal")
+        self.is_idle_tool_call = True
+        timestamp_msg = f"[Idle time update: {self.format_timestamp()} - No activity for {idle_duration:.1f}s] You've been idle for a while. Feel free to get creative - dance, show an emotion, look around, do nothing, or just be yourself!"
+        if not self.connection:
+            logger.debug("No connection, cannot send idle signal")
+            return
+        await self.connection.conversation.item.create(
+            item={
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": timestamp_msg}],
+            },
+        )
+        await self._safe_response_create(
+            response={
+                "instructions": "You MUST respond with function calls only - no speech or text. Choose appropriate actions for idle behavior.",
+                "tool_choice": "required",
+            },
+        )
+
+    def _persist_api_key_if_needed(self) -> None:
+        """Persist the API key into `.env` inside `instance_path/` when appropriate.
+
+        - Only runs in Gradio mode when key came from the textbox and is non-empty.
+        - Only saves if `self.instance_path` is not None.
+        - Writes `.env` to `instance_path/.env` (does not overwrite if it already exists).
+        - If `instance_path/.env.example` exists, copies its contents while overriding OPENAI_API_KEY.
+        """
+        try:
+            if not self.gradio_mode:
+                logger.warning("Not in Gradio mode; skipping API key persistence.")
+                return
+
+            if self._key_source != "textbox":
+                logger.info("API key not provided via textbox; skipping persistence.")
+                return
+
+            key = (self._provided_api_key or "").strip()
+            if not key:
+                logger.warning("No API key provided via textbox; skipping persistence.")
+                return
+            if self.instance_path is None:
+                logger.warning("Instance path is None; cannot persist API key.")
+                return
+
+            # Update the current process environment for downstream consumers
+            try:
+                import os
+
+                os.environ["OPENAI_API_KEY"] = key
+            except Exception:  # best-effort
+                pass
+
+            target_dir = Path(self.instance_path)
+            env_path = target_dir / ".env"
+            if env_path.exists():
+                # Respect existing user configuration
+                logger.info(".env already exists at %s; not overwriting.", env_path)
+                return
+
+            example_path = target_dir / ".env.example"
+            content_lines: list[str] = []
+            if example_path.exists():
+                try:
+                    content = example_path.read_text(encoding="utf-8")
+                    content_lines = content.splitlines()
+                except Exception as e:
+                    logger.warning("Failed to read .env.example at %s: %s", example_path, e)
+
+            # Replace or append the OPENAI_API_KEY line
+            replaced = False
+            for i, line in enumerate(content_lines):
+                if line.strip().startswith("OPENAI_API_KEY="):
+                    content_lines[i] = f"OPENAI_API_KEY={key}"
+                    replaced = True
+                    break
+            if not replaced:
+                content_lines.append(f"OPENAI_API_KEY={key}")
+
+            # Ensure file ends with newline
+            final_text = "\n".join(content_lines) + "\n"
+            env_path.write_text(final_text, encoding="utf-8")
+            logger.info("Created %s and stored OPENAI_API_KEY for future runs.", env_path)
+        except Exception as e:
+            # Never crash the app for QoL persistence; just log.
+            logger.warning("Could not persist OPENAI_API_KEY to .env: %s", e)

src/hello_world/profiles/__init__.py

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

src/hello_world/profiles/_hello_world_locked_profile/custom_tool.py

@@ -0,0 +1,38 @@
+"""Custom tool template - modify this to create your own tools."""
+
+import logging
+from typing import Any
+
+from hello_world.tools.core_tools import Tool, ToolDependencies
+
+logger = logging.getLogger(__name__)
+
+
+class CustomTool(Tool):
+    """A custom tool template. Modify this to create your own tool."""
+
+    name = "custom_tool"
+    description = "A placeholder custom tool - replace this with your own implementation"
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "message": {
+                "type": "string",
+                "description": "An optional message to log",
+            },
+        },
+        "required": [],
+    }
+
+    async def __call__(self, deps: ToolDependencies, **kwargs: Any) -> dict[str, Any]:
+        """Execute the custom tool."""
+        message = kwargs.get("message", "no message")
+        logger.info(f"CustomTool called with message: {message}")
+
+        # TODO: Add your custom logic here
+        # You have access to:
+        # - deps.reachy_mini: the robot SDK
+        # - deps.movement_manager: for queueing movements
+        # - deps.state: current conversation state
+
+        return {"status": "ok"}

src/hello_world/profiles/_hello_world_locked_profile/instructions.txt

@@ -0,0 +1,3 @@
+You are a helpful assistant controlling a Reachy Mini robot.
+You love talking about the Eiffel Tower.
+You can do a look around you using the 'sweep_look' tool.

src/hello_world/profiles/_hello_world_locked_profile/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 hello_world.tools.core_tools import Tool, ToolDependencies
+from hello_world.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/hello_world/profiles/_hello_world_locked_profile/tools.txt

@@ -0,0 +1,18 @@
+# Available tools for this profile, remove comments to activate them
+# or use 'all' to enable all built-in tools
+
+dance
+stop_dance
+play_emotion
+stop_emotion
+#camera
+#do_nothing
+#head_tracking
+#move_head
+
+# You can also add custom tools defined in this profile folder
+# see custom_tool.py for an example
+
+# Uncomment the following line to enable the custom tool template:
+#custom_tool
+sweep_look

src/hello_world/prompts.py

@@ -0,0 +1,110 @@
+import re
+import sys
+import logging
+from pathlib import Path
+
+from hello_world.config import DEFAULT_PROFILES_DIRECTORY, config
+
+
+logger = logging.getLogger(__name__)
+
+
+PROMPTS_LIBRARY_DIRECTORY = Path(__file__).parent / "prompts"
+INSTRUCTIONS_FILENAME = "instructions.txt"
+VOICE_FILENAME = "voice.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:
+        if config.PROFILES_DIRECTORY != DEFAULT_PROFILES_DIRECTORY:
+            logger.info(
+                "Loading prompt from external profile '%s' (root=%s)",
+                profile,
+                config.PROFILES_DIRECTORY,
+            )
+        else:
+            logger.info(f"Loading prompt from profile '{profile}'")
+        instructions_file = config.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)
+
+
+def get_session_voice(default: str = "cedar") -> str:
+    """Resolve the voice to use for the session.
+
+    If a custom profile is selected and contains a voice.txt, return its
+    trimmed content; otherwise return the provided default ("cedar").
+    """
+    profile = config.REACHY_MINI_CUSTOM_PROFILE
+    if not profile:
+        return default
+    try:
+        voice_file = config.PROFILES_DIRECTORY / profile / VOICE_FILENAME
+        if voice_file.exists():
+            voice = voice_file.read_text(encoding="utf-8").strip()
+            return voice or default
+    except Exception:
+        pass
+    return default

src/hello_world/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/hello_world/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 speak English by default and switch languages only if explicitly told.
+
+## 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/hello_world/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/hello_world/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/hello_world/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/hello_world/static/index.html

@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hello World – Settings</title>
+    <link rel="stylesheet" href="/static/style.css" />
+  </head>
+  <body>
+    <div class="ambient"></div>
+    <div id="loading" class="loading">
+      <div class="spinner"></div>
+      <p>Loading…</p>
+    </div>
+    <div class="container">
+      <header class="hero">
+        <div class="pill">Headless control</div>
+        <h1>Hello World</h1>
+        <p class="subtitle">Configure your OpenAI API key for the conversation app.</p>
+      </header>
+
+      <div id="configured" class="panel hidden">
+        <div class="panel-heading">
+          <div>
+            <p class="eyebrow">Credentials</p>
+            <h2>API key ready</h2>
+          </div>
+          <span class="chip chip-ok">Connected</span>
+        </div>
+        <p class="muted">OpenAI API key is configured. The conversation app is ready to use.</p>
+        <button id="change-key-btn" class="ghost">Change API key</button>
+      </div>
+
+      <div id="form-panel" class="panel hidden">
+        <div class="panel-heading">
+          <div>
+            <p class="eyebrow">Credentials</p>
+            <h2>Connect OpenAI</h2>
+          </div>
+          <span class="chip">Required</span>
+        </div>
+        <p class="muted">Paste your API key once and we will store it locally for the conversation loop.</p>
+        <label for="api-key">OpenAI API Key</label>
+        <input id="api-key" type="password" placeholder="sk-..." autocomplete="off" />
+        <div class="actions">
+          <button id="save-btn">Save key</button>
+          <p id="status" class="status"></p>
+        </div>
+      </div>
+    </div>
+
+    <script src="/static/main.js"></script>
+  </body>
+</html>

src/hello_world/static/main.js

@@ -0,0 +1,136 @@
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function fetchWithTimeout(url, options = {}, timeoutMs = 2000) {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } finally {
+    clearTimeout(id);
+  }
+}
+
+async function waitForStatus(timeoutMs = 15000) {
+  const loadingText = document.querySelector("#loading p");
+  let attempts = 0;
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    attempts += 1;
+    try {
+      const url = new URL("/status", window.location.origin);
+      url.searchParams.set("_", Date.now().toString());
+      const resp = await fetchWithTimeout(url, {}, 2000);
+      if (resp.ok) return await resp.json();
+    } catch (e) {}
+    if (loadingText) {
+      loadingText.textContent = attempts > 8 ? "Starting backend…" : "Loading…";
+    }
+    if (Date.now() >= deadline) return null;
+    await sleep(500);
+  }
+}
+
+async function validateKey(key) {
+  const body = { openai_api_key: key };
+  const resp = await fetch("/validate_api_key", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await resp.json().catch(() => ({}));
+  if (!resp.ok) {
+    throw new Error(data.error || "validation_failed");
+  }
+  return data;
+}
+
+async function saveKey(key) {
+  const body = { openai_api_key: key };
+  const resp = await fetch("/openai_api_key", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    const data = await resp.json().catch(() => ({}));
+    throw new Error(data.error || "save_failed");
+  }
+  return await resp.json();
+}
+
+function show(el, flag) {
+  el.classList.toggle("hidden", !flag);
+}
+
+async function init() {
+  const loading = document.getElementById("loading");
+  const statusEl = document.getElementById("status");
+  const formPanel = document.getElementById("form-panel");
+  const configuredPanel = document.getElementById("configured");
+  const saveBtn = document.getElementById("save-btn");
+  const changeKeyBtn = document.getElementById("change-key-btn");
+  const input = document.getElementById("api-key");
+
+  show(loading, true);
+  show(formPanel, false);
+  show(configuredPanel, false);
+
+  const st = (await waitForStatus()) || { has_key: false };
+
+  if (st.has_key) {
+    show(configuredPanel, true);
+  } else {
+    show(formPanel, true);
+  }
+  show(loading, false);
+
+  changeKeyBtn.addEventListener("click", () => {
+    show(configuredPanel, false);
+    show(formPanel, true);
+    input.value = "";
+    statusEl.textContent = "";
+    statusEl.className = "status";
+  });
+
+  input.addEventListener("input", () => {
+    input.classList.remove("error");
+  });
+
+  saveBtn.addEventListener("click", async () => {
+    const key = input.value.trim();
+    if (!key) {
+      statusEl.textContent = "Please enter a valid key.";
+      statusEl.className = "status warn";
+      input.classList.add("error");
+      return;
+    }
+    statusEl.textContent = "Validating API key...";
+    statusEl.className = "status";
+    input.classList.remove("error");
+    try {
+      const validation = await validateKey(key);
+      if (!validation.valid) {
+        statusEl.textContent = "Invalid API key. Please check your key and try again.";
+        statusEl.className = "status error";
+        input.classList.add("error");
+        return;
+      }
+      statusEl.textContent = "Key valid! Saving...";
+      statusEl.className = "status ok";
+      await saveKey(key);
+      statusEl.textContent = "Saved. Reloading…";
+      statusEl.className = "status ok";
+      window.location.reload();
+    } catch (e) {
+      input.classList.add("error");
+      if (e.message === "invalid_api_key") {
+        statusEl.textContent = "Invalid API key. Please check your key and try again.";
+      } else {
+        statusEl.textContent = "Failed to validate/save key. Please try again.";
+      }
+      statusEl.className = "status error";
+    }
+  });
+}
+
+window.addEventListener("DOMContentLoaded", init);

src/hello_world/static/style.css

@@ -0,0 +1,210 @@
+:root {
+  --bg: #060b1a;
+  --bg-2: #071023;
+  --panel: rgba(11, 18, 36, 0.8);
+  --border: rgba(255, 255, 255, 0.08);
+  --text: #eaf2ff;
+  --muted: #9fb6d7;
+  --ok: #4ce0b3;
+  --warn: #ffb547;
+  --error: #ff5c70;
+  --accent: #45c4ff;
+  --accent-2: #5ef0c1;
+  --shadow: 0 20px 70px rgba(0, 0, 0, 0.45);
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: "Space Grotesk", "Inter", "Segoe UI", sans-serif;
+  background: radial-gradient(circle at 20% 20%, rgba(69, 196, 255, 0.16), transparent 35%),
+              radial-gradient(circle at 80% 0%, rgba(94, 240, 193, 0.16), transparent 32%),
+              linear-gradient(135deg, var(--bg), var(--bg-2));
+  color: var(--text);
+}
+
+.ambient {
+  position: fixed;
+  inset: 0;
+  background: radial-gradient(circle at 30% 60%, rgba(255, 255, 255, 0.05), transparent 35%),
+              radial-gradient(circle at 75% 30%, rgba(69, 196, 255, 0.08), transparent 32%);
+  filter: blur(60px);
+  z-index: 0;
+  pointer-events: none;
+}
+
+.loading {
+  position: fixed;
+  inset: 0;
+  background: rgba(5, 10, 24, 0.92);
+  backdrop-filter: blur(4px);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  z-index: 9999;
+}
+.loading .spinner {
+  width: 46px;
+  height: 46px;
+  border: 4px solid rgba(255,255,255,0.15);
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+  margin-bottom: 12px;
+}
+.loading p { color: var(--muted); margin: 0; letter-spacing: 0.4px; }
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.container {
+  position: relative;
+  max-width: 600px;
+  margin: 10vh auto;
+  padding: 0 24px 40px;
+  z-index: 1;
+}
+
+.hero {
+  margin-bottom: 24px;
+}
+.hero h1 {
+  margin: 6px 0 6px;
+  font-size: 32px;
+  letter-spacing: -0.4px;
+}
+.subtitle {
+  margin: 0;
+  color: var(--muted);
+  line-height: 1.5;
+}
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 12px;
+  border-radius: 999px;
+  background: rgba(94, 240, 193, 0.1);
+  color: var(--accent-2);
+  font-size: 12px;
+  letter-spacing: 0.3px;
+  border: 1px solid rgba(94, 240, 193, 0.25);
+}
+
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  padding: 18px 18px 16px;
+  box-shadow: var(--shadow);
+  backdrop-filter: blur(10px);
+  margin-top: 16px;
+}
+.panel-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 8px;
+}
+.panel-heading h2 {
+  margin: 2px 0;
+  font-size: 22px;
+}
+.eyebrow {
+  margin: 0;
+  text-transform: uppercase;
+  font-size: 11px;
+  letter-spacing: 0.5px;
+  color: var(--muted);
+}
+.muted { color: var(--muted); }
+.chip {
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 10px;
+  border-radius: 999px;
+  font-size: 12px;
+  color: var(--text);
+  background: rgba(255, 255, 255, 0.08);
+  border: 1px solid var(--border);
+}
+.chip-ok {
+  background: rgba(76, 224, 179, 0.15);
+  color: var(--ok);
+  border-color: rgba(76, 224, 179, 0.4);
+}
+
+.hidden { display: none; }
+label {
+  display: block;
+  margin: 8px 0 6px;
+  font-size: 13px;
+  color: var(--muted);
+  letter-spacing: 0.2px;
+}
+input[type="password"],
+input[type="text"] {
+  width: 100%;
+  padding: 12px 14px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: rgba(255, 255, 255, 0.04);
+  color: var(--text);
+  transition: border 0.15s ease, box-shadow 0.15s ease;
+}
+input:focus {
+  border-color: rgba(94, 240, 193, 0.7);
+  outline: none;
+  box-shadow: 0 0 0 3px rgba(94, 240, 193, 0.15);
+}
+input.error {
+  border-color: var(--error);
+  box-shadow: 0 0 0 3px rgba(255, 92, 112, 0.15);
+}
+
+button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-top: 12px;
+  padding: 11px 16px;
+  border: none;
+  border-radius: 10px;
+  background: linear-gradient(120deg, var(--accent), var(--accent-2));
+  color: #031022;
+  cursor: pointer;
+  font-weight: 600;
+  letter-spacing: 0.2px;
+  box-shadow: 0 14px 40px rgba(69, 196, 255, 0.25);
+  transition: transform 0.12s ease, filter 0.12s ease, box-shadow 0.12s ease;
+}
+button:hover { filter: brightness(1.06); transform: translateY(-1px); }
+button:active { transform: translateY(0); }
+button.ghost {
+  background: rgba(255, 255, 255, 0.05);
+  color: var(--text);
+  box-shadow: none;
+  border: 1px solid var(--border);
+}
+button.ghost:hover { border-color: rgba(94, 240, 193, 0.4); }
+.actions {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.status {
+  margin: 0;
+  color: var(--muted);
+  font-size: 13px;
+}
+.status.ok { color: var(--ok); }
+.status.warn { color: var(--warn); }
+.status.error { color: var(--error); }
+
+@media (max-width: 760px) {
+  .hero h1 { font-size: 26px; }
+  button { width: 100%; justify-content: center; }
+  .actions { flex-direction: column; align-items: flex-start; }
+}

src/hello_world/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/hello_world/tools/background_tool_manager.py

@@ -0,0 +1,412 @@
+"""Background tool orchestrator for non-blocking tool execution.
+
+Allows tools to run long operations asynchronously while the robot
+continues conversing. Tools can be tracked, cancelled, and their
+completion is announced vocally via a silent notification queue.
+"""
+
+from __future__ import annotations
+import time
+import asyncio
+import logging
+from typing import Any, Dict, Callable, Optional, Coroutine
+
+from pydantic import Field, BaseModel, PrivateAttr
+
+from hello_world.tools.core_tools import (
+    ToolDependencies,
+    dispatch_tool_call,
+    dispatch_tool_call_with_manager,
+)
+from hello_world.tools.tool_constants import ToolState, SystemTool
+
+
+logger = logging.getLogger(__name__)
+
+_SYSTEM_TOOL_NAMES: set[str] = {t.value for t in SystemTool}
+
+class ToolProgress(BaseModel):
+    """Progress of a background tool."""
+
+    """the progress of the tool"""
+    progress: float = Field(..., ge=0.0, le=1.0)
+
+    """the message of the tool"""
+    message: Optional[str] = None
+
+
+class ToolCallRoutine(BaseModel):
+    """Encapsulates an async callable with its arguments for deferred execution."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    """the name of the tool"""
+    tool_name: str
+
+    """the JSON arguments for the tool call"""
+    args_json_str: str
+
+    """the dependencies for the tool call"""
+    deps: "ToolDependencies"
+
+    async def __call__(self, tool_manager: BackgroundToolManager) -> Any:
+        """Execute the stored callable with its arguments."""
+        if self.tool_name in _SYSTEM_TOOL_NAMES:
+            # For safety purposes, we only allow system tools to be called with the tool manager
+            return await dispatch_tool_call_with_manager(tool_name=self.tool_name, args_json=self.args_json_str, deps=self.deps, tool_manager=tool_manager)
+        return await dispatch_tool_call(tool_name=self.tool_name, args_json=self.args_json_str, deps=self.deps)
+
+
+class ToolNotification(BaseModel):
+    """Notification payload for completed tools."""
+
+    """the ID of the tool"""
+    id: str
+
+    """the name of the tool"""
+    tool_name: str
+
+    """whether the tool call was triggered by an idle signal"""
+    is_idle_tool_call: bool
+
+    """the status of the tool"""
+    status: ToolState
+
+    """the result of the tool"""
+    result: Optional[Dict[str, Any]] = None
+
+    """the error of the tool"""
+    error: Optional[str] = None
+
+
+class BackgroundTool(ToolNotification):
+    """Represents a background tool."""
+
+    """the progress of the tool"""
+    progress: Optional[ToolProgress] = None
+
+    """the start time of the tool"""
+    started_at: float = Field(default_factory=time.monotonic)
+
+    """the completion time of the tool"""
+    completed_at: Optional[float] = None
+
+    """the async tool execution task"""
+    _task: Optional[asyncio.Task[None]] = PrivateAttr(default=None)
+
+    @property
+    def tool_id(self) -> str:
+        """Get the name of the tool."""
+        return f"{self.tool_name}-{self.id}-{self.started_at}"
+
+    def get_notification(self) -> ToolNotification:
+        """Get the notification for the tool."""
+        return ToolNotification(
+            id=self.id,
+            tool_name=self.tool_name,
+            is_idle_tool_call=self.is_idle_tool_call,
+            status=self.status,
+            result=self.result,
+            error=self.error,
+        )
+
+
+class BackgroundToolManager(BaseModel):
+    """Manages background tools for non-blocking tool execution.
+
+    Features:
+    - Start async tools without blocking the conversation
+    - Track tool status and progress
+    - Cancel running tools
+
+    """
+
+    """the dictionary of tools"""
+    _tools: Dict[str, BackgroundTool] = PrivateAttr(default_factory=dict)
+
+    """the async queue for notifications"""
+    _notification_queue: asyncio.Queue[ToolNotification] = PrivateAttr(default_factory=asyncio.Queue)
+
+    """the event loop"""
+    _loop: Optional[asyncio.AbstractEventLoop] = PrivateAttr(default=None)
+
+    """internal lifecycle tasks (notification listener, periodic cleanup)"""
+    _lifecycle_tasks: list[asyncio.Task[None]] = PrivateAttr(default_factory=list)
+
+    """the maximum duration of a tool execution in seconds (default: 1 day)"""
+    _max_tool_duration_seconds: float = PrivateAttr(default=86400)
+
+    """the maximum time to keep a completed/failed/cancelled tool in memory (default: 1 hour)"""
+    _max_tool_memory_seconds: float = PrivateAttr(default=3600)
+
+    def set_loop(
+        self,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ) -> None:
+        """Set the event loop.
+
+        Args:
+            loop: The event loop (defaults to current running loop)
+
+        """
+        if loop is not None:
+            self._loop = loop
+        else:
+            try:
+                self._loop = asyncio.get_running_loop()
+            except RuntimeError:
+                self._loop = asyncio.new_event_loop()
+        logger.debug("BackgroundToolManager: event loop set")
+
+
+    async def start_tool(
+        self,
+        call_id: str,
+        tool_call_routine: ToolCallRoutine,
+        is_idle_tool_call: bool,
+        with_progress: bool = False,
+    ) -> BackgroundTool:
+        """Start a new background tool.
+
+        Args:
+            call_id: The ID of the tool
+            tool_call_routine: The ToolCallRoutine containing the callable and its arguments
+            with_progress: Whether to track progress (0.0-1.0)
+            is_idle_tool_call: Whether the tool call was triggered by an idle signal
+
+        Returns:
+            BackgroundTool object with tool ID
+
+        """
+        tool_name = tool_call_routine.tool_name
+        id = call_id
+        bg_tool = BackgroundTool(
+            id=id,
+            tool_name=tool_name,
+            is_idle_tool_call=is_idle_tool_call,
+            progress=ToolProgress(progress=0.0) if with_progress else None,
+            status=ToolState.RUNNING,
+        )
+        self._tools[bg_tool.tool_id] = bg_tool
+
+        async_task = asyncio.create_task(
+            self._run_tool(bg_tool, tool_call_routine),
+            name=f"bg-{tool_name}-{id}",
+        )
+        bg_tool._task = async_task
+
+        logger.info(f"Started background tool: {bg_tool.tool_name} (id={id})")
+
+        return bg_tool
+
+    async def _run_tool(
+        self,
+        bg_tool: BackgroundTool,
+        tool_call_routine: ToolCallRoutine,
+    ) -> None:
+        """Execute the tool and handle completion."""
+        result: dict[str, Any] = await tool_call_routine(self)
+        bg_tool.completed_at = time.monotonic()
+        error = result.get("error")
+
+        if error is not None:
+            if error == "Tool cancelled":
+                bg_tool.status = ToolState.CANCELLED
+                logger.debug(f"Background tool cancelled: {bg_tool.tool_name} (id={bg_tool.id})")
+            else:
+                bg_tool.status = ToolState.FAILED
+                logger.debug(f"Background tool failed: {bg_tool.tool_name} (id={bg_tool.id}): {bg_tool.error}")
+            bg_tool.error = result["error"]
+
+        else:
+            bg_tool.result = result
+            bg_tool.status = ToolState.COMPLETED
+            logger.debug(f"Background tool completed: {bg_tool.tool_name} (id={bg_tool.id})")
+
+        await self._notification_queue.put(bg_tool.get_notification())
+        logger.debug(f"Queued notification for tool: {bg_tool.tool_name} (id={bg_tool.id})")
+
+    async def update_progress(
+        self,
+        tool_id: str,
+        progress: float,
+        message: Optional[str] = None,
+    ) -> bool:
+        """Update progress for a tool (for tools with with_progress=True).
+
+        Args:
+            tool_id: The tool ID
+            progress: Progress value between 0.0 and 1.0
+            message: Optional progress message (e.g., "50% downloaded")
+
+        Returns:
+            True if updated successfully, False if tool not found or not tracking progress
+
+        """
+        tool = self._tools.get(tool_id)
+        if tool is None:
+            return False
+
+        if tool.progress is None:
+            # Tool not tracking progress
+            return False
+
+        tool.progress = ToolProgress(progress=max(0.0, min(1.0, progress)), message=message)
+        logger.debug(f"Tool {tool_id} progress: {progress:.1%} - {message or ''}")
+        return True
+
+    async def cancel_tool(self, tool_id: str, log: bool = True) -> bool:
+        """Cancel a running tool by ID.
+
+        Args:
+            tool_id: The tool ID to cancel
+            log: Whether to log the cancellation
+
+        Returns:
+            True if cancelled, False if tool not found or not running
+
+        """
+        tool = self._tools.get(tool_id)
+        if tool is None:
+            if log:
+                logger.warning(f"Cannot cancel tool {tool_id}: not found")
+            return False
+
+        if tool.status != ToolState.RUNNING:
+            if log:
+                logger.warning(f"Cannot cancel tool {tool_id}: status is {tool.status.value}")
+            return True
+
+        if tool._task:
+            tool._task.cancel()
+            if log:
+                logger.info(f"Cancelled tool: {tool.tool_name} (id={tool_id})")
+            return True
+
+        return False
+
+    def start_up(self, tool_callbacks: list[Callable[[ToolNotification], Coroutine[Any, Any, None]]]) -> None:
+        """Start the background tool manager.
+
+        This method starts two concurrent tasks:
+        - _listener: Listens for completed BackgroundTool notifications and calls the callbacks.
+        - _cleanup: Cleans up completed/failed/cancelled tools that have been in memory for too long and times out tools that have been running too long.
+
+        Args:
+            tool_callbacks: A list of async or sync callables that receive the completed BackgroundTool notifications.
+
+        """
+        self.set_loop()
+
+        async def _listener() -> None:
+            while True:
+                bg_tool = await self._notification_queue.get()
+                for callback in tool_callbacks:
+                    await callback(bg_tool)
+
+        async def _cleanup(interval_seconds: float = 5 * 60) -> None:
+            while True:
+                await asyncio.sleep(interval_seconds)
+                await self.cleanup_tools()
+                await self.timeout_tools()
+
+        self._lifecycle_tasks = [
+            asyncio.create_task(_cleanup(), name="bg-tool-cleanup"),
+            asyncio.create_task(_listener(), name="bg-tool-listener-callback"),
+        ]
+
+        logger.info(
+            "BackgroundToolManager started. "
+            "Max tool execution duration: %s seconds (tools running longer will be auto-cancelled). "
+            "Max tool memory retention: %s seconds (completed/failed/cancelled tools older than this are purged).",
+            self._max_tool_duration_seconds, self._max_tool_memory_seconds,
+        )
+
+    async def shutdown(self) -> None:
+        """Cancel all background tasks (listener, cleanup) and running tools."""
+        for task in self._lifecycle_tasks:
+            task.cancel()
+        for task in self._lifecycle_tasks:
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+        self._lifecycle_tasks.clear()
+
+        for tool_id in list(self._tools):
+            await self.cancel_tool(tool_id, log=False)
+
+        logger.info("BackgroundToolManager shut down")
+
+    async def timeout_tools(self) -> int:
+        """Cancel tools that have been running too long.
+
+        Returns:
+            Number of tools cancelled
+
+        """
+        now = time.monotonic()
+        to_cancel = []
+
+        for tool_id, tool in self._tools.items():
+            if tool.status == ToolState.RUNNING:
+                if tool.started_at and (now - tool.started_at) > self._max_tool_duration_seconds:
+                    to_cancel.append(tool_id)
+
+        for tool_id in to_cancel:
+            await self.cancel_tool(tool_id)
+
+        if to_cancel:
+            logger.debug(f"Timed out {len(to_cancel)} tools")
+
+        return len(to_cancel)
+
+    async def cleanup_tools(self) -> int:
+        """Remove completed/failed/cancelled tools that have been in memory for too long.
+
+        Returns:
+            Number of tools removed
+
+        """
+        now = time.monotonic()
+        to_remove = []
+
+        for tool_id, tool in self._tools.items():
+            if tool.status in (ToolState.COMPLETED, ToolState.FAILED, ToolState.CANCELLED):
+                if tool.completed_at and (now - tool.completed_at) > self._max_tool_memory_seconds:
+                    to_remove.append(tool_id)
+
+        for tool_id in to_remove:
+            del self._tools[tool_id]
+
+        if to_remove:
+            logger.debug(f"Cleaned up {len(to_remove)} old tools")
+
+        return len(to_remove)
+
+    def get_tool(self, tool_id: str) -> Optional[BackgroundTool]:
+        """Get a tool by ID."""
+        return self._tools.get(tool_id)
+
+    def get_running_tools(self) -> list[BackgroundTool]:
+        """Get all currently running tools."""
+        return [t for t in self._tools.values() if t.status == ToolState.RUNNING]
+
+    def get_all_tools(self, limit: Optional[int] = None) -> list[BackgroundTool]:
+        """Get recent tools (most recent first).
+
+        Args:
+            limit: Maximum number of tools to return (None means all)
+
+        Returns:
+            List of tools sorted by start time (most recent first)
+
+        """
+        sorted_tools = sorted(
+            self._tools.values(),
+            key=lambda t: t.started_at,
+            reverse=True,
+        )
+        if limit is not None:
+            return sorted_tools[:limit]
+        return sorted_tools

src/hello_world/tools/camera.py

@@ -0,0 +1,68 @@
+import base64
+import asyncio
+import logging
+from typing import Any, Dict
+
+import cv2
+
+from hello_world.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"}
+            )
+
+        # Encode image directly to JPEG bytes without writing to file
+        success, buffer = cv2.imencode('.jpg', frame)
+        if not success:
+            raise RuntimeError("Failed to encode frame as JPEG")
+
+        b64_encoded = base64.b64encode(buffer.tobytes()).decode("utf-8")
+        return {"b64_im": b64_encoded}

src/hello_world/tools/core_tools.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+import re
+import abc
+import sys
+import json
+import asyncio
+import inspect
+import logging
+import importlib
+import importlib.util
+from typing import TYPE_CHECKING, Any, Dict, List
+from pathlib import Path
+from dataclasses import dataclass
+
+from reachy_mini import ReachyMini
+from hello_world.config import DEFAULT_PROFILES_DIRECTORY as DEFAULT_PROFILES_PATH  # noqa: F401
+
+# Import config to ensure .env is loaded before reading REACHY_MINI_CUSTOM_PROFILE
+from hello_world.config import config  # noqa: F401
+from hello_world.tools.tool_constants import SystemTool
+
+
+if TYPE_CHECKING:
+    from hello_world.tools.background_tool_manager import BackgroundToolManager
+
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_PROFILES_MODULE = "hello_world.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
+
+
+def _load_module_from_file(module_name: str, file_path: Path) -> None:
+    """Load a Python module from a file path."""
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    if not (spec and spec.loader):
+        raise ModuleNotFoundError(f"Cannot create spec for {file_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+
+def _try_load_tool(
+    tool_name: str,
+    module_path: str,
+    fallback_directory: Path | None,
+    file_subpath: str,
+) -> str:
+    """Try to load a tool: first via importlib, then from file if fallback is configured."""
+    try:
+        importlib.import_module(module_path)
+        return "module"
+    except ModuleNotFoundError:
+        if fallback_directory is None:
+            raise
+        tool_file = fallback_directory / file_subpath
+        if not tool_file.exists():
+            raise FileNotFoundError(f"tool file not found at {tool_file}")
+        _load_module_from_file(tool_name, tool_file)
+        return "file"
+
+
+def _format_error(error: Exception) -> str:
+    """Format an exception for logging."""
+    if isinstance(error, FileNotFoundError):
+        return f"Tool file not found: {error}"
+    if isinstance(error, ModuleNotFoundError):
+        return f"Missing dependency: {error}"
+    if isinstance(error, ImportError):
+        return f"Import error: {error}"
+    return f"{type(error).__name__}: {error}"
+
+
+# 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 = config.PROFILES_DIRECTORY / profile
+    tools_txt_path = profile_module_path / "tools.txt"
+    default_tools_txt_path = Path(__file__).parent.parent / "profiles" / "default" / "tools.txt"
+
+    if config.PROFILES_DIRECTORY != DEFAULT_PROFILES_PATH:
+        logger.info(
+            "Loading external profile '%s' from %s",
+            profile,
+            profile_module_path,
+        )
+
+    if not tools_txt_path.exists():
+        if profile != "default" and default_tools_txt_path.exists():
+            logger.warning(
+                "tools.txt not found for profile '%s' at %s. Falling back to default profile tools at %s",
+                profile,
+                tools_txt_path,
+                default_tools_txt_path,
+            )
+            tools_txt_path = default_tools_txt_path
+        else:
+            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)
+
+    # Add system tools
+    tool_names.extend({tool.value for tool in SystemTool})
+
+    logger.info(f"Found {len(tool_names)} tools to load: {tool_names}")
+
+    if config.AUTOLOAD_EXTERNAL_TOOLS and config.TOOLS_DIRECTORY and config.TOOLS_DIRECTORY.is_dir():
+        discovered_external_tools: List[str] = []
+        for tool_file in sorted(config.TOOLS_DIRECTORY.glob("*.py")):
+            if tool_file.name.startswith("_"):
+                continue
+            candidate_name = tool_file.stem
+            if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", candidate_name):
+                logger.warning("Skipping external tool with invalid name: %s", tool_file.name)
+                continue
+            discovered_external_tools.append(candidate_name)
+
+        extra_tools = [name for name in discovered_external_tools if name not in tool_names]
+        if extra_tools:
+            tool_names.extend(extra_tools)
+            logger.info(
+                "AUTOLOAD_EXTERNAL_TOOLS enabled: added %d external tool(s): %s",
+                len(extra_tools),
+                extra_tools,
+            )
+
+    for tool_name in tool_names:
+        loaded = False
+        profile_error = None
+        profile_import_path = f"{DEFAULT_PROFILES_MODULE}.{profile}.{tool_name}"
+
+        # Try profile tool first
+        try:
+            source = _try_load_tool(
+                tool_name,
+                module_path=profile_import_path,
+                fallback_directory=config.PROFILES_DIRECTORY,
+                file_subpath=f"{profile}/{tool_name}.py",
+            )
+            if source == "file":
+                logger.info("✓ Loaded external profile tool: %s", tool_name)
+            else:
+                logger.info("✓ Loaded core profile tool: %s", tool_name)
+            loaded = True
+        except (ModuleNotFoundError, FileNotFoundError) as e:
+            if tool_name not in str(e):
+                profile_error = _format_error(e)
+                logger.error(f"❌ Failed to load profile tool '{tool_name}': {profile_error}")
+                logger.error(f"  Module path: {profile_import_path}")
+        except Exception as e:
+            profile_error = _format_error(e)
+            logger.error(f"❌ Failed to load profile tool '{tool_name}': {profile_error}")
+            logger.error(f"  Module path: {profile_import_path}")
+
+        # Try tools directory if not found in profile
+        if not loaded:
+            shared_module_path = f"hello_world.tools.{tool_name}"
+            try:
+                source = _try_load_tool(
+                    tool_name,
+                    module_path=shared_module_path,
+                    fallback_directory=config.TOOLS_DIRECTORY,
+                    file_subpath=f"{tool_name}.py",
+                )
+                if source == "file":
+                    logger.info("✓ Loaded external tool: %s", tool_name)
+                else:
+                    logger.info("✓ Loaded core tool: %s", tool_name)
+            except (ModuleNotFoundError, FileNotFoundError):
+                if profile_error:
+                    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 Exception as e:
+                logger.error(f"❌ Failed to load shared tool '{tool_name}': {_format_error(e)}")
+                logger.error(f"  Module path: {shared_module_path}")
+
+
+
+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: Dict[str, Any], deps: ToolDependencies) -> Dict[str, Any]:
+    tool = ALL_TOOLS.get(tool_name)
+    if not tool:
+        return {"error": f"unknown tool: {tool_name}"}
+    try:
+        return await tool(deps, **args)
+    except asyncio.CancelledError:
+        logger.info("Tool cancelled: %s", tool_name)
+        return {"error": "Tool cancelled"}
+    except Exception as e:
+        msg = f"{type(e).__name__}: {e}"
+        logger.exception("Tool error in %s: %s", tool_name, msg)
+        return {"error": msg}
+
+
+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."""
+    return await _dispatch_tool_call(tool_name, _safe_load_obj(args_json), deps)
+
+
+async def dispatch_tool_call_with_manager(tool_name: str, args_json: str, deps: ToolDependencies, tool_manager: "BackgroundToolManager") -> Dict[str, Any]:
+    """Dispatch a tool call, injecting a BackgroundToolManager into the args."""
+    args = _safe_load_obj(args_json)
+    args["tool_manager"] = tool_manager
+    return await _dispatch_tool_call(tool_name, args, deps)

src/hello_world/tools/dance.py

@@ -0,0 +1,86 @@
+import logging
+from typing import Any, Dict
+
+from hello_world.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 hello_world.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
+                                        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/hello_world/tools/do_nothing.py

@@ -0,0 +1,30 @@
+import logging
+from typing import Any, Dict
+
+from hello_world.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}