Initial release: MethdAI Receptionist v1.0

.env.example

@@ -0,0 +1,88 @@
+OPENAI_API_KEY=
+MODEL_NAME="gpt-realtime-2"
+
+# 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 (ignored when LOCKED_PROFILE is set in config.py)
+# REACHY_MINI_CUSTOM_PROFILE="example"
+
+# Skip loading .env if you prefer environment-only configuration.
+# REACHY_MINI_SKIP_DOTENV=1
+
+# 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
+
+# Resend transactional email API for the send_email tool.
+# Get a free API key at https://resend.com/api-keys (3000 emails/month free).
+# Without RESEND_API_KEY, send_email writes to the in-memory outbox only
+# (visible in the dashboard's Mailbox Out panel, but nothing actually leaves
+# the robot).
+#
+# RESEND_FROM defaults to "onboarding@resend.dev" — Resend's sandbox sender
+# that ONLY delivers to the email address registered on your Resend account.
+# For production / arbitrary recipients, verify a domain at
+# https://resend.com/domains and set RESEND_FROM to an address on that
+# domain (e.g. "noreply@methdai.com").
+RESEND_API_KEY=
+RESEND_FROM=onboarding@resend.dev
+
+# ---- Reception calendar (Google Calendar via iCal) ----
+# Set this to enable scheduled-visitor flow. The receptionist pulls today's
+# appointments live from this URL (cached ~5 min). When unset, the bot
+# serves walk-in visitors only — they say "I'm here to see X" and the bot
+# routes via the employee directory (managed from the dashboard's
+# Employees panel). There is no hardcoded demo schedule.
+#
+# To get a URL: in Google Calendar, create a calendar (e.g. "MethdAI
+# Reception") -> Settings and sharing -> Integrate calendar ->
+# "Public address in iCal format". Paste it below.
+#
+# Event title convention:  "<Visitor name> with <Host name>"
+#   - "Rohan Verma with Mukul"
+#   - "Sara Khan with Priya — product demo follow-up"
+# Host name matches the employee directory (employees.py); aliases work.
+# An optional " — note" suffix after the host becomes the appointment note;
+# alternatively put it in the event's DESCRIPTION field.
+# RECEPTION_ICS_URL=https://calendar.google.com/calendar/ical/.../public/basic.ics
+
+# Timezone used to display iCal event times on the dashboard and to the LLM.
+# Must be a valid IANA tz name. Defaults to Asia/Kolkata (pilot deployment
+# is in India). Set this when the robot OS is in a different tz than your
+# operators expect to see times in. Common values:
+#   Asia/Kolkata        India (IST, UTC+5:30)
+#   America/New_York    US East Coast
+#   Europe/London       UK
+#   Asia/Tokyo          Japan
+# RECEPTION_TIMEZONE=Asia/Kolkata
+
+# ---- Privacy retention ----
+# Guest face crops in guests/*.png older than this many days are deleted
+# at app startup. Set to 0 to disable (keep faces forever until FIFO
+# capacity eviction kicks in at 100).
+FACE_TTL_DAYS=30
+# Visit rows in visitor_log.db older than this many days are deleted at
+# app startup. Set to 0 to disable (unbounded growth).
+VISITOR_LOG_RETENTION_DAYS=90
+
+# LBPH face-recognition strictness. LOWER = stricter (fewer false matches,
+# more "I don't recognise you, please tell me your name" prompts).
+#   50 - 75   recommended for production (default 75)
+#   75 - 100  permissive (some lighting/angle variance OK)
+#  100 - 110  old default — produces frequent false matches
+# If returning guests stop being recognised, raise by 10 and re-test.
+# If strangers get greeted as someone else, lower by 10.
+FACE_LBPH_THRESHOLD=75

.gitattributes

@@ -0,0 +1,71 @@
+# Force LF line endings for all text files. Without this, Windows
+# checkouts produce CRLF files that crash Python 3.12 when imported on
+# Linux (observed: "from __future__ imports must occur at the
+# beginning of the file" SyntaxError from background_tool_manager.py).
+* text=auto eol=lf
+*.py text eol=lf
+*.txt text eol=lf
+*.md text eol=lf
+*.json text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.toml text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+*.js text eol=lf
+*.ics text eol=lf
+*.sh text eol=lf
+*.cfg text eol=lf
+*.ini text eol=lf
+
+# 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
+.git_disabled/lfs/objects/5a/63/5a63ac8802ff3542f01292c431c5278296880d74cd3580d219fcf4827bc235f9 filter=lfs diff=lfs merge=lfs -text
+.git_disabled/lfs/objects/75/91/75914c3cb7af982e0b1c6369e25fc46d8c08a0ab5ad022240ae9c1a0d93967c3 filter=lfs diff=lfs merge=lfs -text
+.git_disabled/lfs/objects/e9/7c/e97ca125a86bacdaa41c8dca88abd9ca746fd5c9391eda24249c012432b0219b filter=lfs diff=lfs merge=lfs -text
+.git_disabled/objects/pack/pack-ba33ec9fbb4d88d9fd0f2be18721a74ddb3ca16f.pack filter=lfs diff=lfs merge=lfs -text
+build/lib/reachy_mini_receptionist/images/reachymini_avatar.png filter=lfs diff=lfs merge=lfs -text
+build/lib/reachy_mini_receptionist/images/user_avatar.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/reachy_mini_dance.gif filter=lfs diff=lfs merge=lfs -text
+screenshot.png filter=lfs diff=lfs merge=lfs -text
+src/reachy_mini_receptionist/images/reachymini_avatar.png filter=lfs diff=lfs merge=lfs -text
+src/reachy_mini_receptionist/images/user_avatar.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,78 @@
+# 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
+
+# Editor / IDE local settings (user-specific configuration)
+.claude/
+.cursor/
+.vscode/
+.idea/
+
+# Security
+*.key
+*.pem
+*.crt
+*.csr
+
+# Temporary files
+tmp/
+*.log
+cache/
+
+# macOS
+.DS_Store
+
+# Linux
+*~
+.directory
+.Trash-*
+.nfs*
+
+# User-created personalities (managed by UI)
+src/reachy_mini_receptionist/profiles/user_personalities/
+
+# Runtime data (recreated on first run)
+*.db
+*.db-wal
+*.db-shm
+src/reachy_mini_receptionist/guests/*.png
+.env.save
+src/reachy_mini_receptionist.egg-info/
+
+# Old git backup directories
+.git_disabled/

.hfignore

@@ -0,0 +1,23 @@
+# Local environment and secrets
+.env
+src/reachy_mini_receptionist/.env
+
+# Python caches and build outputs
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+*.egg-info/
+
+# Local VCS artifacts that should never ship in published bundles
+.git/
+.git_disabled/
+
+# Local virtual environments
+.venv/
+venv/
+ENV/
+env/

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,152 @@
+---
+title: MethdAI Receptionist
+emoji: 🤖
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+app_file: src/reachy_mini_receptionist/main.py
+pinned: false
+license: apache-2.0
+short_description: Voice-driven receptionist for Reachy Mini — face recognition, real email, live ops dashboard.
+---
+
+# MethdAI Receptionist
+
+AI receptionist for the **Reachy Mini** robot. A visitor walks up, the bot greets them, asks who they're here to see, looks the host up in the directory, and emails the host that their guest has arrived. Returning visitors are recognized by face on their next visit.
+
+Built by **[MethdAI](https://methdai.com)**.
+
+---
+
+## What it does
+
+- **Recognizes faces** — YuNet detection + LBPH recognition. New visitors get registered after they confirm their name.
+- **Talks naturally** — Google Gemini Live (default) or OpenAI Realtime, voice-to-voice over the robot's mic/speaker.
+- **Reads the calendar** — pulls today's schedule from a Google Calendar iCal feed.
+- **Emails the host** — sends real notifications via Resend.
+- **Logs every visit** — SQLite, exportable as CSV.
+- **Configured from a browser** — no `.env` editing, no SSH for routine config.
+
+---
+
+## Hardware required
+
+A real **[Reachy Mini](https://www.pollen-robotics.com/reachy-mini/)** robot from Pollen Robotics. The code expects the robot's camera, microphone, and speaker — there's no cloud-only mode.
+
+---
+
+## Quick start
+
+### Option 1 — Install via the Reachy Mini Control app (recommended)
+
+1. Open Reachy Mini Control on your computer
+2. **Install from Hugging Face** → search `methdai/reachy_mini_receptionist` → Install
+3. Toggle the app **On**
+4. Open the dashboard at `http://<your-robot-hostname>.local:7860/dashboard`
+5. Follow the welcome banner — it tells you exactly which API keys to add and where to find them
+
+### Option 2 — Manual install (for development)
+
+```bash
+# SSH into the robot
+git clone git@github.com:methdai/reachy_mini_receptionist.git
+cd reachy_mini_receptionist
+
+# Install the package in editable mode
+/venvs/apps_venv/bin/pip install -e .
+
+# Make sure the Reachy Mini daemon is running
+sudo systemctl status reachy-mini-daemon
+
+# Start the app
+/venvs/apps_venv/bin/python -m reachy_mini_receptionist.main
+```
+
+Then open `http://localhost:7860/dashboard` in any browser on the same network.
+
+---
+
+## Configuration
+
+**Everything is editable from the dashboard's Settings panel.** No SSH, no `.env` edits.
+
+The welcome banner on first launch tells you which keys are missing. Click each banner item → it scrolls you to the right field.
+
+### Required for full functionality
+
+| Setting | Why | Where to get it |
+|---|---|---|
+| `GEMINI_API_KEY` | Voice (default backend) | [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) — free tier works |
+| `RESEND_API_KEY` | Send emails to hosts | [resend.com](https://resend.com) — free 3000 emails/month |
+| `RECEPTION_ICS_URL` | Read today's appointments | Google Calendar → Settings → **Secret address in iCal format** |
+
+### Optional
+
+| Setting | Purpose |
+|---|---|
+| `VOICE_BACKEND` | Switch between `gemini` (default) and `openai` |
+| `GEMINI_LIVE_VOICE` | Pick a voice — Puck, Charon, Kore, Aoede, etc. |
+| `GEMINI_LIVE_MODEL` | Override the default Gemini Live model |
+| `OPENAI_API_KEY` | Required only if `VOICE_BACKEND=openai` |
+| `RESEND_FROM` | Sender address — defaults to Resend's sandbox sender (delivers only to your Resend account); set to `reception@yourdomain.com` after verifying your domain at Resend |
+| `FACE_TTL_DAYS` | How long a registered face is remembered (default 90 days) |
+| `VISITOR_LOG_RETENTION_DAYS` | How long visit records are kept (default 365 days) |
+
+---
+
+## How it works
+
+**Vision** — `face_recognition_worker.py` runs YuNet on every frame, detects faces, and feeds crops to LBPH for recognition.
+
+**State machine** — `session_manager.py` tracks the current visitor (`idle → visitor_detected → recognized / asking_name → appointment_matched → notified`). `conversation_controller.py` decides what state to move to based on face events and tool results.
+
+**Voice + tools** — Either `gemini_live.py` or `openai_realtime.py` (chosen by `VOICE_BACKEND`) handles bi-directional audio with the LLM. Tools available to the LLM:
+- `get_today_calendar` — fetch today's appointments
+- `register_guest` — save a new visitor's face under a name (requires confirmation)
+- `lookup_employee` — find a host in the directory
+- `send_email` — notify the host
+
+**Persistence** — three SQLite databases (WAL mode):
+- `employees.db` — the directory you edit in the dashboard
+- `visitor_log.db` — every completed visit, exportable as CSV
+- `guests/` directory — saved face crops, one PNG per visitor
+
+---
+
+## Dashboard
+
+Open `http://<robot>:7860/dashboard` while the app is running.
+
+**Live view** — visit count, last visitor, live camera feed, face recognition status.
+**Active Session** — what state the current visitor is in, what the bot heard, what cue it sent to the LLM.
+**Today** — appointments from the calendar, known guests, recent outgoing emails.
+**History** — full visitor log with CSV export and per-row delete.
+**Employees** — add / edit / delete people the bot can notify.
+**Settings** — every environment variable in one place. Toggle dark/light theme from the header.
+
+---
+
+## Development
+
+```bash
+# Install dev dependencies
+/venvs/apps_venv/bin/pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type-check
+mypy src/
+
+# Format / lint
+ruff check src/
+ruff format src/
+```
+
+The codebase is single-process Python 3.10+. Audio streams over WebRTC via `fastrtc`. The dashboard is a single static HTML file in `src/reachy_mini_receptionist/static/`.
+
+---
+
+## License
+
+Apache-2.0

deploy/install_systemd.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+#
+# Install (or upgrade) the MethdAI Receptionist systemd unit on the robot.
+# Run on the robot itself (e.g. via ssh pollen@reachy-mini.local).
+#
+# Idempotent: re-running picks up edits to reachy-receptionist.service and
+# restarts the live service.
+#
+# After install, useful commands:
+#   systemctl status reachy-receptionist
+#   journalctl -u reachy-receptionist -f
+#   sudo systemctl restart reachy-receptionist
+#   sudo systemctl disable --now reachy-receptionist
+#
+set -euo pipefail
+
+UNIT_NAME="reachy-receptionist.service"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SRC="$HERE/$UNIT_NAME"
+DST="/etc/systemd/system/$UNIT_NAME"
+
+if [[ ! -f "$SRC" ]]; then
+    echo "✗ Unit file not found at $SRC" >&2
+    exit 1
+fi
+
+# Re-elevate via `sudo bash <abs-path>` so we don't depend on the script
+# having the executable bit set (git-from-Windows often drops it, and we
+# want `bash deploy/install_systemd.sh` to Just Work).
+if [[ "$(id -u)" -ne 0 ]]; then
+    echo "↻ Re-running with sudo..."
+    exec sudo --preserve-env=HOME bash "$HERE/$(basename "${BASH_SOURCE[0]}")" "$@"
+fi
+
+# Sanity check the runtime paths referenced by the unit file. Catching this
+# now beats debugging a cryptic "ExecStart failed" later.
+PYTHON_BIN="/venvs/apps_venv/bin/python"
+PROJECT_DIR="/home/pollen/reachy_mini_receptionist"
+if [[ ! -x "$PYTHON_BIN" ]]; then
+    echo "✗ Python interpreter not found at $PYTHON_BIN" >&2
+    echo "  Fix: install / locate the apps_venv before re-running." >&2
+    exit 2
+fi
+if [[ ! -d "$PROJECT_DIR" ]]; then
+    echo "✗ Project not found at $PROJECT_DIR" >&2
+    exit 3
+fi
+
+echo "→ Installing $UNIT_NAME → $DST"
+cp "$SRC" "$DST"
+chmod 644 "$DST"
+
+echo "→ Reloading systemd"
+systemctl daemon-reload
+
+echo "→ Enabling on boot"
+systemctl enable "$UNIT_NAME"
+
+echo "→ Restarting service"
+systemctl restart "$UNIT_NAME"
+
+# Brief wait so the status snapshot below shows a meaningful state
+sleep 2
+
+echo
+echo "✓ Installed. Current status:"
+echo "─────────────────────────────────────────"
+systemctl --no-pager --lines=10 status "$UNIT_NAME" || true
+echo "─────────────────────────────────────────"
+echo
+echo "Follow logs:    journalctl -u $UNIT_NAME -f"
+echo "Manual restart: sudo systemctl restart $UNIT_NAME"
+echo "Stop:           sudo systemctl stop $UNIT_NAME"
+echo "Disable:        sudo systemctl disable --now $UNIT_NAME"

deploy/reachy-receptionist.service

@@ -0,0 +1,39 @@
+[Unit]
+Description=MethdAI Receptionist (Reachy Mini)
+Documentation=https://github.com/mukul-chauhan-methdai/reachy_mini_receptionist
+After=network-online.target
+Wants=network-online.target
+# If the receptionist can't come up after 10 attempts in 10 minutes, stop
+# retrying so we don't hammer the OpenAI / Resend / camera APIs on a
+# permanent failure.
+StartLimitBurst=10
+StartLimitIntervalSec=600
+
+[Service]
+Type=simple
+User=pollen
+Group=pollen
+WorkingDirectory=/home/pollen/reachy_mini_receptionist
+
+# Load .env into the service environment. The "-" prefix makes the file
+# optional — missing .env logs a warning but doesn't block start.
+EnvironmentFile=-/home/pollen/reachy_mini_receptionist/.env
+
+# Best-effort: wake the reachy_mini daemon before launching the app.
+# Retries every 3s for up to 30s. We always exit 0 so a failed wake
+# doesn't kill the unit before ExecStart; the app itself will crash and
+# systemd will restart it if the daemon is genuinely down.
+ExecStartPre=/bin/bash -c 'for i in $(seq 1 10); do curl -fsS -X POST "http://localhost:8000/api/daemon/start?wake_up=true" >/dev/null && exit 0; sleep 3; done; exit 0'
+
+ExecStart=/venvs/apps_venv/bin/python -m reachy_mini_receptionist.main
+
+Restart=on-failure
+RestartSec=5
+
+# Capture stdout/stderr in the journal — view with:
+#   journalctl -u reachy-receptionist -f
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target

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,9 @@
+# This file is an explicit allow-list.
+# Every tool name listed below must be either:
+# - a built-in tool from src/reachy_mini_receptionist/tools/
+# - or an external tool file in TOOLS_DIRECTORY (e.g. external_tools/starter_custom_tool.py)
+
+get_today_calendar
+register_guest
+send_email
+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_receptionist.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,141 @@
+<!doctype html>
+<html>
+
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1" />
+	<title>Reachy Mini AI Receptionist</title>
+	<link rel="preconnect" href="https://fonts.googleapis.com">
+	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+	<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Manrope:wght@400;500;600&display=swap" rel="stylesheet">
+	<link rel="stylesheet" href="style.css" />
+</head>
+
+<body>
+	<header class="hero">
+		<div class="topline">
+			<div class="brand">
+				<span class="logo">🤖</span>
+				<span class="brand-name">Reachy Mini</span>
+			</div>
+			<div class="pill">Realtime voice · Vision aware · Expressive motion</div>
+		</div>
+		<div class="hero-grid">
+			<div class="hero-copy">
+				<p class="eyebrow">AI Receptionist</p>
+				<h1>
+					Face-aware receptionist with tool-calling automation.
+					<a class="live-demo-badge" href="#live-demo">Live demo</a>
+				</h1>
+				<p class="lede">
+					A camera-aware front-desk assistant for Reachy Mini. Greet visitors naturally, register guests, check appointments, and log handoff actions from a single dashboard.
+				</p>
+				<p class="lede">
+					Built for reception workflows: realtime face detection to know when someone is present, face recognition to personalize interactions, and structured tool calls so the AI can register guests, query appointments, and trigger handoff actions reliably.
+				</p>
+				<div class="hero-actions">
+					<a class="btn primary" href="#highlights">Explore features</a>
+					<a class="btn ghost" href="#story">See how it feels</a>
+				</div>
+				<div class="hero-badges">
+					<span>Realtime face detection</span>
+					<span>Visitor face recognition</span>
+					<span>Model tool-calling workflows</span>
+					<span>Low-latency voice + dashboard ops</span>
+				</div>
+			</div>
+			<div class="hero-visual">
+				<div class="glass-card">
+					<img src="screenshot.png" alt="Reachy Mini AI Receptionist screenshot" class="hero-gif">
+					<p class="caption">Reachy Mini can greet, identify, and assist visitors with receptionist-specific context.</p>
+					<div class="video-embed-wrapper" id="live-demo">
+						<iframe
+							src="https://www.youtube.com/embed/4U9uj5b9p2Y"
+							title="Reachy Mini AI Receptionist live demo"
+							loading="lazy"
+							allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+							allowfullscreen>
+						</iframe>
+					</div>
+					<p class="video-link"><a href="https://youtu.be/4U9uj5b9p2Y" target="_blank" rel="noopener">Watch on YouTube</a></p>
+				</div>
+			</div>
+		</div>
+	</header>
+
+	<section id="highlights" class="section features">
+		<div class="section-header">
+			<p class="eyebrow">What’s inside</p>
+			<h2>All-in-one receptionist layer for your robot</h2>
+			<p class="intro">
+				The app blends realtime speech, vision, and workflow tools so Reachy Mini can run a front desk flow.
+			</p>
+		</div>
+		<div class="feature-grid">
+			<div class="feature-card">
+				<span class="icon">🎤</span>
+				<h3>Natural voice chat</h3>
+				<p>Talk freely and get fast, high-quality replies powered by realtime models.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🎥</span>
+				<h3>Face-aware onboarding</h3>
+				<p>Recognize known visitors, register new guests, and keep the latest face context synced with the conversation.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">💃</span>
+				<h3>Expressive motion</h3>
+				<p>Use subtle head and antenna gestures during welcome and registration interactions.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🧠</span>
+				<h3>Calendar-aware assistance</h3>
+				<p>Use appointment context to welcome guests on time and guide follow-up actions.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🌐</span>
+				<h3>Ready for your setup</h3>
+				<p>Works in console mode or web mode with dashboard APIs for quick operator visibility.</p>
+			</div>
+		</div>
+	</section>
+
+	<section id="story" class="section story">
+		<div class="story-grid">
+			<div class="story-card">
+				<p class="eyebrow">How it feels</p>
+				<h3>From greeting to handoff in seconds</h3>
+				<ul class="story-list">
+					<li><span>👋</span> Greet visitors naturally with low-latency voice conversation.</li>
+					<li><span>👀</span> Use camera context to identify known guests or register new ones.</li>
+					<li><span>📅</span> Check appointment context and respond with relevant timing cues.</li>
+					<li><span>📨</span> Log handoff actions in the outbox for host follow-up.</li>
+				</ul>
+			</div>
+			<div class="story-card secondary">
+				<p class="eyebrow">Where it shines</p>
+				<h3>Great for offices, demos, and guided reception flows</h3>
+				<p class="story-text">
+					Show how Reachy Mini can handle repeatable visitor workflows while staying expressive and conversational. It is ideal for front-desk demos, events, and product showcases.
+				</p>
+				<div class="chips">
+					<span class="chip">Guest recognition</span>
+					<span class="chip">Calendar check</span>
+					<span class="chip">Outbox logging</span>
+					<span class="chip">Dashboard APIs</span>
+					<span class="chip">Realtime conversation</span>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<footer class="footer">
+		<p>
+			Reachy Mini AI Receptionist by Toon Beerten (<a href="mailto:toon@neontreebot.be">toon@neontreebot.be</a>), based on the Reachy Mini conversation app by <a href="https://github.com/pollen-robotics" target="_blank" rel="noopener">Pollen Robotics</a>.
+			Explore more apps on <a href="https://huggingface.co/spaces/pollen-robotics/Reachy_Mini_Apps" target="_blank" rel="noopener">Hugging Face Spaces</a>.
+		</p>
+	</footer>
+
+</body>
+
+</html>

plan.md

@@ -0,0 +1,89 @@
+# Reachy Mini AI Receptionist — Plan
+
+## What This App Does
+
+An interactive AI receptionist that:
+
+1. Talks to visitors via OpenAI Realtime API (low-latency speech in/out).
+2. Monitors camera frames for face detection/recognition in a background worker.
+3. Stores guest face crops as PNG files in a persistent `guests/` directory.
+4. Uses a hardcoded POC calendar for appointment context.
+5. Exposes a dashboard with live video, guests, calendar, outbox, and debug logs.
+
+Start command:
+
+```bash
+python -m reachy_mini_receptionist.main
+```
+
+---
+
+## Architecture
+
+The receptionist extends the conversation base stack and adds receptionist-specific modules:
+
+```text
+src/reachy_mini_receptionist/
+├── face_db.py                  # File-based face store (PNG per guest in guests/)
+├── face_recognition_worker.py  # Background detection/recognition + event emission
+├── calendar_data.py            # Hardcoded appointment data
+├── main.py                     # App entrypoint + dashboard API mounting
+└── tools/
+      ├── get_today_calendar.py
+      ├── register_guest.py
+      ├── send_email.py
+      └── check_current_face.py   # Legacy compatibility path
+```
+
+---
+
+## Key Design Decisions
+
+### 1) Face database is file-based
+
+- Guests are stored as grayscale PNG crops in `guests/`.
+- `FaceDatabase` enforces capacity with FIFO-style eviction when full.
+- No SQL database is required.
+
+### 2) Face recognition runs in a background worker
+
+- `FaceRecognitionWorker` runs independently from the realtime audio loop.
+- Worker state is consumed by tools and dashboard endpoints.
+- Stable face transitions emit context events to the model.
+
+### 3) Calendar is static for POC
+
+- `calendar_data.py` returns hardcoded appointments.
+- Easy to swap later for Google/Microsoft calendar integrations.
+
+### 4) Dashboard API is mounted in-app
+
+- `GET /dashboard` serves the receptionist dashboard.
+- `GET /video_feed` streams annotated MJPEG.
+- `GET /api/guests`, `/api/calendar`, `/api/outbox`, `/api/face_status`, `/api/logs` expose app state.
+
+### 5) Profile is intentionally locked
+
+- `LOCKED_PROFILE` is set to `_reachy_mini_receptionist_locked_profile` in `config.py`.
+- Current locked tool allow-list is:
+   - `get_today_calendar`
+   - `register_guest`
+   - `send_email`
+
+---
+
+## Face Context Event Behavior
+
+The receptionist flow is push-based:
+
+- Stable face transitions are emitted by `FaceRecognitionWorker`.
+- `OpenaiRealtimeHandler` injects these as context-only user items.
+- No automatic `response.create` is triggered by these face context updates.
+
+---
+
+## Known Notes
+
+- With `--no-camera`, recognition and registration tools cannot operate.
+- Output language behavior is controlled by profile instructions.
+- If profile/tool loading fails, the app can fall back to default model behavior; monitor startup logs.

pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = [ "setuptools",]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reachy_mini_receptionist"
+version = "0.3.0"
+description = "Reachy Mini AI receptionist app with realtime voice, guest recognition, and dashboard tools."
+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-contrib-python>=4.8.0", "python-dotenv", "openai>=2.1", "google-genai>=1.40", "reachy_mini_dances_library", "reachy_mini_toolbox", "reachy-mini>=1.5.0", "eclipse-zenoh~=1.7.0", "gradio_client>=1.13.3", "numpy>=1.24", "httpx>=0.27", "icalendar>=5.0",]
+license = "Apache-2.0"
+classifiers = [
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3 :: Only",
+	"Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/pollen-robotics/reachy_mini"
+Repository = "https://github.com/pollen-robotics/reachy_mini"
+[[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]
+reachy-mini-receptionist = "reachy_mini_receptionist.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]
+reachy_mini_receptionist = "reachy_mini_receptionist.main:ReachyMiniReceptionist"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.package-data]
+reachy_mini_receptionist = [ "images/*", "static/*", ".env.example", "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 = [ "reachy_mini_receptionist",]
+known-first-party = [ "reachy_mini", "reachy_mini_dances_library", "reachy_mini_toolbox",]
+split-on-trailing-comma = true

scripts/gemini_live_smoke.py

@@ -0,0 +1,96 @@
+"""Minimal Gemini Live smoke test — isolates SDK behavior from app.
+
+Reads GEMINI_API_KEY from environment, connects to the Live API with
+the configured model, sends a single text turn, prints every event
+received until session closes or 30s timeout.
+
+Use:
+    GEMINI_API_KEY=... /venvs/apps_venv/bin/python scripts/gemini_live_smoke.py
+    GEMINI_API_KEY=... GEMINI_LIVE_MODEL=gemini-2.0-flash-live-001 /venvs/apps_venv/bin/python scripts/gemini_live_smoke.py
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+
+async def main() -> int:
+    key = os.environ.get("GEMINI_API_KEY", "").strip()
+    if not key:
+        print("ERROR: GEMINI_API_KEY not set", file=sys.stderr)
+        return 1
+
+    model = os.environ.get("GEMINI_LIVE_MODEL", "gemini-2.5-flash-native-audio-latest")
+    print(f"[smoke] model={model}")
+
+    try:
+        from google import genai
+    except ImportError as e:
+        print(f"ERROR: google-genai not installed: {e}", file=sys.stderr)
+        return 1
+
+    print(f"[smoke] google-genai version={getattr(genai, '__version__', '?')}")
+
+    client = genai.Client(api_key=key, http_options={"api_version": "v1beta"})
+
+    # Native-audio models REQUIRE AUDIO modality. The 1007 error
+    # "Cannot extract voices from a non-audio request" confirms this.
+    config = {
+        "response_modalities": ["AUDIO"],
+    }
+    try:
+        async with client.aio.live.connect(model=model, config=config) as session:
+            print("[smoke] connected; sending one text turn (turn_complete=True)...")
+            await session.send_client_content(
+                turns=[{"role": "user", "parts": [{"text": "Say hello in one short friendly sentence."}]}],
+                turn_complete=True,
+            )
+
+            event_count = 0
+            audio_bytes_total = 0
+            try:
+                async with asyncio.timeout(30):
+                    async for resp in session.receive():
+                        event_count += 1
+                        text = getattr(resp, "text", None)
+                        data = getattr(resp, "data", None)
+                        if data:
+                            audio_bytes_total += len(data)
+                        sc = getattr(resp, "server_content", None)
+                        tc = getattr(sc, "turn_complete", None) if sc else None
+                        model_turn = getattr(sc, "model_turn", None) if sc else None
+                        mt_parts_summary = ""
+                        if model_turn is not None:
+                            parts = getattr(model_turn, "parts", None) or []
+                            mt_parts_summary = f" model_turn.parts={len(parts)}"
+                            for i, p in enumerate(parts[:3]):
+                                ip = getattr(p, "inline_data", None)
+                                tp = getattr(p, "text", None)
+                                th = getattr(p, "thought", None)
+                                print(
+                                    f"[smoke]     part {i}: text={tp!r}, "
+                                    f"inline_data={'<%d bytes>' % len(getattr(ip, 'data', b'')) if ip else None}, "
+                                    f"thought={th}"
+                                )
+                        print(
+                            f"[smoke] event #{event_count}: text={text!r}, "
+                            f"data={'<%d bytes>' % len(data) if data else None}, "
+                            f"turn_complete={tc}{mt_parts_summary}"
+                        )
+                        if tc:
+                            print("[smoke] turn_complete=True — exiting receive() loop")
+                            break
+            except asyncio.TimeoutError:
+                print(f"[smoke] timed out after 30s, events={event_count}, audio_total={audio_bytes_total} bytes")
+            print(f"[smoke] done. total events={event_count}, total_audio_bytes={audio_bytes_total}")
+    except Exception as e:
+        import traceback
+        print(f"[smoke] CONNECTION ERROR: {e}")
+        traceback.print_exc()
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

scripts/list_gemini_live_models.py

@@ -0,0 +1,50 @@
+"""List all Gemini models on this API key that support bidiGenerateContent.
+
+These are the models you can put in GEMINI_LIVE_MODEL. Anything not listed
+here will 1008 at connect time.
+
+Use:
+    GEMINI_API_KEY=... /venvs/apps_venv/bin/python scripts/list_gemini_live_models.py
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import httpx
+
+
+def main() -> int:
+    key = os.environ.get("GEMINI_API_KEY", "").strip()
+    if not key:
+        print("ERROR: GEMINI_API_KEY not set", file=sys.stderr)
+        return 1
+
+    url = f"https://generativelanguage.googleapis.com/v1beta/models?key={key}&pageSize=200"
+    try:
+        resp = httpx.get(url, timeout=15.0)
+        resp.raise_for_status()
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    data = resp.json()
+    models = data.get("models", [])
+    live_models = []
+    for m in models:
+        methods = m.get("supportedGenerationMethods") or []
+        if "bidiGenerateContent" in methods:
+            live_models.append(m.get("name", "?").replace("models/", ""))
+
+    if not live_models:
+        print("(no Live-capable models on this key)")
+        return 0
+
+    print(f"Live-capable models on this key ({len(live_models)}):\n")
+    for name in sorted(live_models):
+        print(f"  {name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/reachy_mini_receptionist/__init__.py

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

src/reachy_mini_receptionist/audio/__init__.py

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

src/reachy_mini_receptionist/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 reachy_mini_receptionist.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/reachy_mini_receptionist/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/reachy_mini_receptionist/calendar_data.py

@@ -0,0 +1,139 @@
+"""Calendar data — appointments source for the receptionist.
+
+Single source: a Google Calendar (or any iCal feed) configured via the
+``RECEPTION_ICS_URL`` env var. Operators add events in Google Calendar;
+the robot fetches every ~5 min via ``ical_calendar.py``. Title
+convention: ``"<Visitor> with <Host>"`` (host resolved through
+``employees.py``).
+
+When ``RECEPTION_ICS_URL`` is unset OR the feed is unreachable, this
+module returns an EMPTY calendar. That's intentional — the receptionist
+supports exactly two visitor paths:
+
+1. **Scheduled visitor** — appointment exists in the iCal feed; bot
+   matches by visitor name and emails the host.
+2. **Walk-in to see an employee** — visitor names a host that lives in
+   the SQLite Employee directory (managed from the dashboard's
+   Employees panel); bot calls ``lookup_employee`` and emails the host.
+
+There is intentionally no hardcoded demo schedule fallback. If you want
+demo data, add it to Google Calendar; if you want a host-only flow, add
+the host via the dashboard.
+
+The ``visiting`` field on each returned appointment is always an email
+address (resolved through the employee directory). If a host can't be
+resolved, the original string is preserved so the LLM can flag it.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from reachy_mini_receptionist import employees
+
+
+def _resolve_visiting(visiting: str) -> str:
+    """Return the email for a `visiting` reference, falling back to itself.
+
+    Looks up via the employee directory first; if `visiting` already contains
+    `@` (one-off external host), returns it unchanged.
+    """
+    if not visiting:
+        return ""
+    if "@" in visiting:
+        return visiting
+    email = employees.find_email_for(visiting)
+    return email or visiting
+
+
+def _appointments_from_ical(ics_url: str) -> List[Dict[str, Any]]:
+    """Pull today's appointments from an iCal feed and reshape them.
+
+    Drops the iCal-specific helper fields (``_host_query``, ``_dt``) and
+    resolves the host name to an email through the employee directory.
+    """
+    from reachy_mini_receptionist import ical_calendar
+
+    raw = ical_calendar.fetch_appointments(ics_url)
+    out: List[Dict[str, Any]] = []
+    for ev in raw:
+        host_query = ev.get("_host_query", "")
+        out.append({
+            "time": ev.get("time", ""),
+            "name": ev.get("name", ""),
+            "note": ev.get("note", ""),
+            "visiting": _resolve_visiting(host_query) if host_query else "",
+        })
+    return out
+
+
+def get_appointments() -> List[dict]:
+    """Return today's appointment list with ``visiting`` resolved to an email.
+
+    Pulls live from the iCal feed when ``RECEPTION_ICS_URL`` is set
+    (cached ~5 min). Returns an empty list otherwise — walk-in flow
+    (via ``lookup_employee``) handles visitors who aren't on the schedule.
+
+    Each item has:
+        time     (str)  — e.g. "11:00 AM"
+        name     (str)  — guest name
+        note     (str)  — short description (may be empty)
+        visiting (str)  — host email (resolved from employee directory)
+    """
+    ics_url = (os.getenv("RECEPTION_ICS_URL") or "").strip()
+    if not ics_url:
+        return []
+    return _appointments_from_ical(ics_url)
+
+
+async def get_appointments_async() -> List[dict]:
+    """Async wrapper for ``get_appointments`` — offloads the sync iCal HTTP
+    fetch to a worker thread so async callers (realtime audio loop, tool
+    completion handlers) don't block the event loop on a 10-second HTTP
+    timeout. Cache hits return immediately; only the underlying httpx.get
+    call gets thread-offloaded.
+    """
+    return await asyncio.to_thread(get_appointments)
+
+
+def format_for_llm() -> str:
+    """Return a human-readable calendar string for the LLM."""
+    today = datetime.now().strftime("%A, %B %d %Y")
+    appts = get_appointments()
+    if not appts:
+        return (
+            f"Today is {today}. No scheduled appointments in the calendar. "
+            "Walk-in visitors should be routed via lookup_employee."
+        )
+    lines = [f"Today is {today}. Appointments:"]
+    for appt in appts:
+        lines.append(f"  {appt['time']}: {appt['name']} — {appt['note']}")
+    return "\n".join(lines)
+
+
+def get_appointment_for_name(name: str) -> Optional[dict]:
+    """Find an appointment by guest name (case-insensitive)."""
+    target = (name or "").strip().lower()
+    for appt in get_appointments():
+        if appt["name"].lower() == target:
+            return appt
+    return None
+
+
+def find_appointment_for_employee(employee_query: str) -> Optional[dict]:
+    """Find today's appointment whose host matches ``employee_query``.
+
+    Resolves the query through the employee directory first so callers can
+    pass a name OR alias OR email. Returns the first matching appointment,
+    or None if nothing on today's schedule is for that host.
+    """
+    target_email = employees.find_email_for(employee_query) or employee_query
+    target_email = (target_email or "").strip().lower()
+    if not target_email:
+        return None
+    for appt in get_appointments():
+        if (appt.get("visiting") or "").strip().lower() == target_email:
+            return appt
+    return None

src/reachy_mini_receptionist/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/reachy_mini_receptionist/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 = "_reachy_mini_receptionist_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 receptionist 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/reachy_mini_receptionist/console.py

@@ -0,0 +1,527 @@
+"""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 reachy_mini_receptionist.config import LOCKED_PROFILE, config
+from reachy_mini_receptionist.openai_realtime import OpenaiRealtimeHandler
+from reachy_mini_receptionist.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, RedirectResponse
+    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
+            ``reachy_mini_receptionist/.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 reachy_mini_receptionist.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 / -> redirect to /dashboard (the receptionist control room)
+        @self._settings_app.get("/")
+        def _root() -> RedirectResponse:
+            return RedirectResponse(url="/dashboard")
+
+        # 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("reachy_mini_receptionist.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 reachy_mini_receptionist.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)
+
+                # Drop empty / sub-sample chunks. Some Gemini Live preview
+                # models (e.g. gemini-3.1-flash-live-preview as of
+                # 2026-05-21) emit 2-byte placeholder chunks. Without
+                # this guard, scipy.signal.resample below does
+                # `len_in / len_out` and crashes with ZeroDivisionError
+                # when the resampled target length rounds to 0,
+                # killing the whole console play_loop and the app with
+                # it. Skipping is the safe behaviour — a truly empty
+                # chunk has nothing to play anyway.
+                if audio_frame.size == 0 or len(audio_frame) < 2:
+                    logger.debug(
+                        "play_loop: skipping near-empty audio frame "
+                        "(len=%d, input_sr=%s, output_sr=%s)",
+                        len(audio_frame), input_sample_rate, output_sample_rate,
+                    )
+                    await asyncio.sleep(0)
+                    continue
+
+                # Resample if needed
+                if input_sample_rate != output_sample_rate:
+                    target_len = int(len(audio_frame) * output_sample_rate / input_sample_rate)
+                    if target_len < 1:
+                        # Resample would divide by zero — skip rather than crash.
+                        logger.debug(
+                            "play_loop: skipping frame that would resample to 0 "
+                            "samples (len=%d, %s->%s)",
+                            len(audio_frame), input_sample_rate, output_sample_rate,
+                        )
+                        await asyncio.sleep(0)
+                        continue
+                    audio_frame = resample(audio_frame, target_len)
+
+                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/reachy_mini_receptionist/conversation_controller.py

@@ -0,0 +1,586 @@
+"""Conversation controller — translates events into session state transitions.
+
+This is the workflow engine. It listens for:
+- Face state events from FaceRecognitionWorker.
+- Tool call completions from the realtime handler.
+
+And decides which ReceptionState transition should fire on the SessionManager.
+
+Also exposes ``next_action_hint(state)`` — short directives the realtime
+handler appends to its session context push so the LLM gets per-state
+workflow guidance dynamically, instead of having the whole flow baked into
+the system prompt.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Optional
+
+from reachy_mini_receptionist.receptionist_state import ReceptionState
+from reachy_mini_receptionist.session_manager import SessionManager
+
+logger = logging.getLogger(__name__)
+
+
+# States in which an "unknown" face transitioning to "known" should still
+# short-circuit identification (we haven't yet confirmed the visitor's name
+# through other channels).
+_EARLY_IDENTIFICATION_STATES: frozenset[ReceptionState] = frozenset({
+    ReceptionState.IDLE,
+    ReceptionState.VISITOR_DETECTED,
+    ReceptionState.GREETING,
+    ReceptionState.ASK_NAME,
+    # Include MULTIPLE_PEOPLE so the controller transitions back out as
+    # soon as the crowd thins to one face.
+    ReceptionState.MULTIPLE_PEOPLE,
+})
+
+# States in which losing the face means the visitor walked away and we should
+# reset the session for the next person. Inside flow states (e.g. ASK_NAME),
+# losing the face briefly just means they turned their head — don't reset.
+_RESET_ON_FACE_LOST_STATES: frozenset[ReceptionState] = frozenset({
+    ReceptionState.NOTIFIED,
+    ReceptionState.NO_APPOINTMENT,
+    ReceptionState.EMAIL_FAILED,
+    ReceptionState.COMPLETE,
+    ReceptionState.ERROR,
+})
+
+
+class ConversationController:
+    """Wire face events + tool completions into session state transitions.
+
+    Stateless aside from the SessionManager it operates on. Safe to call
+    handlers from any thread because SessionManager handles locking.
+
+    Optionally records every completed visit to a ``VisitorLog`` when the
+    session resets out of a meaningful state (visitor name, recognized
+    face, or employee was set).
+    """
+
+    def __init__(self, session_manager: SessionManager) -> None:
+        self._session = session_manager
+
+    # ------------------------------------------------------------------
+    # Face events
+    # ------------------------------------------------------------------
+
+    def on_face_event(self, event: dict[str, Any]) -> None:
+        """Translate a ``face_state_changed`` event into a session transition.
+
+        Event shape (from ``FaceRecognitionWorker._update_stable_state``):
+            state: "no_face" | "unknown" | "known"
+            name:  str | None       (populated when state == "known")
+            previous_state, previous_name, lbph_confidence, detection_confidence
+        """
+        state = event.get("state")
+        name = event.get("name")
+        current = self._session.current_state
+        snapshot = self._session.session
+
+        if state == "known" and name:
+            # Already-completed-flow guard: if we already emailed the host
+            # for this visitor, don't re-enter RECOGNIZED — that re-triggers
+            # the whole check-in (get_today_calendar + send_email) and
+            # produces duplicate emails when the face momentarily flickers
+            # to MULTIPLE_PEOPLE and back.
+            already_done = (
+                bool(snapshot.email_sent_to)
+                and (snapshot.visitor_name or "").strip().lower() == name.strip().lower()
+            )
+            if already_done:
+                if current != ReceptionState.NOTIFIED:
+                    logger.info(
+                        "Face %r returned after notified — restoring NOTIFIED instead of re-running flow",
+                        name,
+                    )
+                    self._session.transition(
+                        ReceptionState.NOTIFIED,
+                        recognized_face_name=name,
+                    )
+                else:
+                    self._session.update(recognized_face_name=name)
+                return
+
+            if current in _EARLY_IDENTIFICATION_STATES:
+                # If the visitor has ALREADY told us a different name in
+                # this session (visitor_name set by register_guest), trust
+                # speech over face. The face recognizer can mis-match
+                # (LBPH on a single crop is noisy under different lighting)
+                # and the visitor explicitly correcting "no, I'm X" should
+                # override the camera. Only auto-promote face -> visitor
+                # when no speech-confirmed name exists yet.
+                speech_confirmed = (snapshot.visitor_name or "").strip()
+                if speech_confirmed and speech_confirmed.lower() != name.strip().lower():
+                    logger.info(
+                        "Face matched %r but visitor already confirmed %r — keeping speech",
+                        name, speech_confirmed,
+                    )
+                    self._session.update(recognized_face_name=name)
+                    return
+                self._session.transition(
+                    ReceptionState.RECOGNIZED,
+                    visitor_name=name,
+                    recognized_face_name=name,
+                )
+                # Same auto-resolve as the register_guest path so the
+                # face-recognition shortcut also reaches APPOINTMENT_MATCHED
+                # without depending on the LLM to call get_today_calendar.
+                try:
+                    self._auto_resolve_appointment(name)
+                except Exception as e:
+                    logger.warning(
+                        "Auto-resolve appointment after face match failed: %s", e,
+                    )
+            else:
+                # Past identification — just record the face match.
+                self._session.update(recognized_face_name=name)
+            return
+
+        if state == "unknown":
+            if current in (ReceptionState.IDLE, ReceptionState.MULTIPLE_PEOPLE):
+                self._session.transition(ReceptionState.VISITOR_DETECTED)
+            return
+
+        if state == "multiple":
+            if current != ReceptionState.MULTIPLE_PEOPLE:
+                self._session.transition(ReceptionState.MULTIPLE_PEOPLE)
+            return
+
+        if state == "no_face":
+            if current in _RESET_ON_FACE_LOST_STATES:
+                logger.info("Face lost in terminal state %s — resetting session", current.value)
+                # SessionManager.reset() handles persisting the pre-reset
+                # snapshot to the visitor log on its own.
+                self._session.reset()
+            return
+
+    # ------------------------------------------------------------------
+    # Tool completions
+    # ------------------------------------------------------------------
+
+    async def on_tool_completed_async(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        result: dict[str, Any],
+    ) -> None:
+        """Async-safe wrapper for ``on_tool_completed``.
+
+        The realtime event loop reaches the controller via this method.
+        Tools whose handlers need an iCal fetch (``register_guest`` triggers
+        ``_auto_resolve_appointment``) pre-fetch the calendar via
+        ``asyncio.to_thread`` so the audio loop never blocks on the
+        synchronous httpx call inside ``ical_calendar.fetch_appointments``.
+        """
+        if not isinstance(result, dict):
+            return
+        explicit_failure = "error" in result and result.get("success") is False
+        if explicit_failure:
+            self.on_tool_completed(tool_name, args, result)
+            return
+
+        appointments: Optional[list[dict[str, Any]]] = None
+        if tool_name in ("register_guest", "lookup_employee"):
+            try:
+                from reachy_mini_receptionist import calendar_data
+                appointments = await calendar_data.get_appointments_async()
+            except Exception as e:
+                logger.debug("Pre-fetch appointments failed: %s", e)
+                appointments = None
+
+        self._dispatch_tool_completion(tool_name, args, result, appointments)
+
+    def on_tool_completed(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        result: dict[str, Any],
+    ) -> None:
+        """Translate a successful tool call into a session transition.
+
+        Failures are logged but never transition the session into ERROR
+        automatically — that's the caller's policy choice.
+
+        Synchronous variant — calls into ``_auto_resolve_appointment`` will
+        block on the iCal HTTP fetch. Safe from background threads (face
+        worker). Async callers on the realtime event loop should use
+        ``on_tool_completed_async`` instead so the iCal call gets
+        off-thread.
+        """
+        if not isinstance(result, dict):
+            return
+        explicit_failure = "error" in result and result.get("success") is False
+        if explicit_failure:
+            logger.debug("Tool %s reported failure: %s", tool_name, result.get("error"))
+            return
+        self._dispatch_tool_completion(tool_name, args, result, None)
+
+    def _dispatch_tool_completion(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        result: dict[str, Any],
+        appointments: Optional[list[dict[str, Any]]],
+    ) -> None:
+        """Core transition logic shared by sync + async entry points.
+
+        ``appointments`` is the optional pre-fetched calendar (set by the
+        async entry point so the iCal HTTP call doesn't run on the
+        realtime audio loop). When ``None``, ``_auto_resolve_appointment``
+        falls back to its own sync fetch.
+        """
+        if tool_name == "register_guest":
+            # Only transition on actual SUCCESS. If register_guest was
+            # blocked (no_confirmation, name_is_filler, hallucinated
+            # chatter, no_face, etc.) it returns success=False — we
+            # MUST NOT advance the session in that case, or the visitor
+            # ends up locked into a bogus name like "Community" with
+            # no path to fix it.
+            if not result.get("success"):
+                logger.debug(
+                    "register_guest returned success=False (reason=%r) — not transitioning",
+                    result.get("blocked_reason") or result.get("error"),
+                )
+                return
+            name = (args.get("name") or "").strip()
+            if name:
+                self._session.transition(
+                    ReceptionState.RECOGNIZED,
+                    visitor_name=name,
+                    recognized_face_name=name,
+                )
+                # The LLM was supposed to follow the RECOGNIZED hint with a
+                # get_today_calendar tool call, but it kept asking the visitor
+                # "who are you here to see?" instead — emails never went out.
+                # Pull the calendar synchronously from the backend and dispatch
+                # APPOINTMENT_MATCHED / NO_APPOINTMENT ourselves so the bot is
+                # never blocked on the LLM remembering to look something up.
+                try:
+                    self._auto_resolve_appointment(name, appointments)
+                except Exception as e:
+                    logger.warning(
+                        "Auto-resolve appointment after register_guest failed: %s", e,
+                    )
+
+        elif tool_name == "get_today_calendar":
+            calendar = result.get("calendar") or []
+            snap = self._session.session
+            # Prefer explicit visitor_name (operator typed/spoke it), fall
+            # back to a recognized face match (returning guest whose name
+            # we already trust because LBPH matched their saved crop).
+            visitor_name = snap.visitor_name or snap.recognized_face_name
+            if not visitor_name:
+                # LLM fetched the calendar as a generic lookup (often during
+                # idle exploration) before identifying the visitor. There is
+                # no name to match against yet, so don't change state.
+                logger.debug(
+                    "get_today_calendar fired without a visitor_name — skipping transition",
+                )
+                return
+            matched = self._match_appointment(calendar, visitor_name)
+            updates: dict[str, Any] = {}
+            # If we matched purely off the face name, promote it into
+            # visitor_name so downstream (send_email guard, dashboard,
+            # visitor log) treats it as a confirmed identity.
+            if not snap.visitor_name:
+                updates["visitor_name"] = visitor_name
+            if matched:
+                updates["matched_appointment"] = matched
+                updates["employee_name"] = matched.get("visiting")
+                self._session.transition(ReceptionState.APPOINTMENT_MATCHED, **updates)
+            else:
+                updates["error_message"] = f"No appointment found for {visitor_name!r}"
+                self._session.transition(ReceptionState.NO_APPOINTMENT, **updates)
+
+        elif tool_name == "send_email":
+            # Only flip to NOTIFIED if the tool actually succeeded. The
+            # send_email tool can refuse (placeholder address, no visitor
+            # identity yet, duplicate-blocked, Resend HTTP error) — those
+            # all return success=False, and the dashboard must not lie
+            # "NOTIFIED" when no email left the system.
+            to = (args.get("to") or "").strip()
+            send_ok = bool(result.get("success"))
+            if to and send_ok:
+                self._session.transition(
+                    ReceptionState.NOTIFIED,
+                    email_sent_to=to,
+                )
+            elif to and not send_ok:
+                logger.info(
+                    "send_email returned success=False (blocked_reason=%s) — "
+                    "NOT transitioning to NOTIFIED",
+                    result.get("blocked_reason") or result.get("error"),
+                )
+
+        elif tool_name == "lookup_employee":
+            # Walk-in path: visitor named the host instead of themselves.
+            # On hit, drop the synthetic appointment into the session so the
+            # existing APPOINTMENT_MATCHED -> send_email -> NOTIFIED path
+            # works unchanged. On miss, surface UNKNOWN_EMPLOYEE so the
+            # bot tells the visitor that name isn't on the list.
+            found = bool(result.get("found"))
+            if found:
+                emp = result.get("employee") or {}
+                emp_email = (emp.get("email") or "").strip()
+                emp_name = (emp.get("name") or args.get("name") or "").strip()
+                if emp_email:
+                    snap = self._session.session
+                    # Trust the face DB: if LBPH already recognised this
+                    # visitor (recognized_face_name), promote that into
+                    # visitor_name so send_email's identity guard passes
+                    # without forcing the bot to ask the name again. This
+                    # is the "returning known guest came back to see X"
+                    # path — they shouldn't be re-prompted for their name.
+                    visitor = snap.visitor_name or snap.recognized_face_name
+
+                    # If the visitor is known AND today's calendar has a real
+                    # appointment for them with this host, prefer that real
+                    # appointment over a synthetic walk-in. Otherwise the
+                    # host's notification email loses the scheduled time/note
+                    # and reads "Walk-in visitor has arrived" for a meeting
+                    # that was actually on the calendar.
+                    real_appt: Optional[dict[str, Any]] = None
+                    if visitor and appointments:
+                        candidate = self._match_appointment(appointments, visitor)
+                        if (
+                            candidate
+                            and (candidate.get("visiting") or "").strip().lower()
+                            == emp_email.lower()
+                        ):
+                            real_appt = candidate
+
+                    if real_appt is not None:
+                        matched_appt = real_appt
+                    else:
+                        matched_appt = {
+                            "time": "now",
+                            "name": visitor or "Walk-in visitor",
+                            "note": f"Walk-in to see {emp_name}",
+                            "visiting": emp_email,
+                        }
+                    updates: dict[str, Any] = {
+                        "matched_appointment": matched_appt,
+                        "employee_name": emp_email,
+                    }
+                    if visitor and not snap.visitor_name:
+                        updates["visitor_name"] = visitor
+                    self._session.transition(ReceptionState.APPOINTMENT_MATCHED, **updates)
+            else:
+                query = (args.get("name") or "").strip()
+                self._session.transition(
+                    ReceptionState.UNKNOWN_EMPLOYEE,
+                    error_message=f"No directory match for {query!r}",
+                )
+
+    @staticmethod
+    def _match_appointment(
+        calendar: list[dict[str, Any]],
+        visitor_name: Optional[str],
+    ) -> Optional[dict[str, Any]]:
+        """Case-insensitive name match against today's calendar entries.
+
+        Matching is layered so a visitor who says just their first name
+        ("Rohan") still resolves to a calendar entry like "Rohan Verma":
+
+        1. Exact match on the full string.
+        2. Calendar entry's first whitespace-delimited token equals the
+           visitor string ("Rohan" == first(\"Rohan Verma\")).
+        3. Substring of the calendar entry (\"rohan\" in \"rohan verma\").
+
+        Each layer returns the FIRST hit so we never silently switch which
+        calendar entry a visitor is mapped to. The minimum length guard
+        (>= 2 chars) keeps single-letter transcripts from matching half
+        the calendar.
+        """
+        if not visitor_name:
+            return None
+        target = visitor_name.strip().lower()
+        if len(target) < 2:
+            return None
+        for appt in calendar:
+            if (appt.get("name") or "").strip().lower() == target:
+                return appt
+        for appt in calendar:
+            name = (appt.get("name") or "").strip().lower()
+            tokens = name.split()
+            if tokens and tokens[0] == target:
+                return appt
+        for appt in calendar:
+            name = (appt.get("name") or "").strip().lower()
+            if target in name:
+                return appt
+        return None
+
+    def _auto_resolve_appointment(
+        self,
+        visitor_name: str,
+        appointments: Optional[list[dict[str, Any]]] = None,
+    ) -> None:
+        """Look up today's calendar for ``visitor_name`` and dispatch.
+
+        Called from the RECOGNIZED transition in both the register_guest
+        path and the face-recognition path so the bot doesn't have to
+        depend on the LLM calling get_today_calendar — production showed
+        the LLM acknowledging the visitor and then improvising next-step
+        questions instead of running the tool, so the email never went out.
+
+        ``appointments`` is an optional pre-fetched list. Async callers on
+        the realtime event loop preload it via ``calendar_data.get_appointments_async``
+        so the synchronous iCal HTTP call doesn't block the audio loop here.
+        When omitted, falls back to a sync fetch (safe from background threads
+        like the face worker).
+
+        Dispatches:
+          - APPOINTMENT_MATCHED with the matched appointment + host email,
+            if today's iCal has an entry whose ``name`` matches.
+          - NO_APPOINTMENT otherwise. The bot then offers to take a message
+            or route via lookup_employee.
+        """
+        if not visitor_name:
+            return
+        if appointments is None:
+            from reachy_mini_receptionist import calendar_data
+            appointments = calendar_data.get_appointments()
+        matched = self._match_appointment(appointments, visitor_name)
+        if matched:
+            self._session.transition(
+                ReceptionState.APPOINTMENT_MATCHED,
+                matched_appointment=matched,
+                employee_name=matched.get("visiting"),
+            )
+            logger.info(
+                "Auto-resolved appointment for %r -> %s",
+                visitor_name, matched.get("visiting"),
+            )
+        else:
+            self._session.transition(
+                ReceptionState.NO_APPOINTMENT,
+                error_message=f"No appointment found for {visitor_name!r}",
+            )
+            logger.info("Auto-resolve: no appointment for %r", visitor_name)
+
+
+# ----------------------------------------------------------------------
+# Per-state workflow hints
+# ----------------------------------------------------------------------
+# These get appended to the session context push so the LLM knows what to
+# do next — without the workflow being hardcoded in the system prompt.
+# Keep each hint short (one or two sentences) and concrete. The LLM has
+# already been told to wait for the user to speak before responding; these
+# hints describe what to do *when* the user speaks.
+
+_NEXT_ACTION_HINTS: dict[ReceptionState, str] = {
+    # IDLE is the "no visitor yet" state — normally we stay silent. BUT if a
+    # visitor speaks before the face worker has stabilised (camera obscured,
+    # off-angle, dim light), the bot would otherwise just greet generically
+    # and never advance. So when the user speaks during IDLE, treat the
+    # utterance as the start of the flow and dispatch immediately to the
+    # right tool based on what they said.
+    ReceptionState.IDLE: (
+        "If the visitor speaks first, just be conversational — greet them "
+        "and figure out who they are or who they want to see. If they named "
+        "themselves, confirm once ('I heard <name>, right?') then call "
+        "register_guest(name, confirmed=true). If they named a host, call "
+        "lookup_employee. ALWAYS respond — never go silent. If you mishear, "
+        "say so and ask again naturally; don't lecture."
+    ),
+    ReceptionState.VISITOR_DETECTED: (
+        "Greet the visitor warmly. Ask their name or who they're here to see "
+        "if they haven't said yet. When they tell you a name, repeat it back "
+        "briefly to confirm; if they say yes, call register_guest with the "
+        "EXACT name you heard from the visitor and confirmed=true. Never "
+        "invent a name. If they're here to see someone, call lookup_employee. "
+        "Be conversational — short, friendly replies. ALWAYS respond to "
+        "whatever they say; never go silent."
+    ),
+    ReceptionState.GREETING: (
+        "Greet the visitor. If they haven't said why they're here yet, "
+        "ask whether they have an appointment or are here to see someone."
+    ),
+    ReceptionState.ASK_NAME: (
+        "Ask the visitor their name or who they're here to see. When they "
+        "answer, confirm the name back briefly and if they say yes, call "
+        "register_guest(confirmed=true). If you genuinely couldn't hear, "
+        "ask once more naturally. Keep replies short and friendly."
+    ),
+    ReceptionState.MULTIPLE_PEOPLE: (
+        "More than one face is in view. Say 'I see more than one person — could "
+        "whoever's checking in step forward please?' Do NOT call register_guest, "
+        "lookup_employee, or send_email until the state changes back."
+    ),
+    ReceptionState.RECOGNIZED: (
+        "Acknowledge the visitor by name. "
+        "Then call get_today_calendar to look up their appointment."
+    ),
+    ReceptionState.CHECKING_APPOINTMENT: (
+        "Briefly let the visitor know you're checking the schedule."
+    ),
+    ReceptionState.APPOINTMENT_MATCHED: (
+        "Use the appointment= and employee= values from the context above. "
+        "Say something like: 'Great, I have you down for <appointment> with "
+        "<employee> — I'll let them know you're here.' Then immediately call "
+        "send_email to that host. If visitor= is empty, ask their name first."
+    ),
+    ReceptionState.NO_APPOINTMENT: (
+        "Politely tell the visitor you don't have them on today's schedule. "
+        "Offer to take a message or notify someone."
+    ),
+    ReceptionState.NOTIFYING_EMPLOYEE: (
+        "Briefly tell the visitor you're notifying their host."
+    ),
+    ReceptionState.NOTIFIED: (
+        "Use the employee= from context. Say: 'Done — I've notified <employee>. "
+        "Please have a seat, they'll be with you shortly.' Be warm, not robotic."
+    ),
+    ReceptionState.EMAIL_FAILED: (
+        "Apologize that you couldn't reach the host right now. "
+        "Suggest the visitor wait briefly while you try again."
+    ),
+    ReceptionState.WAITING: "",
+    ReceptionState.COMPLETE: (
+        "Thank the visitor warmly and wish them a good day."
+    ),
+    ReceptionState.UNKNOWN_EMPLOYEE: (
+        "Tell the visitor that name isn't in your directory. "
+        "Offer to find someone else who can help."
+    ),
+    ReceptionState.ERROR: (
+        "Apologize for the issue and ask the visitor to wait a moment."
+    ),
+}
+
+
+def next_action_hint(state: ReceptionState) -> str:
+    """Return a short workflow directive for the LLM based on the current state."""
+    return _NEXT_ACTION_HINTS.get(state, "")
+
+
+# States that require the bot to speak IMMEDIATELY when entered, because the
+# transition was triggered by an in-flight LLM response cycle (tool returned,
+# state advanced — visitor is waiting for the bot to finish what it started).
+# All others (face events, idle/reset) wait for the visitor to speak first.
+_SPEAK_NOW_STATES: frozenset[ReceptionState] = frozenset({
+    # Greet the visitor as soon as the face is detected. Previously the bot
+    # would silently wait for the visitor to speak first, which gave the
+    # impression of an unresponsive robot — visitors often hesitate when
+    # they don't know if the bot is "on" yet.
+    ReceptionState.VISITOR_DETECTED,
+    ReceptionState.RECOGNIZED,
+    ReceptionState.APPOINTMENT_MATCHED,
+    ReceptionState.NO_APPOINTMENT,
+    ReceptionState.NOTIFIED,
+    ReceptionState.EMAIL_FAILED,
+    ReceptionState.UNKNOWN_EMPLOYEE,
+})
+
+
+def should_speak_immediately(state: ReceptionState) -> bool:
+    """True if entering ``state`` should trigger an immediate spoken response.
+
+    For these states the LLM is mid-flow (just ran a tool, state advanced)
+    and the visitor is waiting. For all other states (face events,
+    timeouts, manual resets) the bot waits for the visitor to speak.
+    """
+    return state in _SPEAK_NOW_STATES

src/reachy_mini_receptionist/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/reachy_mini_receptionist/employees.py

@@ -0,0 +1,121 @@
+"""Employee directory — read API used by tools, calendar, and the LLM.
+
+Two-tier source:
+
+1. **Primary**: ``EmployeeStore`` (SQLite), populated and edited via the
+   dashboard's Employees panel.
+2. **Fallback**: the hardcoded ``_SEED_EMPLOYEES`` constant below. This
+   only takes effect when the store is unset (e.g. tests that import
+   ``employees`` directly) OR when the store is empty. On a real
+   deployment, ``main.py`` constructs the store and seeds it with
+   ``_SEED_EMPLOYEES`` on first run; after that, edits via the
+   dashboard are the source of truth.
+
+Consumers (``lookup_employee``, ``find_email_for``, ``get_all_employees``,
+``format_for_llm``) keep the same signatures so ``calendar_data`` and the
+``lookup_employee`` tool need zero changes.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Optional, TypedDict
+
+logger = logging.getLogger(__name__)
+
+
+class Employee(TypedDict, total=False):
+    name: str
+    email: str
+    aliases: List[str]
+    title: Optional[str]
+
+
+# Seed list intentionally empty. A brand-new install starts with zero
+# employees and the dashboard's Employees panel shows an empty state
+# with a "+ Add" button — that's a clearer first-run UX than pre-loading
+# dummy entries the operator has to delete one by one before adding
+# their real team. The seed-load mechanism in employees_store.py is
+# preserved for callers that want to bundle a seed list (e.g. a future
+# import-from-CSV path).
+_SEED_EMPLOYEES: List[Employee] = []
+
+
+# Process-wide reference to the active store. ``main.py`` calls
+# ``set_store(...)`` after construction. Kept ``None`` in tests / imports
+# that don't go through main, in which case we fall back to the seed list.
+_store: Any = None
+
+
+def set_store(store: Any) -> None:
+    """Register the EmployeeStore the module should read from."""
+    global _store
+    _store = store
+    logger.info("employees: bound to store (count=%s)", store.count() if store else "n/a")
+
+
+def _strip_internal(emp: dict[str, Any]) -> Employee:
+    """Drop SQLite-side fields the LLM doesn't need (id, created_at, etc)."""
+    return {  # type: ignore[return-value]
+        "name": emp.get("name", ""),
+        "email": emp.get("email", ""),
+        "aliases": list(emp.get("aliases") or []),
+        "title": emp.get("title"),
+    }
+
+
+def _normalize(s: str) -> str:
+    return (s or "").strip().lower()
+
+
+def get_all_employees() -> List[Employee]:
+    """Return a snapshot of the full directory."""
+    if _store is not None:
+        try:
+            rows = _store.list_all()
+            if rows:
+                return [_strip_internal(r) for r in rows]
+        except Exception as e:
+            logger.warning("employees.get_all_employees: store read failed (%s); using seed", e)
+    return [dict(e) for e in _SEED_EMPLOYEES]  # type: ignore[misc]
+
+
+def lookup_employee(query: str) -> Optional[Employee]:
+    """Find an employee by name or alias (case-insensitive, exact-only)."""
+    if not (query or "").strip():
+        return None
+    if _store is not None:
+        try:
+            hit = _store.lookup(query)
+            if hit:
+                return _strip_internal(hit)
+        except Exception as e:
+            logger.warning("employees.lookup_employee: store read failed (%s); using seed", e)
+    q = _normalize(query)
+    if not q:
+        return None
+    for emp in _SEED_EMPLOYEES:
+        if _normalize(emp.get("name", "")) == q:
+            return dict(emp)  # type: ignore[return-value]
+        for alias in emp.get("aliases", []) or []:
+            if _normalize(alias) == q:
+                return dict(emp)  # type: ignore[return-value]
+    return None
+
+
+def find_email_for(query: str) -> Optional[str]:
+    """Convenience: resolve a name/alias to an email, or None."""
+    emp = lookup_employee(query)
+    return emp.get("email") if emp else None
+
+
+def format_for_llm() -> str:
+    """Render the directory as a short string the LLM can reference."""
+    employees = get_all_employees()
+    if not employees:
+        return "Employee directory is empty."
+    lines = ["Employee directory:"]
+    for emp in employees:
+        aliases = emp.get("aliases") or []
+        alias_str = f" (also: {', '.join(aliases)})" if aliases else ""
+        lines.append(f"  - {emp.get('name', '?')}{alias_str}")
+    return "\n".join(lines)

src/reachy_mini_receptionist/employees_store.py

@@ -0,0 +1,342 @@
+"""SQLite-backed employee directory CRUD.
+
+The dashboard's Employees panel uses this; ``employees.py`` reads from
+this store too (with a fall-through to the hardcoded ``_EMPLOYEES`` list
+when the store is empty, which only happens on a brand-new install
+before the seed runs).
+
+Schema matches the operator's mental model: name, email, optional title,
+optional list of aliases the bot might hear (e.g. "AJ" for "Arjun
+Mehta"). Name uniqueness is enforced case-insensitively so the bot can
+never end up with two "Mukul" entries that route differently.
+
+Lives next to ``visitor_log.db`` in the app's instance directory. Uses
+the same WAL + per-call connection pattern.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Iterable, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS employees (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    name        TEXT NOT NULL,
+    email       TEXT NOT NULL,
+    title       TEXT,
+    aliases     TEXT,
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_employees_name_lower
+    ON employees (LOWER(name));
+"""
+
+
+class EmployeeExistsError(Exception):
+    """Raised when an employee name (case-insensitive) already exists."""
+
+
+class EmployeeNotFoundError(Exception):
+    """Raised when a CRUD operation targets a missing employee id."""
+
+
+class EmployeeStore:
+    """Thread-safe employee directory backed by a single SQLite file."""
+
+    def __init__(self, db_path: str | Path) -> None:
+        self._db_path = Path(db_path)
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._init_schema()
+        logger.info("EmployeeStore initialised at %s", self._db_path)
+
+    # ------------------------------------------------------------------
+    # Connection / schema
+    # ------------------------------------------------------------------
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, check_same_thread=False, timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA synchronous=NORMAL")
+        return conn
+
+    def _init_schema(self) -> None:
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.execute("PRAGMA journal_mode=WAL")
+                conn.executescript(_SCHEMA)
+                conn.commit()
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------
+    # Row <-> dict helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _row_to_dict(row: sqlite3.Row) -> dict[str, Any]:
+        aliases_raw = row["aliases"] or "[]"
+        try:
+            aliases = json.loads(aliases_raw)
+            if not isinstance(aliases, list):
+                aliases = []
+        except Exception:
+            aliases = []
+        return {
+            "id": row["id"],
+            "name": row["name"],
+            "email": row["email"],
+            "title": row["title"],
+            "aliases": aliases,
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+
+    @staticmethod
+    def _aliases_to_text(aliases: Optional[Iterable[str]]) -> str:
+        cleaned = []
+        seen: set[str] = set()
+        for a in aliases or []:
+            s = (a or "").strip()
+            if not s:
+                continue
+            key = s.lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            cleaned.append(s)
+        return json.dumps(cleaned)
+
+    # ------------------------------------------------------------------
+    # Reads
+    # ------------------------------------------------------------------
+
+    def list_all(self) -> List[dict[str, Any]]:
+        with self._lock:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    "SELECT * FROM employees ORDER BY LOWER(name)",
+                ).fetchall()
+            finally:
+                conn.close()
+        return [self._row_to_dict(r) for r in rows]
+
+    def count(self) -> int:
+        with self._lock:
+            conn = self._connect()
+            try:
+                row = conn.execute("SELECT COUNT(*) AS n FROM employees").fetchone()
+            finally:
+                conn.close()
+        return int(row["n"]) if row else 0
+
+    def get_by_id(self, employee_id: int) -> Optional[dict[str, Any]]:
+        with self._lock:
+            conn = self._connect()
+            try:
+                row = conn.execute(
+                    "SELECT * FROM employees WHERE id = ?",
+                    (int(employee_id),),
+                ).fetchone()
+            finally:
+                conn.close()
+        return self._row_to_dict(row) if row else None
+
+    def lookup(self, query: str) -> Optional[dict[str, Any]]:
+        """Find an employee by name OR alias (case-insensitive, exact match).
+
+        Mirrors the original ``employees.lookup_employee`` semantics — exact
+        match only so that "Sam" can never silently route to "Samira".
+        """
+        q = (query or "").strip().lower()
+        if not q:
+            return None
+        with self._lock:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    "SELECT * FROM employees WHERE LOWER(name) = ?",
+                    (q,),
+                ).fetchall()
+                if rows:
+                    return self._row_to_dict(rows[0])
+                all_rows = conn.execute("SELECT * FROM employees").fetchall()
+            finally:
+                conn.close()
+        for row in all_rows:
+            d = self._row_to_dict(row)
+            for alias in d.get("aliases") or []:
+                if (alias or "").strip().lower() == q:
+                    return d
+        return None
+
+    # ------------------------------------------------------------------
+    # Writes
+    # ------------------------------------------------------------------
+
+    def create(
+        self,
+        name: str,
+        email: str,
+        aliases: Optional[Iterable[str]] = None,
+        title: Optional[str] = None,
+    ) -> dict[str, Any]:
+        name = (name or "").strip()
+        email = (email or "").strip()
+        if not name:
+            raise ValueError("name is required")
+        if not email:
+            raise ValueError("email is required")
+        aliases_text = self._aliases_to_text(aliases)
+        now = datetime.utcnow().isoformat(timespec="seconds")
+        with self._lock:
+            conn = self._connect()
+            try:
+                try:
+                    cur = conn.execute(
+                        """
+                        INSERT INTO employees (name, email, title, aliases, created_at, updated_at)
+                        VALUES (?, ?, ?, ?, ?, ?)
+                        """,
+                        (name, email, (title or None), aliases_text, now, now),
+                    )
+                    conn.commit()
+                    new_id = cur.lastrowid
+                except sqlite3.IntegrityError as e:
+                    raise EmployeeExistsError(
+                        f"An employee named {name!r} already exists (case-insensitive)"
+                    ) from e
+                row = conn.execute(
+                    "SELECT * FROM employees WHERE id = ?",
+                    (new_id,),
+                ).fetchone()
+            finally:
+                conn.close()
+        logger.info("EmployeeStore.create: id=%s name=%r email=%r", new_id, name, email)
+        return self._row_to_dict(row)
+
+    def update(
+        self,
+        employee_id: int,
+        *,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        aliases: Optional[Iterable[str]] = None,
+        title: Optional[str] = None,
+    ) -> Optional[dict[str, Any]]:
+        sets: List[str] = []
+        params: List[Any] = []
+        if name is not None:
+            cleaned = name.strip()
+            if not cleaned:
+                raise ValueError("name cannot be empty")
+            sets.append("name = ?")
+            params.append(cleaned)
+        if email is not None:
+            cleaned = email.strip()
+            if not cleaned:
+                raise ValueError("email cannot be empty")
+            sets.append("email = ?")
+            params.append(cleaned)
+        if aliases is not None:
+            sets.append("aliases = ?")
+            params.append(self._aliases_to_text(aliases))
+        if title is not None:
+            sets.append("title = ?")
+            params.append(title.strip() or None)
+        if not sets:
+            # Nothing to update; return current row.
+            return self.get_by_id(employee_id)
+        sets.append("updated_at = ?")
+        params.append(datetime.utcnow().isoformat(timespec="seconds"))
+        params.append(int(employee_id))
+        with self._lock:
+            conn = self._connect()
+            try:
+                try:
+                    cur = conn.execute(
+                        f"UPDATE employees SET {', '.join(sets)} WHERE id = ?",
+                        params,
+                    )
+                    conn.commit()
+                    if cur.rowcount == 0:
+                        return None
+                except sqlite3.IntegrityError as e:
+                    raise EmployeeExistsError(
+                        "Another employee already uses that name (case-insensitive)"
+                    ) from e
+                row = conn.execute(
+                    "SELECT * FROM employees WHERE id = ?",
+                    (int(employee_id),),
+                ).fetchone()
+            finally:
+                conn.close()
+        if row:
+            logger.info("EmployeeStore.update: id=%s -> %s", employee_id, dict(row))
+            return self._row_to_dict(row)
+        return None
+
+    def delete(self, employee_id: int) -> bool:
+        with self._lock:
+            conn = self._connect()
+            try:
+                cur = conn.execute(
+                    "DELETE FROM employees WHERE id = ?",
+                    (int(employee_id),),
+                )
+                conn.commit()
+                removed = cur.rowcount > 0
+            finally:
+                conn.close()
+        if removed:
+            logger.info("EmployeeStore.delete: id=%s", employee_id)
+        return removed
+
+    # ------------------------------------------------------------------
+    # Seeding
+    # ------------------------------------------------------------------
+
+    def seed_if_empty(self, employees: Iterable[dict[str, Any]]) -> int:
+        """Bulk-insert ``employees`` only if the table is currently empty.
+
+        Returns the number inserted. Idempotent across restarts — the
+        seed runs once on a brand-new install and is then a no-op.
+        Duplicate-name conflicts inside the seed list are skipped (the
+        first occurrence wins) so partial seeds don't abort the whole
+        batch.
+        """
+        if self.count() > 0:
+            return 0
+        inserted = 0
+        for emp in employees:
+            try:
+                self.create(
+                    name=emp.get("name", ""),
+                    email=emp.get("email", ""),
+                    aliases=emp.get("aliases") or [],
+                    title=emp.get("title"),
+                )
+                inserted += 1
+            except EmployeeExistsError:
+                logger.warning(
+                    "Seed: skipping duplicate %r", emp.get("name"),
+                )
+            except Exception as e:
+                logger.warning(
+                    "Seed: failed to insert %r: %s", emp.get("name"), e,
+                )
+        if inserted:
+            logger.info("EmployeeStore: seeded %d employee(s)", inserted)
+        return inserted

src/reachy_mini_receptionist/face_db.py

@@ -0,0 +1,184 @@
+"""File-based face store for OpenCV LBPH recognition.
+
+Design decisions:
+- Stores 100×100 grayscale face crops as PNG files named after the guest.
+  e.g.  guests/Beyonce.png, guests/Elon Musk.png
+- No database required — files are the database.  Easy to inspect, edit,
+  or delete with any file manager.
+- Max 100 guests. When full, the oldest file (by mtime) is replaced (FIFO).
+- Thread-safe: all writes use a threading.Lock.
+- The guests/ directory lives in the app instance directory so it persists
+  across restarts.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+MAX_GUESTS = 100
+
+
+def _safe_filename(name: str) -> str:
+    """Sanitise a guest name so it is safe to use as a filename."""
+    # Replace characters that are problematic on Windows/Linux/macOS
+    for ch in r'\/:*?"<>|':
+        name = name.replace(ch, "_")
+    return name.strip() or "unknown"
+
+
+class FaceDatabase:
+    """File-based face crop store (PNG per guest).
+
+    Public API is intentionally identical to the previous SQLite version so
+    that all callers (FaceRecognitionWorker, register_guest tool, API
+    endpoints) need zero changes.
+    """
+
+    def __init__(self, db_path: str | Path) -> None:
+        # Accept the old ``guests.db`` path and derive the sibling directory
+        # from it so the call-site in main.py doesn't need to change.
+        db_path = Path(db_path)
+        self._guests_dir = db_path.parent / "guests"
+        self._guests_dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        logger.info("FaceDatabase (file-based) initialised at %s", self._guests_dir)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _path_for(self, name: str) -> Path:
+        return self._guests_dir / f"{_safe_filename(name)}.png"
+
+    def _all_png_files(self) -> List[Path]:
+        """Return all .png files sorted newest-first (by mtime)."""
+        files = list(self._guests_dir.glob("*.png"))
+        files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        return files
+
+    # ------------------------------------------------------------------
+    # Write
+    # ------------------------------------------------------------------
+
+    def add_or_update_guest(self, name: str, face_crop: np.ndarray) -> None:
+        """Save a 100×100 grayscale face crop as ``<guests_dir>/<name>.png``.
+
+        If the directory already has MAX_GUESTS different entries and ``name``
+        is new, the oldest file (by mtime) is deleted first (FIFO eviction).
+        """
+        target = self._path_for(name)
+
+        with self._lock:
+            if not target.exists():
+                files = list(self._guests_dir.glob("*.png"))
+                if len(files) >= MAX_GUESTS:
+                    # Evict the oldest file
+                    oldest = min(files, key=lambda p: p.stat().st_mtime)
+                    oldest.unlink()
+                    logger.info("Evicted oldest guest file: %s (capacity=%d)", oldest.name, MAX_GUESTS)
+
+            ok = cv2.imwrite(str(target), face_crop)
+            if ok:
+                logger.info("Saved guest '%s' → %s", name, target)
+            else:
+                raise RuntimeError(f"cv2.imwrite failed for path: {target}")
+
+    # ------------------------------------------------------------------
+    # Read
+    # ------------------------------------------------------------------
+
+    def get_all_guests(self) -> List[dict]:
+        """Return all guests as dicts with keys: name, timestamp, thumbnail_url."""
+        with self._lock:
+            files = self._all_png_files()
+            result = []
+            for f in files:
+                mtime = f.stat().st_mtime
+                ts = datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M:%S")
+                guest_name = f.stem  # filename without .png extension
+                result.append({
+                    "name": guest_name,
+                    "timestamp": ts,
+                    "thumbnail_url": f"/guest_images/{f.name}",
+                })
+            return result
+
+    def get_all_guests_with_crops(self) -> List[Tuple[str, np.ndarray]]:
+        """Return list of (name, face_crop) for LBPH recognizer training."""
+        with self._lock:
+            files = self._all_png_files()
+            result = []
+            for f in files:
+                crop = cv2.imread(str(f), cv2.IMREAD_GRAYSCALE)
+                if crop is not None:
+                    result.append((f.stem, crop))
+                else:
+                    logger.warning("Could not read face crop from %s — skipping", f)
+            return result
+
+    def count(self) -> int:
+        with self._lock:
+            return len(list(self._guests_dir.glob("*.png")))
+
+    def clear(self) -> None:
+        """Wipe all guest images (useful for demo reset)."""
+        with self._lock:
+            for f in self._guests_dir.glob("*.png"):
+                f.unlink()
+            logger.info("FaceDatabase cleared")
+
+    def cleanup_older_than(self, max_age_days: float) -> int:
+        """Delete guest PNGs whose mtime is older than ``max_age_days``.
+
+        Returns the number of files removed. Pass 0 or negative to disable
+        cleanup (returns immediately). Failures to remove individual files
+        are logged but do not raise — TTL is best-effort.
+        """
+        import time as _t
+
+        if max_age_days <= 0:
+            return 0
+        cutoff = _t.time() - (max_age_days * 86400.0)
+        removed = 0
+        with self._lock:
+            for f in list(self._guests_dir.glob("*.png")):
+                try:
+                    if f.stat().st_mtime < cutoff:
+                        f.unlink()
+                        removed += 1
+                        logger.info(
+                            "Face TTL: removed %s (older than %.1f days)",
+                            f.name, max_age_days,
+                        )
+                except Exception as e:
+                    logger.warning("Face TTL: could not remove %s: %s", f, e)
+        return removed
+
+    def delete_guest(self, name: str) -> bool:
+        """Delete one guest PNG by name.
+
+        Returns True if the file existed and was removed, False otherwise.
+        """
+        target = self._path_for(name)
+        with self._lock:
+            if not target.exists():
+                return False
+            target.unlink()
+            logger.info("Deleted guest '%s' -> %s", name, target)
+            return True
+
+    # ------------------------------------------------------------------
+    # Expose the guests directory path (needed by main.py to mount statics)
+    # ------------------------------------------------------------------
+
+    @property
+    def guests_dir(self) -> Path:
+        return self._guests_dir

src/reachy_mini_receptionist/face_recognition_worker.py

@@ -0,0 +1,698 @@
+"""Background face recognition worker — OpenCV YuNet detection + LBPH recognition.
+
+Design decisions:
+- Uses cv2.FaceDetectorYN (YuNet) for face detection: returns a real confidence
+  score (0–1) per bounding box. Model (~400 KB ONNX) is downloaded to
+  ~/.cache/reachy_mini/ on first use.
+- Uses OpenCV LBPH (Local Binary Pattern Histogram) recognizer for identification.
+  Same algorithm used in embedded/microcontroller face recognition.
+- Runs in a daemon thread so it never blocks the audio/LLM loop.
+- Processes every Nth frame to keep CPU usage low.
+- Annotates frames with bounding boxes + labels for the MJPEG dashboard stream.
+- All shared state is protected by threading.Lock so tools can read safely.
+- Frames are pulled from CameraWorker (robot camera via SDK) rather than opening
+  a raw cv2.VideoCapture, so the correct camera is always used on Lite setups.
+
+Detection quality metrics:
+- Detection confidence (YuNet score 0–1): higher = more certain this is a face.
+  Used as a multiplier in the quality score so uncertain detections rank lower.
+- Blur score (Laplacian variance): cv2.Laplacian(crop, cv2.CV_64F).var()
+  High value = sharp / lots of edge detail → good crop.
+  Low value  = blurry / uniform → bad crop (head mid-motion, etc.).
+    Crops below _MIN_BLUR_SCORE are considered low-quality, but they are still
+    stored so dashboard previews and fallback checks can return "best available"
+    evidence instead of empty results.
+- Face area (w×h pixels) is kept as a secondary tiebreaker: among comparably sharp
+  crops the closer/larger face is still preferred.
+- Combined quality score: blur_score × log(face_area) × max(det_confidence, 0.01)
+
+Requirements: opencv-contrib-python  (pip install opencv-contrib-python)
+  The contrib package is a superset of opencv-python — don't install both.
+"""
+from __future__ import annotations
+
+import logging
+import math
+import pathlib
+import threading
+import time
+import urllib.request
+from collections import deque
+from typing import Any, Callable, Optional
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# How many frames to skip between recognition passes
+_PROCESS_EVERY_N_FRAMES = 10
+# LBPH confidence threshold: LOWER = stricter match (distance, not similarity).
+#
+# Calibration notes (single 100×100 grayscale crop per guest):
+#   ≤ 50      almost certainly the same person (well-lit, same angle)
+#   50 - 75   plausible match (different angle/lighting OK)
+#   75 - 100  weak — often false positives on similar-looking people
+#  100 - 160  printed photos, strangers who happen to resemble a guest
+#  > 160     unrelated face / no match
+#
+# Default was 110 which silently mis-recognised strangers as registered
+# guests (we saw a stranger scored 103 and got greeted as "Jon"). 75 is
+# the right starting point: prefers "I don't recognise you, please tell
+# me your name" over a wrong-greeting failure. Operators can tune via
+# the FACE_LBPH_THRESHOLD env var if their lighting/angles demand it.
+_DEFAULT_CONFIDENCE_THRESHOLD = 75.0
+
+
+def _resolve_threshold() -> float:
+    """Read FACE_LBPH_THRESHOLD env var, falling back to the default."""
+    import os
+    try:
+        raw = os.getenv("FACE_LBPH_THRESHOLD")
+        if raw is None or not str(raw).strip():
+            return _DEFAULT_CONFIDENCE_THRESHOLD
+        val = float(raw)
+        if val <= 0:
+            return _DEFAULT_CONFIDENCE_THRESHOLD
+        return val
+    except Exception:
+        return _DEFAULT_CONFIDENCE_THRESHOLD
+
+
+_CONFIDENCE_THRESHOLD = _resolve_threshold()
+# Minimum Laplacian variance for a crop to be accepted into the detection window.
+# Laplacian variance measures image sharpness: high = sharp, low = blurry.
+# Typical values: sharp well-lit face 150–400, soft/distant face 60–120,
+# head mid-motion 5–40, total blur < 5.
+# Crops below this threshold are considered low quality and ranked lower.
+_MIN_BLUR_SCORE = 80.0  # lower to ~50 if valid faces get rejected; raise to ~120 if blur sneaks through
+
+# Central detection zone: fractions of frame dimensions.
+# Faces whose centre falls outside this zone are ignored.
+# 0.25 margin → active zone = middle 50% horizontally and 80% vertically.
+_ZONE_X_MARGIN = 0.25   # 25% margin on each side → 50% wide centre zone
+_ZONE_Y_MARGIN = 0.10   # 10% margin on top/bottom  → 80% tall centre zone
+
+# Rolling window duration (seconds) for selecting the best recent face crop.
+_BEST_FACE_WINDOW_SECONDS = 5.0
+# Minimum spread (seconds) between first and last detection in the window.
+# A face must have been continuously present for this long to be returned by
+# best_recent_face(). Prevents a briefly passing face from overriding the
+# person who has been standing in front of the robot for several seconds.
+_MIN_DWELL_SECONDS = 1.5
+
+# Stable identity transition settings for external face context events.
+# Observed identity must remain unchanged for _FACE_STATE_CONFIRM_SECONDS before
+# becoming the stable state, except no-face which uses a longer grace period.
+_FACE_STATE_CONFIRM_SECONDS = 1.2
+_NO_FACE_CONFIRM_SECONDS = 2.5
+# Slightly longer dwell for multi-person before promoting — people walking
+# past should not trip MULTIPLE_PEOPLE.
+_MULTIPLE_PEOPLE_CONFIRM_SECONDS = 1.5
+# Minimum interval between emitted external face events.
+_FACE_EVENT_COOLDOWN_SECONDS = 5.0
+# Minimum number of in-zone faces to be considered "multiple".
+# Set absurdly high to effectively DISABLE MULTIPLE_PEOPLE state — in the
+# pilot lobby, background people / posters were tripping the state too
+# easily and the bot would go silent mid-conversation. The state has no
+# SPEAK_NOW cue, so once triggered the visitor's speech is ignored until
+# the camera clears. For a single-receptionist deployment the largest-
+# face heuristic the worker already uses is enough to pick the visitor.
+_MULTIPLE_PEOPLE_THRESHOLD = 999
+
+# YuNet (cv2.FaceDetectorYN) detection settings
+_YUNET_SCORE_THRESHOLD = 0.6    # minimum per-face detection confidence (0–1)
+_YUNET_NMS_THRESHOLD = 0.3      # non-max suppression overlap threshold
+_YUNET_TOP_K = 5000             # max candidate detections before NMS
+_YUNET_MODEL_URL = (
+    "https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/"
+    "face_detection_yunet_2023mar.onnx"
+)
+_YUNET_CACHE_PATH = pathlib.Path.home() / ".cache" / "reachy_mini" / "face_detection_yunet_2023mar.onnx"
+
+
+def _ensure_yunet_model() -> pathlib.Path:
+    """Download the YuNet ONNX model (~400 KB) to cache if not already present."""
+    if not _YUNET_CACHE_PATH.exists():
+        _YUNET_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        logger.info("Downloading YuNet model → %s", _YUNET_CACHE_PATH)
+        urllib.request.urlretrieve(_YUNET_MODEL_URL, _YUNET_CACHE_PATH)
+        logger.info("YuNet model downloaded.")
+    return _YUNET_CACHE_PATH
+
+
+# Check LBPH recognizer availability (needs opencv-contrib-python)
+_LBPH_AVAILABLE = hasattr(cv2, "face") and hasattr(cv2.face, "LBPHFaceRecognizer_create")
+if not _LBPH_AVAILABLE:
+    logger.warning(
+        "cv2.face.LBPHFaceRecognizer_create not found. "
+        "Install opencv-contrib-python:  pip install opencv-contrib-python\n"
+        "Face recognition (identification) will be disabled; detection still works."
+    )
+
+
+def _build_lbph_recognizer(label_crops: list[tuple[int, np.ndarray]]) -> "cv2.face.LBPHFaceRecognizer | None":
+    """Train and return an LBPH recognizer from a list of (label_int, gray_crop) pairs."""
+    if not _LBPH_AVAILABLE or not label_crops:
+        return None
+    recognizer = cv2.face.LBPHFaceRecognizer_create()
+    labels = np.array([lc[0] for lc in label_crops], dtype=np.int32)
+    crops = [lc[1] for lc in label_crops]
+    recognizer.train(crops, labels)
+    return recognizer
+
+
+class FaceRecognitionWorker:
+    """Background thread that continuously detects and recognises faces.
+
+    Public API (thread-safe):
+        worker.current_name          → str  "Unknown" or registered name
+        worker.current_encoding      → Optional[np.ndarray]  raw face crop (grayscale)
+        worker.latest_annotated_jpeg → Optional[bytes]  MJPEG frame
+        worker.confidence            → float  0–100 LBPH confidence (lower = better)
+        worker.best_recent_face()    → (name, lbph_conf, crop) from 5-second window
+    """
+
+    def __init__(
+        self,
+        face_db,  # FaceDatabase instance
+        camera_worker=None,  # CameraWorker instance (pulls robot frames via SDK)
+        process_every_n: int = _PROCESS_EVERY_N_FRAMES,
+        confidence_threshold: float = _CONFIDENCE_THRESHOLD,
+    ) -> None:
+        self._face_db = face_db
+        self._camera_worker = camera_worker
+        self._process_every_n = process_every_n
+        self._confidence_threshold = confidence_threshold
+
+        # Shared state (read by tools and dashboard)
+        self._lock = threading.Lock()
+        self._current_name: str = "Unknown"
+        self._current_encoding: Optional[np.ndarray] = None  # grayscale face crop
+        self._latest_annotated_jpeg: Optional[bytes] = None
+        self._confidence: float = 0.0
+
+        # Stable face state for context event emission.
+        # state in {"no_face", "unknown", "known"}
+        now = time.monotonic()
+        self._stable_state: str = "no_face"
+        self._stable_name: str = "Unknown"
+        self._stable_since: float = now
+        self._candidate_state: str = "no_face"
+        self._candidate_name: str = "Unknown"
+        self._candidate_since: float = now
+        self._last_event_sent_at: float = 0.0
+        self._face_event_callback: Optional[Callable[[dict[str, Any]], None]] = None
+
+        # Rolling 5-second detection window: each entry is
+        # (timestamp: float, face_area: int, blur_score: float, crop: np.ndarray, det_confidence: float)
+        # face_area      = w * h in pixels — larger = more prominent / closer face
+        # blur_score     = Laplacian variance — higher = sharper crop
+        # det_confidence = YuNet score 0–1 — higher = more confident detection
+        # Entries with blur_score < _MIN_BLUR_SCORE are still added, but rank lower.
+        self._detection_window: deque = deque()
+
+        # Log buffer for dashboard debug panel (ring buffer, max 200 lines)
+        self._log_buffer: list[str] = []
+        self._log_lock = threading.Lock()
+
+        # LBPH recognizer — rebuilt whenever guests are added/changed
+        self._recognizer_lock = threading.Lock()
+        self._recognizer: Optional[object] = None  # cv2.face.LBPHFaceRecognizer
+        self._label_map: dict[int, str] = {}  # int label → guest name
+
+        self._stop_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+        # YuNet face detector — initialized in start()
+        self._detector: Optional[object] = None  # cv2.FaceDetectorYN
+        self._detector_input_size: tuple = (0, 0)
+
+    # ------------------------------------------------------------------
+    # Public read properties (thread-safe)
+    # ------------------------------------------------------------------
+
+    @property
+    def current_name(self) -> str:
+        with self._lock:
+            return self._current_name
+
+    @property
+    def current_encoding(self) -> Optional[np.ndarray]:
+        """Returns the latest detected face crop (grayscale numpy array) or None."""
+        with self._lock:
+            return self._current_encoding.copy() if self._current_encoding is not None else None
+
+    @property
+    def latest_annotated_jpeg(self) -> Optional[bytes]:
+        with self._lock:
+            return self._latest_annotated_jpeg
+
+    @property
+    def confidence(self) -> float:
+        with self._lock:
+            return self._confidence
+
+    def get_recent_logs(self, n: int = 50) -> list[str]:
+        with self._log_lock:
+            return list(self._log_buffer[-n:])
+
+    def set_face_event_callback(self, callback: Optional[Callable[[dict[str, Any]], None]]) -> None:
+        """Register a callback for stable face-state transition events."""
+        with self._lock:
+            self._face_event_callback = callback
+
+    def best_recent_face(
+        self,
+        window_seconds: float = _BEST_FACE_WINDOW_SECONDS,
+        require_dwell: bool = True,
+    ) -> tuple[str, float, Optional[np.ndarray]]:
+        """Return the best face seen in the last `window_seconds` seconds.
+
+        Selection strategy:
+        - Among all entries in the rolling detection window (entries with
+          blur_score < _MIN_BLUR_SCORE are never stored), pick the one with the
+          highest combined quality score:  blur_score * log(face_area)
+          This ranks sharpness first while using face area as a tiebreaker so
+          a large sharp face beats both a tiny sharp face and a large blurry one.
+        - Run LBPH recognition on that crop and return the result.
+        - If the window is empty (all recent crops were too blurry, or no face
+          seen) → return ("Unknown", 0.0, None).
+
+        This is intentionally called at tool-invocation time (not in the
+        background loop) so the LLM always queries the best available evidence
+        rather than a momentary snapshot.
+
+        Returns:
+            (name, lbph_confidence, crop)
+            name              — registered guest name or "Unknown"
+            lbph_confidence   — LBPH distance (lower = more certain match; 0 if no guests)
+            crop              — 100×100 grayscale numpy array, or None if window is empty
+        """
+        now = time.monotonic()
+        with self._lock:
+            # Prune stale entries
+            while self._detection_window and (now - self._detection_window[0][0]) > window_seconds:
+                self._detection_window.popleft()
+
+            if not self._detection_window:
+                return "Unknown", 0.0, None
+
+            # Optional dwell guard: for tool-calls we prefer stable evidence;
+            # for dashboard preview we may choose best available immediately.
+            if require_dwell:
+                timestamps = [e[0] for e in self._detection_window]
+                if max(timestamps) - min(timestamps) < _MIN_DWELL_SECONDS:
+                    return "Unknown", 0.0, None
+
+            # Pick the entry with the best combined quality: sharpness × log(area)
+            best = max(self._detection_window, key=lambda e: e[2] * math.log(max(e[1], 1)) * max(e[4], 0.01))
+            _ts, face_area, blur_score, crop, det_conf = best
+            crop_copy = crop.copy()
+
+        # Run LBPH recognition outside the lock (can be slow)
+        name, conf = self._recognize(crop_copy)
+        logger.debug(
+            "best_recent_face: face_area=%d blur=%.1f det_conf=%.2f name=%s lbph_conf=%.1f",
+            face_area, blur_score, det_conf, name, conf,
+        )
+        self._add_log(f"check_current_face → {name} (area={face_area}px², blur={blur_score:.1f}, det={det_conf:.2f}, lbph={conf:.1f})")
+        return name, conf, crop_copy
+
+    # ------------------------------------------------------------------
+    # Recognizer rebuild (called by register_guest tool after adding a guest)
+    # ------------------------------------------------------------------
+
+    def rebuild_recognizer(self) -> None:
+        """Rebuild the LBPH recognizer from the current guest database.
+
+        Call this after registering or updating a guest so the worker
+        immediately starts recognising the new face.
+        """
+        if not _LBPH_AVAILABLE:
+            return
+        guests = self._face_db.get_all_guests_with_crops()
+        if not guests:
+            with self._recognizer_lock:
+                self._recognizer = None
+                self._label_map = {}
+            self._add_log("Recognizer cleared (no guests)")
+            return
+
+        label_map: dict[int, str] = {}
+        label_crops: list[tuple[int, np.ndarray]] = []
+        for idx, (name, crop) in enumerate(guests):
+            label_map[idx] = name
+            label_crops.append((idx, crop))
+
+        recognizer = _build_lbph_recognizer(label_crops)
+        with self._recognizer_lock:
+            self._recognizer = recognizer
+            self._label_map = label_map
+        self._add_log(f"Recognizer rebuilt ({len(label_map)} guest(s))")
+        logger.info("LBPH recognizer rebuilt with %d guest(s)", len(label_map))
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        # Initialize YuNet detector (downloads model on first run)
+        try:
+            model_path = _ensure_yunet_model()
+            self._detector = cv2.FaceDetectorYN.create(
+                model=str(model_path),
+                config="",
+                input_size=(640, 480),
+                score_threshold=_YUNET_SCORE_THRESHOLD,
+                nms_threshold=_YUNET_NMS_THRESHOLD,
+                top_k=_YUNET_TOP_K,
+            )
+            self._detector_input_size = (640, 480)
+            logger.info("YuNet face detector initialized")
+            self._add_log("YuNet face detector initialized ✓")
+        except Exception as e:
+            logger.error("Failed to initialize YuNet detector: %s", e)
+            self._add_log(f"WARNING: YuNet detector failed to initialize: {e}")
+
+        # Build recognizer from existing DB on startup
+        self.rebuild_recognizer()
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True, name="face-recognition-worker")
+        self._thread.start()
+        logger.info("FaceRecognitionWorker started (camera_worker=%s)", self._camera_worker)
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=3.0)
+        logger.info("FaceRecognitionWorker stopped")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _add_log(self, msg: str) -> None:
+        ts = time.strftime("%H:%M:%S")
+        entry = f"[{ts}] {msg}"
+        with self._log_lock:
+            self._log_buffer.append(entry)
+            if len(self._log_buffer) > 200:
+                self._log_buffer = self._log_buffer[-200:]
+
+    def _emit_face_state_event(self, event: dict[str, Any]) -> None:
+        """Best-effort callback dispatch for external face context events."""
+        callback = None
+        with self._lock:
+            callback = self._face_event_callback
+        if callback is None:
+            return
+        try:
+            callback(event)
+        except Exception as e:
+            logger.warning("Failed to dispatch face state event: %s", e)
+
+    def _update_stable_state(
+        self,
+        observed_state: str,
+        observed_name: str,
+        lbph_confidence: float,
+        det_confidence: float,
+    ) -> None:
+        """Promote observed state into stable state with dwell and cooldown guards."""
+        now = time.monotonic()
+
+        with self._lock:
+            # Stage candidate transitions first.
+            candidate_changed = (
+                observed_state != self._candidate_state
+                or (observed_state == "known" and observed_name != self._candidate_name)
+            )
+            if candidate_changed:
+                self._candidate_state = observed_state
+                self._candidate_name = observed_name
+                self._candidate_since = now
+                return
+
+            if observed_state == "no_face":
+                required = _NO_FACE_CONFIRM_SECONDS
+            elif observed_state == "multiple":
+                required = _MULTIPLE_PEOPLE_CONFIRM_SECONDS
+            else:
+                required = _FACE_STATE_CONFIRM_SECONDS
+            if (now - self._candidate_since) < required:
+                return
+
+            previous_state = self._stable_state
+            previous_name = self._stable_name
+            stable_changed = (
+                observed_state != previous_state
+                or (observed_state == "known" and observed_name != previous_name)
+            )
+            if not stable_changed:
+                return
+
+            self._stable_state = observed_state
+            self._stable_name = observed_name
+            self._stable_since = now
+
+            # Public current_* values follow the stable state, not instantaneous observations.
+            self._current_name = observed_name if observed_state == "known" else "Unknown"
+            self._confidence = 0.0 if observed_state == "no_face" else float(lbph_confidence)
+
+            can_emit_event = (now - self._last_event_sent_at) >= _FACE_EVENT_COOLDOWN_SECONDS
+            if can_emit_event:
+                self._last_event_sent_at = now
+
+        self._add_log(
+            "Stable face: %s(%s) -> %s(%s)"
+            % (previous_state, previous_name, observed_state, observed_name)
+        )
+
+        if not can_emit_event:
+            self._add_log("Face context event skipped (cooldown)")
+            return
+
+        event_payload = {
+            "event": "face_state_changed",
+            "state": observed_state,
+            "name": observed_name if observed_state == "known" else None,
+            "previous_state": previous_state,
+            "previous_name": previous_name if previous_state == "known" else None,
+            "lbph_confidence": round(float(lbph_confidence), 2),
+            "detection_confidence": round(float(det_confidence), 3),
+            "timestamp": time.time(),
+        }
+        self._emit_face_state_event(event_payload)
+
+    def _detect_faces(self, frame: np.ndarray) -> list[tuple[int, int, int, int, int, float]]:
+        """Return list of (x, y, w, h, area, det_confidence) sorted by area descending.
+
+        Uses YuNet (cv2.FaceDetectorYN) which returns a real confidence score (0–1)
+        per bounding box. The detector input size is updated dynamically per frame.
+        """
+        if self._detector is None:
+            return []
+
+        h, w = frame.shape[:2]
+        if (w, h) != self._detector_input_size:
+            self._detector.setInputSize((w, h))
+            self._detector_input_size = (w, h)
+
+        _, faces = self._detector.detect(frame)
+        if faces is None or len(faces) == 0:
+            return []
+
+        results = [
+            (int(f[0]), int(f[1]), int(f[2]), int(f[3]), int(f[2] * f[3]), float(f[14]))
+            for f in faces
+        ]
+        results.sort(key=lambda r: r[4], reverse=True)
+        return results
+
+    def _recognize(self, gray_crop: np.ndarray) -> tuple[str, float]:
+        """Return (name, confidence) for a face crop. confidence is LBPH distance (lower = better match)."""
+        with self._recognizer_lock:
+            recognizer = self._recognizer
+            label_map = self._label_map
+
+        if recognizer is None or not label_map:
+            return "Unknown", 0.0
+
+        try:
+            resized = cv2.resize(gray_crop, (100, 100))
+            label_int, confidence = recognizer.predict(resized)
+            name = label_map.get(label_int, "Unknown")
+            if confidence <= self._confidence_threshold:
+                return name, float(confidence)
+            else:
+                return "Unknown", float(confidence)
+        except Exception as e:
+            logger.debug("LBPH predict error: %s", e)
+            return "Unknown", 0.0
+
+    # ------------------------------------------------------------------
+    # Main loop
+    # ------------------------------------------------------------------
+
+    def _run(self) -> None:
+        if self._camera_worker is None:
+            logger.warning("FaceRecognitionWorker: no camera_worker provided — face recognition disabled")
+            self._add_log("WARNING: No camera_worker — face recognition disabled")
+            return
+
+        self._add_log("Camera worker attached ✓ (OpenCV Haar + LBPH, robot camera)")
+
+        frame_count = 0
+        last_face_rects: list[tuple[int, int, int, int]] = []  # (x, y, w, h)
+        last_face_labels: list[str] = []
+
+        try:
+            while not self._stop_event.is_set():
+                frame = self._camera_worker.get_latest_frame()
+                if frame is None:
+                    time.sleep(0.05)
+                    continue
+
+                frame_count += 1
+                do_recognition = frame_count % self._process_every_n == 0
+
+                if do_recognition:
+                    rects = self._detect_faces(frame)  # sorted by area descending; (x,y,w,h,area,det_conf)
+
+                    # Filter to faces whose centre falls inside the central detection zone
+                    fh_full, fw_full = frame.shape[:2]
+                    _zx1 = fw_full * _ZONE_X_MARGIN
+                    _zx2 = fw_full * (1 - _ZONE_X_MARGIN)
+                    _zy1 = fh_full * _ZONE_Y_MARGIN
+                    _zy2 = fh_full * (1 - _ZONE_Y_MARGIN)
+                    rects = [
+                        (x, y, w, h, area, det_conf)
+                        for x, y, w, h, area, det_conf in rects
+                        if _zx1 <= (x + w / 2) <= _zx2 and _zy1 <= (y + h / 2) <= _zy2
+                    ]
+
+                    # Strip area/conf for annotation (keep (x,y,w,h) tuples)
+                    last_face_rects = [(x, y, w, h) for x, y, w, h, _area, _conf in rects]
+                    last_face_labels = []
+
+                    multiple_in_zone = len(rects) >= _MULTIPLE_PEOPLE_THRESHOLD
+                    if multiple_in_zone:
+                        # Multiple people in the central zone — defer
+                        # single-person identification until one comes forward.
+                        self._update_stable_state("multiple", "Unknown", 0.0, 0.0)
+
+                    if rects:
+                        # Best face = largest area (index 0 after sort)
+                        px, py, pw, ph, face_area, det_conf = rects[0]
+                        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+                        fh, fw = gray.shape[:2]
+                        # Clamp bbox to frame bounds (YuNet can return coords outside the frame)
+                        x1 = max(0, px)
+                        y1 = max(0, py)
+                        x2 = min(fw, px + pw)
+                        y2 = min(fh, py + ph)
+                        crop = gray[y1:y2, x1:x2]
+                        if crop.size == 0:
+                            last_face_labels.append("Face (bad crop)")
+                            continue
+                        resized_crop = cv2.resize(crop, (100, 100))
+
+                        # Compute sharpness via Laplacian variance (higher = sharper)
+                        blur_score = cv2.Laplacian(resized_crop, cv2.CV_64F).var()
+
+                        # Add every valid crop to the detection window; low blur crops
+                        # are naturally ranked lower by the quality score.
+                        now = time.monotonic()
+                        with self._lock:
+                            self._detection_window.append((now, face_area, blur_score, resized_crop.copy(), det_conf))
+                            # Prune entries older than the configured window
+                            while self._detection_window and (now - self._detection_window[0][0]) > _BEST_FACE_WINDOW_SECONDS:
+                                self._detection_window.popleft()
+                            # Keep current_encoding pointing to the best-quality crop in the window
+                            best_entry = max(self._detection_window, key=lambda e: e[2] * math.log(max(e[1], 1)) * max(e[4], 0.01))
+                            self._current_encoding = best_entry[3].copy()
+
+                        if blur_score < _MIN_BLUR_SCORE:
+                            logger.debug("Face crop rejected: blur_score=%.1f < threshold=%.1f", blur_score, _MIN_BLUR_SCORE)
+
+                        # Run LBPH recognition on the current crop for live display
+                        name, conf = self._recognize(resized_crop)
+
+                        # When 2+ faces are in the zone we already emitted
+                        # "multiple"; skip the per-person state emission so
+                        # we don't oscillate.
+                        if not multiple_in_zone:
+                            observed_state = "known" if name != "Unknown" else "unknown"
+                            observed_name = name if observed_state == "known" else "Unknown"
+                            self._update_stable_state(observed_state, observed_name, conf, det_conf)
+
+                        # Build labels for all detected faces
+                        for i, (x, y, w, h, area, conf_i) in enumerate(rects):
+                            if i == 0:
+                                det_tag = f"det={det_conf:.2f}"
+                                if name != "Unknown":
+                                    last_face_labels.append(f"Known: {name} (lbph={conf:.0f}) {det_tag}")
+                                else:
+                                    last_face_labels.append(f"Unknown (lbph={conf:.0f}) {det_tag}")
+                            else:
+                                last_face_labels.append(f"Face (det={conf_i:.2f})")
+                    else:
+                        # Prune the window even when no face detected
+                        now = time.monotonic()
+                        with self._lock:
+                            while self._detection_window and (now - self._detection_window[0][0]) > _BEST_FACE_WINDOW_SECONDS:
+                                self._detection_window.popleft()
+                            if not self._detection_window:
+                                self._current_encoding = None
+
+                        self._update_stable_state("no_face", "No face", 0.0, 0.0)
+
+                # Annotate frame and encode as JPEG
+                annotated = self._annotate_frame(frame, last_face_rects, last_face_labels)
+                _, jpeg = cv2.imencode(".jpg", annotated, [cv2.IMWRITE_JPEG_QUALITY, 70])
+                with self._lock:
+                    self._latest_annotated_jpeg = jpeg.tobytes()
+
+        except Exception as e:
+            logger.exception("FaceRecognitionWorker crashed: %s", e)
+            self._add_log(f"CRASH: {e}")
+        finally:
+            logger.info("FaceRecognitionWorker: stopped")
+
+    def _annotate_frame(
+        self,
+        frame: np.ndarray,
+        face_rects: list[tuple[int, int, int, int]],
+        labels: list[str],
+    ) -> np.ndarray:
+        """Draw bounding boxes and labels on the frame."""
+        out = frame.copy()
+
+        # Draw the active central detection zone
+        fh, fw = out.shape[:2]
+        zone_x1 = int(fw * _ZONE_X_MARGIN)
+        zone_y1 = int(fh * _ZONE_Y_MARGIN)
+        zone_x2 = int(fw * (1 - _ZONE_X_MARGIN))
+        zone_y2 = int(fh * (1 - _ZONE_Y_MARGIN))
+        cv2.rectangle(out, (zone_x1, zone_y1), (zone_x2, zone_y2), (0, 210, 210), 2)
+        cv2.putText(out, "Detection Zone", (zone_x1 + 4, zone_y1 + 18),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 210, 210), 1)
+
+        for i, (x, y, w, h) in enumerate(face_rects):
+            label = labels[i] if i < len(labels) else "Face"
+            is_known = label.startswith("Known:")
+            color = (0, 200, 0) if is_known else (0, 100, 255)  # green / orange
+
+            cv2.rectangle(out, (x, y), (x + w, y + h), color, 2)
+            cv2.rectangle(out, (x, y + h - 28), (x + w, y + h), color, cv2.FILLED)
+            cv2.putText(
+                out,
+                label,
+                (x + 4, y + h - 8),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.5,
+                (255, 255, 255),
+                1,
+            )
+        return out

src/reachy_mini_receptionist/gemini_live.py

@@ -0,0 +1,754 @@
+"""Gemini Live API handler — drop-in replacement for OpenaiRealtimeHandler.
+
+Same public surface as ``openai_realtime.OpenaiRealtimeHandler`` so the
+rest of the app (main.py, console.py, headless_personality_ui.py) can
+switch backends with one env var (``VOICE_BACKEND=gemini``) without
+code changes.
+
+Audio I/O is bidirectional PCM via Gemini's Live websocket. Tool
+calling, VAD, voice synthesis all delegated to Gemini.
+
+This module imports ``google.genai`` LAZILY inside ``start_up`` so the
+absence of the SDK does not break OpenAI-backend installs.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Final, Literal, Optional, Tuple
+
+import numpy as np
+from fastrtc import AdditionalOutputs, AsyncStreamHandler, wait_for_item, audio_to_int16
+from numpy.typing import NDArray
+from scipy.signal import resample
+
+from reachy_mini_receptionist.config import config
+from reachy_mini_receptionist.prompts import get_session_voice, get_session_instructions
+from reachy_mini_receptionist.tools.core_tools import (
+    ToolDependencies,
+    get_tool_specs,
+)
+from reachy_mini_receptionist.tools.background_tool_manager import (
+    ToolCallRoutine,
+    ToolNotification,
+    BackgroundToolManager,
+)
+
+logger = logging.getLogger(__name__)
+
+# Gemini Live expects 16 kHz PCM16 mono input; outputs 24 kHz PCM16.
+GEMINI_INPUT_SAMPLE_RATE: Final[int] = 16000
+GEMINI_OUTPUT_SAMPLE_RATE: Final[int] = 24000
+
+
+def _gemini_model_name() -> str:
+    """Resolve the Gemini Live model id (env-overridable).
+
+    Default is ``gemini-2.5-flash-native-audio-latest`` — confirmed
+    bidiGenerateContent-capable on the project's API key (queried
+    2026-05-20 against models.list endpoint). Set GEMINI_LIVE_MODEL
+    in .env to switch to e.g. gemini-2.5-flash-native-audio-preview-09-2025
+    or whatever else your project has allowlisted.
+    """
+    return (os.getenv("GEMINI_LIVE_MODEL") or "gemini-2.5-flash-native-audio-latest").strip()
+
+
+def _openai_tools_to_gemini(openai_tools: list[dict]) -> list[dict]:
+    """Translate OpenAI function-tool specs to Gemini function declarations.
+
+    OpenAI format:  {"type": "function", "name": "...", "description": "...",
+                     "parameters": {"type": "object", ...}}
+    Gemini format:  {"function_declarations": [
+                       {"name": "...", "description": "...",
+                        "parameters": {"type": "OBJECT", ...}}, ...]}
+    """
+    declarations: list[dict] = []
+    for tool in openai_tools or []:
+        if tool.get("type") != "function":
+            continue
+        name = tool.get("name")
+        if not name:
+            continue
+        decl = {
+            "name": name,
+            "description": tool.get("description", ""),
+        }
+        params = tool.get("parameters")
+        if params:
+            decl["parameters"] = params
+        declarations.append(decl)
+    return [{"function_declarations": declarations}] if declarations else []
+
+
+class GeminiLiveHandler(AsyncStreamHandler):
+    """Gemini Live API handler — mirror of OpenaiRealtimeHandler.
+
+    Same public surface as the OpenAI handler so the rest of the app
+    can switch backends via ``VOICE_BACKEND=gemini`` without code
+    changes elsewhere.
+    """
+
+    def __init__(
+        self,
+        deps: ToolDependencies,
+        gradio_mode: bool = False,
+        instance_path: Optional[str] = None,
+        session_manager: Any | None = None,
+        controller: Any | None = None,
+    ):
+        super().__init__(
+            expected_layout="mono",
+            output_sample_rate=GEMINI_OUTPUT_SAMPLE_RATE,
+            input_sample_rate=GEMINI_INPUT_SAMPLE_RATE,
+        )
+        self.deps = deps
+        self.gradio_mode = gradio_mode
+        self.instance_path = instance_path
+        self._session_manager = session_manager
+        self._controller = controller
+
+        self.output_queue: "asyncio.Queue[Tuple[int, NDArray[np.int16]] | AdditionalOutputs]" = asyncio.Queue()
+
+        self.session: Any = None  # google.genai live session, set in start_up
+        self._client: Any = None
+        self._runtime_loop: asyncio.AbstractEventLoop | None = None
+        self._shutdown_requested: bool = False
+
+        # Cumulative cost tracker (Gemini doesn't expose token costs the same way)
+        self.cumulative_cost: float = 0.0
+        self.start_time = asyncio.get_event_loop().time()
+        self.last_activity_time = self.start_time
+
+        # Background tool manager (same as OpenAI handler)
+        self.tool_manager = BackgroundToolManager()
+
+        # Tool-call args stash keyed by call_id, so the controller can see
+        # both args + result when the tool completes.
+        self._tool_call_args: dict[str, dict[str, Any]] = {}
+
+        # Last face event + session event sent to model (for /api endpoints)
+        self._face_event_lock = threading.Lock()
+        self._last_face_event_sent: dict[str, Any] | None = None
+        self._session_event_lock = threading.Lock()
+        self._last_session_event_sent: dict[str, Any] | None = None
+
+        # Pending events waiting for session to be ready
+        self._pending_face_event_lock = threading.Lock()
+        self._pending_face_event: dict[str, Any] | None = None
+        self._pending_session_event_lock = threading.Lock()
+        self._pending_session_event: dict[str, Any] | None = None
+
+        # idle-speech cue dedupe
+        self._idle_speech_cue_pushed: bool = False
+
+    # ------------------------------------------------------------------
+    # AsyncStreamHandler required methods
+    # ------------------------------------------------------------------
+
+    def copy(self) -> "GeminiLiveHandler":
+        return GeminiLiveHandler(
+            self.deps,
+            self.gradio_mode,
+            self.instance_path,
+            session_manager=self._session_manager,
+            controller=self._controller,
+        )
+
+    async def start_up(self) -> None:
+        """Connect to Gemini Live and run the event loop until shutdown."""
+        self._runtime_loop = asyncio.get_running_loop()
+
+        # Lazy import — only required when this backend is active.
+        try:
+            from google import genai
+            from google.genai import types as genai_types
+        except ImportError as e:
+            logger.error(
+                "google-genai SDK not installed. Install with: "
+                "pip install google-genai. Error: %s", e,
+            )
+            return
+
+        api_key = (os.getenv("GEMINI_API_KEY") or "").strip()
+        if not api_key:
+            logger.error("GEMINI_API_KEY not set — cannot start Gemini Live backend")
+            return
+
+        self._client = genai.Client(api_key=api_key, http_options={"api_version": "v1beta"})
+        model_id = _gemini_model_name()
+        logger.info("Gemini Live backend starting with model=%s", model_id)
+
+        # Build session config — instructions, voice, tools, VAD-equivalent
+        instructions = get_session_instructions()
+        voice = get_session_voice()
+        openai_tools = get_tool_specs()  # type: ignore[no-untyped-call]
+        gemini_tools = _openai_tools_to_gemini(openai_tools)
+
+        # Minimal config — back to known-good shape after the
+        # realtime_input_config attempt caused 1011 internal server
+        # errors. Will revisit low-latency VAD tuning via SDK-specific
+        # types once we confirm the exact accepted shape.
+        config_obj: dict[str, Any] = {
+            "response_modalities": ["AUDIO"],
+            "system_instruction": instructions,
+        }
+
+        # Half-cascade Live models (model name contains "-live-" but
+        # NOT "native-audio") require an explicit speech_config /
+        # voice_config to actually emit audio. Without it they degrade
+        # to 2-byte placeholder chunks and `resp.text`-only responses
+        # (observed 2026-05-21 with gemini-3.1-flash-live-preview).
+        # Native-audio models auto-select voice and REJECT voice_config
+        # with 1007 "Cannot extract voices from a non-audio request",
+        # so we conditionally apply this only when the model name says
+        # we should. Voice name override via env var.
+        model_lower = model_id.lower()
+        is_half_cascade = ("-live-" in model_lower or model_lower.endswith("-live-preview")) \
+                          and "native-audio" not in model_lower
+        if is_half_cascade:
+            voice_name = (os.getenv("GEMINI_LIVE_VOICE") or "Puck").strip() or "Puck"
+            config_obj["speech_config"] = {
+                "voice_config": {
+                    "prebuilt_voice_config": {"voice_name": voice_name},
+                },
+            }
+            # Half-cascade also benefits from explicit input/output
+            # transcription so we can log what the model heard / said
+            # for debugging. Empty dict = enable with defaults.
+            config_obj["input_audio_transcription"] = {}
+            config_obj["output_audio_transcription"] = {}
+            logger.info(
+                "Gemini Live: half-cascade model detected — adding "
+                "speech_config (voice=%s) + transcription", voice_name,
+            )
+
+        if gemini_tools:
+            config_obj["tools"] = gemini_tools
+
+        try:
+            async with self._client.aio.live.connect(model=model_id, config=config_obj) as session:
+                self.session = session
+                logger.info("Gemini Live connected.")
+                # Start background tool manager (same callback signature)
+                self.tool_manager.start_up(tool_callbacks=[self._handle_tool_result])
+
+                # Kick off conversation with a one-shot greeting prompt.
+                # With the tighter VAD config (400ms silence) we could
+                # in theory wait for visitor speech, but a proactive
+                # greeting keeps the demo natural — the bot says hi
+                # the moment a face is detected. Server VAD handles
+                # all subsequent visitor turns with low latency.
+                try:
+                    await session.send_client_content(
+                        turns=[{
+                            "role": "user",
+                            "parts": [{
+                                "text": (
+                                    "(Visitor just walked up. Greet them "
+                                    "very briefly in ONE short friendly "
+                                    "sentence and ask their name or who "
+                                    "they're here to see. Keep it under "
+                                    "8 words.)"
+                                ),
+                            }],
+                        }],
+                        turn_complete=True,
+                    )
+                    logger.info("Gemini Live: sent kick-off greeting prompt")
+                except Exception as e:
+                    logger.warning("Gemini Live: kick-off send failed: %s", e)
+
+                try:
+                    await self._run_event_loop()
+                except Exception as inner:
+                    logger.exception("Gemini Live event loop crashed: %s", inner)
+                finally:
+                    await self.tool_manager.shutdown()
+                    self.session = None
+                    logger.info("Gemini Live: session ended cleanly")
+        except Exception as e:
+            logger.exception("Gemini Live session failed: %s", e)
+            self.session = None
+
+    async def shutdown(self) -> None:
+        self._shutdown_requested = True
+        try:
+            if self.session is not None:
+                await self.session.close()
+        except Exception as e:
+            logger.debug("Gemini session close ignored: %s", e)
+        try:
+            await self.tool_manager.shutdown()
+        except Exception:
+            pass
+
+    async def receive(self, frame: Tuple[int, NDArray[np.int16]]) -> None:
+        """Stream visitor mic frames to Gemini Live."""
+        if self.session is None:
+            return
+        input_rate, audio_frame = frame
+        if audio_frame.ndim == 2:
+            if audio_frame.shape[1] > audio_frame.shape[0]:
+                audio_frame = audio_frame.T
+            if audio_frame.shape[1] > 1:
+                audio_frame = audio_frame[:, 0]
+        # Resample if needed
+        if self.input_sample_rate != input_rate:
+            audio_frame = resample(
+                audio_frame,
+                int(len(audio_frame) * self.input_sample_rate / input_rate),
+            )
+        audio_frame = audio_to_int16(audio_frame)
+        try:
+            await self.session.send_realtime_input(
+                audio={
+                    "data": audio_frame.tobytes(),
+                    "mime_type": f"audio/pcm;rate={self.input_sample_rate}",
+                },
+            )
+            # Log once after first frame so we know mic-to-Gemini path is live.
+            if not getattr(self, "_first_mic_frame_logged", False):
+                logger.info(
+                    "Gemini Live: first mic frame sent (input_rate=%d, target_rate=%d, samples=%d)",
+                    input_rate, self.input_sample_rate, len(audio_frame),
+                )
+                self._first_mic_frame_logged = True
+        except Exception as e:
+            logger.debug("Dropped mic frame: %s", e)
+
+    async def emit(self) -> Tuple[int, NDArray[np.int16]] | AdditionalOutputs | None:
+        # Optional idle/timeout reset like OpenAI handler
+        if self._session_manager is not None:
+            try:
+                self._session_manager.maybe_reset_if_stale()
+            except Exception:
+                pass
+        return await wait_for_item(self.output_queue)  # type: ignore[no-any-return]
+
+    # ------------------------------------------------------------------
+    # Event loop — read Gemini events and dispatch
+    # ------------------------------------------------------------------
+
+    async def _run_event_loop(self) -> None:
+        """Consume Gemini Live server events until session closes / shutdown.
+
+        Wraps session.receive() in an outer loop so the conversation
+        survives multiple turns. Gemini's receive() iterator can return
+        after a single turn in some SDK versions — when it exits we
+        re-enter as long as the session and shutdown flag say keep going.
+        """
+        if self.session is None:
+            return
+        event_count = 0
+        audio_chunks = 0
+        outer_iterations = 0
+        try:
+            while self.session is not None and not self._shutdown_requested:
+                outer_iterations += 1
+                logger.info("Gemini Live: receive() iteration %d starting", outer_iterations)
+                async for resp in self.session.receive():
+                    if self._shutdown_requested:
+                        break
+                    event_count += 1
+
+                    # Smoke test confirmed: resp.data IS the same audio
+                    # as server_content.model_turn.parts[].inline_data.data
+                    # (just a convenience shortcut). Use ONLY the shortcut
+                    # to avoid double-emit when both paths fire.
+                    data = getattr(resp, "data", None)
+                    if data:
+                        audio_chunks += 1
+                        arr = np.frombuffer(data, dtype=np.int16).reshape(1, -1)
+                        await self.output_queue.put((self.output_sample_rate, arr))
+                        self.last_activity_time = asyncio.get_event_loop().time()
+                        if audio_chunks == 1:
+                            logger.info("Gemini Live: first audio chunk received (%d bytes)", len(data))
+
+                    # text shortcut — concatenated text parts
+                    text = getattr(resp, "text", None)
+                    if text:
+                        logger.info("Gemini Live text: %r", text[:120])
+                        await self.output_queue.put(
+                            AdditionalOutputs({"role": "assistant", "content": text})
+                        )
+
+                    # server_content parsing for non-audio metadata + turn_complete
+                    server_content = getattr(resp, "server_content", None)
+                    if server_content is not None:
+                        # NOTE: audio chunks via model_turn.parts[].inline_data
+                        # are ALREADY surfaced via resp.data above — don't
+                        # re-emit. Just look at non-audio parts here.
+                        model_turn = getattr(server_content, "model_turn", None)
+                        if model_turn is not None:
+                            parts = getattr(model_turn, "parts", None) or []
+                            for part in parts:
+                                if getattr(part, "thought", False):
+                                    continue  # silently swallow chain-of-thought
+                                ptext = getattr(part, "text", None)
+                                if ptext and not text:  # avoid double-text-emit
+                                    logger.info("Gemini Live model_turn text: %r", ptext[:120])
+                                    await self.output_queue.put(
+                                        AdditionalOutputs({"role": "assistant", "content": ptext})
+                                    )
+
+                        in_tr = getattr(server_content, "input_transcription", None)
+                        if in_tr is not None:
+                            txt = (getattr(in_tr, "text", "") or "").strip()
+                            if txt:
+                                logger.info("Gemini Live input transcript: %r", txt)
+                                if self._session_manager is not None:
+                                    try:
+                                        self._session_manager.record_user_transcript(txt)
+                                    except Exception:
+                                        pass
+                                await self.output_queue.put(
+                                    AdditionalOutputs({"role": "user", "content": txt})
+                                )
+
+                        if getattr(server_content, "turn_complete", False):
+                            logger.info(
+                                "Gemini Live: model turn complete (events=%d, audio_chunks=%d)",
+                                event_count, audio_chunks,
+                            )
+                            audio_chunks = 0  # reset for next turn
+
+                    # Tool calls
+                    tool_call = getattr(resp, "tool_call", None)
+                    if tool_call is not None:
+                        fcs = getattr(tool_call, "function_calls", None) or []
+                        logger.info("Gemini Live: tool_call with %d function calls", len(fcs))
+                        for fc in fcs:
+                            await self._dispatch_function_call(fc)
+
+                logger.info(
+                    "Gemini Live: receive() iteration %d ended (events so far=%d). Looping.",
+                    outer_iterations, event_count,
+                )
+                # Small backoff so we don't spin if session is genuinely dead
+                await asyncio.sleep(0.1)
+        except Exception as e:
+            logger.warning("Gemini Live event loop exited with exception: %s", e)
+        finally:
+            logger.info(
+                "Gemini Live event loop: total iterations=%d, events=%d, audio_chunks=%d",
+                outer_iterations, event_count, audio_chunks,
+            )
+
+    async def _dispatch_function_call(self, fc: Any) -> None:
+        """Route a Gemini function call into the background tool manager."""
+        tool_name = getattr(fc, "name", None)
+        args_obj = getattr(fc, "args", {}) or {}
+        call_id = str(getattr(fc, "id", None) or uuid.uuid4())
+        if not tool_name:
+            return
+        # Normalize args dict
+        if not isinstance(args_obj, dict):
+            try:
+                args_obj = dict(args_obj)
+            except Exception:
+                args_obj = {}
+        args_json_str = json.dumps(args_obj)
+        self._tool_call_args[call_id] = args_obj
+        logger.info(
+            "Gemini tool call: %s call_id=%s args=%s", tool_name, call_id, args_json_str,
+        )
+        try:
+            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=False,
+            )
+        except Exception as e:
+            logger.warning("Failed to start Gemini tool '%s': %s", tool_name, e)
+
+    async def _handle_tool_result(self, bg_tool: ToolNotification) -> None:
+        """Send the tool result back to Gemini + notify the controller."""
+        if bg_tool.error is not None:
+            tool_result: dict[str, Any] = {"error": bg_tool.error}
+        elif bg_tool.result is not None:
+            tool_result = bg_tool.result
+        else:
+            tool_result = {"error": "No result"}
+
+        call_args = self._tool_call_args.pop(bg_tool.id, {})
+
+        # Send result back to Gemini Live
+        if self.session is not None:
+            try:
+                # Gemini expects function_responses with {id, name, response: {output: ...}}
+                await self.session.send_tool_response(
+                    function_responses=[{
+                        "id": bg_tool.id if isinstance(bg_tool.id, str) else None,
+                        "name": bg_tool.tool_name,
+                        "response": {"output": tool_result},
+                    }],
+                )
+            except Exception as e:
+                logger.debug("send_tool_response failed: %s", e)
+
+        # Surface tool result to dashboard chatbot
+        await self.output_queue.put(
+            AdditionalOutputs({
+                "role": "assistant",
+                "content": json.dumps(tool_result),
+                "metadata": {
+                    "title": f"🛠️ Used tool {bg_tool.tool_name}",
+                    "status": "done",
+                },
+            })
+        )
+
+        # Drive backend state transitions (same as OpenAI handler)
+        if self._controller is not None:
+            try:
+                await self._controller.on_tool_completed_async(
+                    bg_tool.tool_name, call_args, tool_result,
+                )
+            except Exception as e:
+                logger.warning(
+                    "ConversationController.on_tool_completed_async raised %s: %s",
+                    type(e).__name__, e,
+                )
+
+    # ------------------------------------------------------------------
+    # Public API — face + session context push (mirror of OpenAI handler)
+    # ------------------------------------------------------------------
+
+    def _stash_pending_face_event(self, face_event: dict[str, Any]) -> None:
+        with self._pending_face_event_lock:
+            self._pending_face_event = dict(face_event)
+
+    def _pop_pending_face_event(self) -> dict[str, Any] | None:
+        with self._pending_face_event_lock:
+            p = self._pending_face_event
+            self._pending_face_event = None
+            return p
+
+    async def _flush_pending_face_event(self) -> None:
+        p = self._pop_pending_face_event()
+        if p is not None:
+            try:
+                await self._push_face_context_event(p)
+            except Exception as e:
+                logger.debug("flush pending face event failed: %s", e)
+                self._stash_pending_face_event(p)
+
+    def notify_external_face_event(self, face_event: dict[str, Any]) -> None:
+        loop = self._runtime_loop
+        if loop is None or loop.is_closed() or self.session is None:
+            self._stash_pending_face_event(face_event)
+            return
+        try:
+            future = asyncio.run_coroutine_threadsafe(
+                self._push_face_context_event(face_event), loop,
+            )
+
+            def _done(fut: "asyncio.Future[None]") -> None:
+                try:
+                    fut.result()
+                except Exception as e:
+                    logger.debug("face event push failed: %s", e)
+                    self._stash_pending_face_event(face_event)
+
+            future.add_done_callback(_done)
+        except Exception as e:
+            logger.debug("schedule face event failed: %s", e)
+            self._stash_pending_face_event(face_event)
+
+    async def _push_face_context_event(self, face_event: dict[str, Any]) -> None:
+        if self.session is None:
+            self._stash_pending_face_event(face_event)
+            return
+        state = str(face_event.get("state", "unknown"))
+        name = face_event.get("name")
+        msg = (
+            f"[External face update {self.format_timestamp()}] "
+            f"state={state}; name={name}. Context only; don't respond unless the user speaks."
+        )
+        try:
+            # send_realtime_input(text=...) injects context without
+            # forcing a turn — perfect for face state updates that
+            # the model should know about but not respond to.
+            await self.session.send_realtime_input(text=msg)
+        except Exception as e:
+            logger.debug("send face context failed: %s", e)
+            self._stash_pending_face_event(face_event)
+            return
+
+        sent_at = time.time()
+        payload = {
+            "state": state,
+            "name": name,
+            "previous_state": face_event.get("previous_state"),
+            "previous_name": face_event.get("previous_name"),
+            "lbph_confidence": float(face_event.get("lbph_confidence") or 0.0),
+            "detection_confidence": float(face_event.get("detection_confidence") or 0.0),
+            "sent_at": sent_at,
+            "sent_at_iso": datetime.fromtimestamp(sent_at).strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        with self._face_event_lock:
+            self._last_face_event_sent = payload
+
+    def get_last_face_event_sent(self) -> dict[str, Any] | None:
+        with self._face_event_lock:
+            return dict(self._last_face_event_sent) if self._last_face_event_sent else None
+
+    # --- session events ---
+
+    def _stash_pending_session_event(self, payload: dict[str, Any]) -> None:
+        with self._pending_session_event_lock:
+            self._pending_session_event = dict(payload)
+
+    def _pop_pending_session_event(self) -> dict[str, Any] | None:
+        with self._pending_session_event_lock:
+            p = self._pending_session_event
+            self._pending_session_event = None
+            return p
+
+    async def _flush_pending_session_event(self) -> None:
+        p = self._pop_pending_session_event()
+        if p is not None:
+            try:
+                await self._push_session_context_event(p)
+            except Exception:
+                self._stash_pending_session_event(p)
+
+    def notify_session_event(self, previous_state: Any, new_state: Any, snapshot: Any) -> None:
+        try:
+            payload = {
+                "previous_state": getattr(previous_state, "value", str(previous_state)),
+                "new_state": getattr(new_state, "value", str(new_state)),
+                "snapshot": snapshot.to_dict() if hasattr(snapshot, "to_dict") else {},
+            }
+        except Exception:
+            return
+
+        if payload.get("new_state") == "idle":
+            self._idle_speech_cue_pushed = False
+
+        loop = self._runtime_loop
+        if loop is None or loop.is_closed() or self.session is None:
+            self._stash_pending_session_event(payload)
+            return
+        try:
+            future = asyncio.run_coroutine_threadsafe(
+                self._push_session_context_event(payload), loop,
+            )
+
+            def _done(fut: "asyncio.Future[None]") -> None:
+                try:
+                    fut.result()
+                except Exception:
+                    self._stash_pending_session_event(payload)
+
+            future.add_done_callback(_done)
+        except Exception:
+            self._stash_pending_session_event(payload)
+
+    async def _push_session_context_event(self, payload: dict[str, Any]) -> None:
+        if self.session is None:
+            self._stash_pending_session_event(payload)
+            return
+        snap = payload.get("snapshot") or {}
+        new_state_value = payload.get("new_state")
+        hint = ""
+        speak_now = False
+        try:
+            from reachy_mini_receptionist.conversation_controller import (
+                next_action_hint, should_speak_immediately,
+            )
+            from reachy_mini_receptionist.receptionist_state import ReceptionState
+            if new_state_value:
+                new_state_enum = ReceptionState(new_state_value)
+                hint = next_action_hint(new_state_enum)
+                speak_now = should_speak_immediately(new_state_enum)
+        except Exception:
+            pass
+
+        base = (
+            f"[Backend session update {self.format_timestamp()}] "
+            f"state: {payload.get('previous_state')} -> {new_state_value}; "
+            f"visitor={snap.get('visitor_name')}; "
+            f"employee={snap.get('employee_name')}; "
+            f"appointment={(snap.get('matched_appointment') or {}).get('time')}; "
+            f"email_sent_to={snap.get('email_sent_to')}."
+        )
+        if hint and speak_now:
+            msg = f"{base} SPEAK NOW: {hint}"
+        elif hint:
+            msg = f"{base} Next: {hint} (Stay quiet until the visitor speaks; context only.)"
+        else:
+            msg = f"{base} Context only; do not respond unless the user speaks."
+
+        try:
+            # For SPEAK_NOW transitions, use send_client_content with
+            # turn_complete=True so the model actually responds.
+            # Otherwise context-only via send_realtime_input(text=).
+            from reachy_mini_receptionist.conversation_controller import should_speak_immediately
+            from reachy_mini_receptionist.receptionist_state import ReceptionState
+            speak_now = False
+            try:
+                if new_state_value:
+                    speak_now = should_speak_immediately(ReceptionState(new_state_value))
+            except Exception:
+                pass
+
+            if speak_now:
+                await self.session.send_client_content(
+                    turns=[{
+                        "role": "user",
+                        "parts": [{"text": msg}],
+                    }],
+                    turn_complete=True,
+                )
+            else:
+                await self.session.send_realtime_input(text=msg)
+        except Exception as e:
+            logger.debug("session context push failed: %s", e)
+            return
+
+        sent_payload = {**payload, "sent_at": time.time(), "hint": hint}
+        with self._session_event_lock:
+            self._last_session_event_sent = sent_payload
+
+    def get_last_session_event_sent(self) -> dict[str, Any] | None:
+        with self._session_event_lock:
+            return dict(self._last_session_event_sent) if self._last_session_event_sent else None
+
+    # ------------------------------------------------------------------
+    # Personality + voice (UI hooks)
+    # ------------------------------------------------------------------
+
+    async def apply_personality(self, profile: str | None) -> str:
+        """Profile updates require a session restart — minimal impl."""
+        try:
+            from reachy_mini_receptionist.config import set_custom_profile
+            set_custom_profile(profile)
+            return "Personality updated. Restart for it to take effect (Gemini backend)."
+        except Exception as e:
+            return f"Failed to apply personality: {e}"
+
+    async def get_available_voices(self) -> list[str]:
+        """Gemini prebuilt voices (fixed list — no discovery API)."""
+        return ["Aoede", "Charon", "Kore", "Puck", "Fenrir"]
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def format_timestamp(self) -> str:
+        loop_time = asyncio.get_event_loop().time()
+        elapsed = loop_time - self.start_time
+        dt = datetime.now()
+        return f"[{dt.strftime('%Y-%m-%d %H:%M:%S')} | +{elapsed:.1f}s]"

src/reachy_mini_receptionist/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=["marin"], value="marin", 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 "marin"
+                vf = self._resolve_profile_dir(name) / "voice.txt"
+                if vf.exists():
+                    v = vf.read_text(encoding="utf-8").strip()
+                    return v or "marin"
+            except Exception:
+                pass
+            return "marin"
+
+        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 = "marin"
+                return gr.update(choices=voices, value=current)
+            except Exception:
+                return gr.update(choices=["marin"], value="marin")
+
+        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="marin"),
+                )
+            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 "marin").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/reachy_mini_receptionist/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 = "marin") -> 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 "marin").strip() + "\n", encoding="utf-8")

src/reachy_mini_receptionist/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] = "marin"
+
+    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 = "marin"
+        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 "marin"
+        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", "marin")) if raw.get("voice") is not None else "marin"
+
+        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 "marin")
+            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 "marin")
+        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 = "marin") -> 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 "marin")
+            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 ["marin"]
+
+        async def _get_v() -> list[str]:
+            try:
+                return await handler.get_available_voices()
+            except Exception:
+                return ["marin"]
+
+        try:
+            fut = asyncio.run_coroutine_threadsafe(_get_v(), loop)
+            return fut.result(timeout=10)
+        except Exception:
+            return ["marin"]

src/reachy_mini_receptionist/ical_calendar.py

@@ -0,0 +1,248 @@
+"""iCal calendar source for the receptionist.
+
+When ``RECEPTION_ICS_URL`` is set in the environment, ``calendar_data``
+uses this module to fetch today's appointments. The URL is typically a
+Google Calendar "Public address in iCal format" link
+(Settings -> Integrate calendar -> Public address in iCal format).
+When the URL is unset, ``calendar_data`` returns an empty schedule and
+the receptionist serves walk-in visitors only (via ``lookup_employee``).
+
+Operator convention for event titles:
+
+    "<Visitor name> with <Host name>"
+
+Examples:
+
+    "Rohan Verma with Mukul"
+    "Sara Khan with Priya"
+    "David Lee with Arjun Mehta"
+
+The host name (or alias) is matched against ``employees.py``. Add an
+optional " — note" suffix to the title or use the event's DESCRIPTION
+field for the note. The event's LOCATION field is used as a fallback host
+when the title doesn't contain " with ".
+
+Single-occurrence events only — RRULE recurrence is not expanded in v1.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import time
+from datetime import date, datetime
+from typing import Any, Dict, List, Optional, Tuple
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import httpx
+from icalendar import Calendar
+
+logger = logging.getLogger(__name__)
+
+_CACHE_TTL_SECONDS: float = 300.0
+_HTTP_TIMEOUT_SECONDS: float = 10.0
+
+_cache: Dict[str, Any] = {"fetched_at": 0.0, "data": [], "url": None, "valid": False}
+
+
+def _display_tz() -> Any:
+    """Return the timezone to use for displaying iCal event times.
+
+    Read from ``RECEPTION_TIMEZONE`` env var (e.g. ``Asia/Kolkata``,
+    ``America/New_York``). Defaults to ``Asia/Kolkata`` since the pilot
+    deployment is in India. Falls back to system local time on a bad
+    value rather than crashing the whole calendar fetch.
+    """
+    raw = (os.getenv("RECEPTION_TIMEZONE") or "Asia/Kolkata").strip()
+    try:
+        return ZoneInfo(raw)
+    except ZoneInfoNotFoundError:
+        logger.warning(
+            "RECEPTION_TIMEZONE=%r is not a valid IANA tz name — "
+            "falling back to system local time",
+            raw,
+        )
+        return None  # signals "use astimezone() default"
+
+
+# Visitor/host separators the operator may write in event titles. Order
+# matters — we try the most-specific phrasing first so "is here to see"
+# wins over a bare "to" if both appear. Case-insensitive match.
+_VISITOR_HOST_SEPARATORS: Tuple[str, ...] = (
+    " is here to see ",
+    " here to see ",
+    " to see ",
+    " meets with ",
+    " meeting with ",
+    " meeting ",
+    " meets ",
+    # Bare "meet" — added 2026-05-21 after the operator's calendar used
+    # the imperative form ("Krishna Meet Rohan", "Alex Meet Arjun"). Without
+    # this the title fails to split, host_query stays empty, and the bot
+    # falls back to a context-derived email instead of looking the host
+    # up in the employee directory.
+    " meet ",
+    " with ",
+    " for ",
+    " -> ",
+    " → ",
+)
+
+
+def _parse_summary(summary: str) -> Tuple[str, str, Optional[str]]:
+    """Split a SUMMARY into (visitor_name, host_query, inline_note).
+
+    Visitor/host separator: any of ``_VISITOR_HOST_SEPARATORS``
+    (case-insensitive). Note separator (applied to the rest after host
+    extraction): ``" — "``, ``" - "``, ``": "``.
+
+    Returns ``(text, "", None)`` if no visitor/host separator is found —
+    the caller can then fall back to LOCATION for the host.
+    """
+    if not summary:
+        return ("", "", None)
+    text = summary.strip()
+    lower = text.lower()
+    sep_idx = -1
+    sep_len = 0
+    for sep in _VISITOR_HOST_SEPARATORS:
+        idx = lower.find(sep)
+        if idx >= 0 and (sep_idx < 0 or idx < sep_idx):
+            sep_idx = idx
+            sep_len = len(sep)
+    if sep_idx < 0:
+        return (text, "", None)
+    visitor = text[:sep_idx].strip()
+    rest = text[sep_idx + sep_len:].strip()
+    note: Optional[str] = None
+    for delim in (" — ", " - ", ": "):
+        d = rest.find(delim)
+        if d >= 0:
+            note = rest[d + len(delim):].strip()
+            rest = rest[:d].strip()
+            break
+    return (visitor, rest, note)
+
+
+def _format_time(dt: Any) -> str:
+    """Format a datetime as 'H:MM AM/PM' in the display timezone.
+
+    iCal feeds frequently serialise event times in UTC (or with a TZID
+    pointing to a different region). We convert to ``RECEPTION_TIMEZONE``
+    (default ``Asia/Kolkata``) before formatting so an operator
+    scheduling "1 PM" in IST sees "1:00 PM" on the dashboard, not
+    "7:30 AM" (UTC) — regardless of what timezone the robot's OS is in.
+    """
+    if isinstance(dt, datetime):
+        if dt.tzinfo is not None:
+            tz = _display_tz()
+            local = dt.astimezone(tz) if tz is not None else dt.astimezone()
+        else:
+            local = dt
+        return local.strftime("%I:%M %p").lstrip("0")
+    return "all day"
+
+
+def _local_event_date(start: Any) -> date:
+    """Return the display-tz date of an event's DTSTART."""
+    if isinstance(start, datetime):
+        if start.tzinfo is not None:
+            tz = _display_tz()
+            return (start.astimezone(tz) if tz is not None else start.astimezone()).date()
+        return start.date()
+    return start  # already a date
+
+
+def _today_events(cal: Calendar, today: date) -> List[Dict[str, Any]]:
+    """Walk a parsed Calendar and return the events that fall on ``today``."""
+    out: List[Dict[str, Any]] = []
+    for event in cal.walk("VEVENT"):
+        dtstart = event.get("DTSTART")
+        if dtstart is None:
+            continue
+        start = dtstart.dt
+        if _local_event_date(start) != today:
+            continue
+        summary = str(event.get("SUMMARY") or "")
+        description = str(event.get("DESCRIPTION") or "").strip()
+        location = str(event.get("LOCATION") or "").strip()
+        visitor, host_from_title, inline_note = _parse_summary(summary)
+        host_query = host_from_title or location
+        # Only surface a note when there's something beyond the title — never
+        # echo the SUMMARY back into ``note`` (that just makes the LLM
+        # context noisier without adding information).
+        note = inline_note or description or ""
+        out.append({
+            "time": _format_time(start),
+            "name": visitor or summary,
+            "note": note,
+            "_host_query": host_query,
+            "_dt": start,
+        })
+    out.sort(key=_sort_key)
+    return out
+
+
+def _sort_key(event: Dict[str, Any]) -> datetime:
+    dt = event.get("_dt")
+    if isinstance(dt, datetime):
+        return dt.replace(tzinfo=None) if dt.tzinfo is None else dt.astimezone().replace(tzinfo=None)
+    if isinstance(dt, date):
+        return datetime.combine(dt, datetime.min.time())
+    return datetime.min
+
+
+def _fetch_ics(url: str) -> str:
+    resp = httpx.get(url, timeout=_HTTP_TIMEOUT_SECONDS, follow_redirects=True)
+    resp.raise_for_status()
+    return resp.text
+
+
+def fetch_appointments(ics_url: str, today: Optional[date] = None) -> List[Dict[str, Any]]:
+    """Return today's appointments from the iCal URL, cached for ~5 minutes.
+
+    On any fetch/parse failure returns the last successful cache (or empty
+    list if there's no cache yet) and logs a warning. Each appointment dict
+    has keys:
+
+        time         (str)  — "H:MM AM/PM" or "all day"
+        name         (str)  — visitor name parsed from SUMMARY
+        note         (str)  — inline note, DESCRIPTION, or SUMMARY fallback
+        _host_query  (str)  — host name/alias from SUMMARY ' with ' or LOCATION
+        _dt          (datetime|date) — event start, for downstream use
+
+    Resolution of ``_host_query`` to an email is the caller's job
+    (calendar_data.py uses ``employees.find_email_for``).
+    """
+    if today is None:
+        tz = _display_tz()
+        today = (datetime.now(tz) if tz is not None else datetime.now().astimezone()).date()
+    now = time.time()
+    # Cache freshness is tracked by ``valid`` + ``fetched_at`` only. An empty
+    # list is a legitimate cached result ("no appointments today") — treating
+    # ``data`` truthiness as the freshness flag would force a re-fetch on
+    # every call on an empty-calendar day, which on the receptionist hot path
+    # blocks the audio loop with a synchronous HTTP call per request.
+    if (
+        _cache["url"] == ics_url
+        and _cache["valid"]
+        and (now - _cache["fetched_at"]) < _CACHE_TTL_SECONDS
+    ):
+        return list(_cache["data"])
+    try:
+        text = _fetch_ics(ics_url)
+        cal = Calendar.from_ical(text)
+        events = _today_events(cal, today)
+        _cache.update({"fetched_at": now, "data": events, "url": ics_url, "valid": True})
+        logger.info("Fetched iCal: %d event(s) for %s", len(events), today)
+        return list(events)
+    except Exception as e:
+        logger.warning(
+            "iCal fetch failed (%s: %s); using last-good cache (%d entries)",
+            type(e).__name__, e, len(_cache.get("data", [])),
+        )
+        return list(_cache.get("data", []))
+
+
+def clear_cache() -> None:
+    """Clear the iCal cache (test hook + manual refresh helper)."""
+    _cache.update({"fetched_at": 0.0, "data": [], "url": None, "valid": False})

src/reachy_mini_receptionist/main.py

@@ -0,0 +1,1199 @@
+"""Entrypoint for the Reachy Mini Receptionist app.
+
+Changes from the base realtime app template:
+- FaceDatabase and FaceRecognitionWorker are initialised here and injected into
+  ToolDependencies (face_worker + face_db fields).
+- A /video_feed MJPEG endpoint and /api/* JSON endpoints are mounted on the
+  FastAPI settings_app so the dashboard can show the live annotated camera feed,
+  guest list, calendar, and notifications.
+- The camera_worker slot is left intact for future head-tracking integration.
+"""
+
+import os
+import sys
+import time
+import asyncio
+import argparse
+import threading
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastrtc import Stream
+from gradio.utils import get_space
+
+from reachy_mini import ReachyMini, ReachyMiniApp
+from reachy_mini_receptionist.utils import (
+    parse_args,
+    setup_logger,
+    handle_vision_stuff,
+    log_connection_troubleshooting,
+)
+
+
+def _mount_dashboard_api(
+    app: Any,
+    face_worker: Any,
+    face_db: Any,
+    realtime_handler: Any | None = None,
+    session_manager: Any | None = None,
+    visitor_log: Any | None = None,
+    employee_store: Any | None = None,
+    instance_path: Optional[str] = None,
+) -> None:
+    """Mount receptionist dashboard API endpoints on a FastAPI app.
+
+        Endpoints:
+      GET /dashboard          → serves the dashboard HTML page
+      GET /video_feed         → MJPEG stream of annotated camera frames
+      GET /api/guests         → JSON list of registered guests
+      GET /api/calendar       → JSON today's appointments
+            GET /api/outbox         → JSON email outbox log
+      GET /api/face_status    → JSON current face detection state
+            GET /api/face_event_last_sent → JSON last external face event sent to model
+      GET /api/logs           → JSON recent face recognition debug logs
+      GET /api/session        → JSON current visitor session state (state machine)
+      GET /api/session_event_last_sent → JSON last session context event sent to model
+    """
+    if app is None or not hasattr(app, "get"):
+        return  # No FastAPI app available (e.g. LocalStream without settings_app)
+
+    # Body needs to be in scope for every POST/PATCH endpoint with a JSON
+    # body below. Imported once here at the top of the function so the
+    # order endpoints are defined in doesn't matter.
+    from fastapi import Body  # noqa: F401 — used by endpoints below
+
+    from reachy_mini_receptionist.calendar_data import get_appointments
+    from reachy_mini_receptionist.tools.send_email import get_outbox
+
+    static_dir = Path(__file__).parent / "static"
+    dashboard_html = static_dir / "dashboard.html"
+
+    # Serve guest face thumbnails as static files
+    guests_dir = face_db.guests_dir
+    app.mount(
+        "/guest_images",
+        StaticFiles(directory=str(guests_dir)),
+        name="guest_images",
+    )
+
+    # Serve dashboard page
+    if dashboard_html.exists():
+        from fastapi.responses import FileResponse
+
+        @app.get("/dashboard")
+        def _dashboard_page():
+            return FileResponse(str(dashboard_html))
+
+    # MJPEG video feed
+    def _mjpeg_generator():
+        boundary = b"--frame"
+        while True:
+            jpeg = face_worker.latest_annotated_jpeg
+            if jpeg:
+                yield (
+                    boundary + b"\r\nContent-Type: image/jpeg\r\n\r\n"
+                    + jpeg + b"\r\n"
+                )
+            time.sleep(0.05)  # ~20 fps max
+
+    @app.get("/video_feed")
+    def _video_feed():
+        return StreamingResponse(
+            _mjpeg_generator(),
+            media_type="multipart/x-mixed-replace; boundary=frame",
+        )
+
+    @app.get("/api/guests")
+    def _api_guests():
+        return JSONResponse(face_db.get_all_guests())
+
+    @app.delete("/api/guests")
+    def _api_delete_guest(name: str):
+        removed = face_db.delete_guest(name)
+        if not removed:
+            return JSONResponse(
+                {"ok": False, "error": "Guest not found", "name": name},
+                status_code=404,
+            )
+        return JSONResponse({"ok": True, "name": name})
+
+    @app.get("/api/calendar")
+    def _api_calendar():
+        return JSONResponse(get_appointments())
+
+    @app.get("/api/outbox")
+    def _api_outbox():
+        return JSONResponse(get_outbox())
+
+    @app.get("/api/face_status")
+    def _api_face_status():
+        return JSONResponse({
+            "name": face_worker.current_name,
+            "confidence": round(face_worker.confidence, 2),
+            "is_known": face_worker.current_name not in ("Unknown", "No face"),
+        })
+
+    @app.get("/api/face_event_last_sent")
+    def _api_face_event_last_sent():
+        if realtime_handler is None or not hasattr(realtime_handler, "get_last_face_event_sent"):
+            return JSONResponse({"sent": False})
+
+        event = realtime_handler.get_last_face_event_sent()
+        if event is None:
+            return JSONResponse({"sent": False})
+
+        return JSONResponse({"sent": True, **event})
+
+    @app.get("/api/logs")
+    def _api_logs():
+        return JSONResponse({"logs": face_worker.get_recent_logs(100)})
+
+    @app.get("/api/config")
+    def _api_config():
+        from reachy_mini_receptionist.config import config
+        return JSONResponse({"model": config.MODEL_NAME})
+
+    @app.get("/api/best_face_jpeg")
+    def _api_best_face_jpeg():
+        # Return the best face crop from the last 5 seconds as JPEG.
+        # When no face is available we return 204 (No Content) instead of
+        # 404 so the dashboard doesn't pollute the browser's network tab
+        # with red error rows every 500 ms while the room is empty.
+        import cv2
+        from fastapi.responses import Response
+
+        # Dashboard preview should show best currently available face immediately
+        # and not wait for dwell-based stabilization.
+        result = face_worker.best_recent_face(window_seconds=5.0, require_dwell=False)
+        name, conf, crop = result
+
+        if crop is None:
+            return Response(status_code=204)
+
+        # Encode 100x100 grayscale crop as JPEG (upsample to 200x200 for readability)
+        display = cv2.resize(crop, (200, 200), interpolation=cv2.INTER_NEAREST)
+        _, jpeg_buf = cv2.imencode(".jpg", display, [cv2.IMWRITE_JPEG_QUALITY, 85])
+        jpeg_bytes = jpeg_buf.tobytes()
+
+        # Find face area of the best entry for the header
+        face_area = 0
+        with face_worker._lock:
+            if face_worker._detection_window:
+                best_entry = max(face_worker._detection_window, key=lambda e: e[1])
+                face_area = best_entry[1]
+
+        return Response(
+            content=jpeg_bytes,
+            media_type="image/jpeg",
+            headers={
+                "X-Face-Name": name,
+                "X-Face-Confidence": str(round(conf, 2)),
+                "X-Face-Area": str(face_area),
+                "Cache-Control": "no-cache, no-store",
+            },
+        )
+
+    @app.get("/api/session")
+    def _api_session():
+        if session_manager is None:
+            return JSONResponse({"available": False})
+        snap = session_manager.session
+        payload = snap.to_dict() if hasattr(snap, "to_dict") else {}
+        return JSONResponse({"available": True, **payload})
+
+    @app.get("/api/session_event_last_sent")
+    def _api_session_event_last_sent():
+        if realtime_handler is None or not hasattr(realtime_handler, "get_last_session_event_sent"):
+            return JSONResponse({"sent": False})
+        event = realtime_handler.get_last_session_event_sent()
+        if event is None:
+            return JSONResponse({"sent": False})
+        return JSONResponse({"sent": True, **event})
+
+    @app.get("/api/visitor_log")
+    def _api_visitor_log(limit: int = 100):
+        if visitor_log is None:
+            return JSONResponse({"available": False, "today_count": 0, "visits": []})
+        return JSONResponse({
+            "available": True,
+            "today_count": visitor_log.count_today(),
+            "visits": visitor_log.list_visits(limit=limit),
+        })
+
+    @app.get("/api/visitor_log.csv")
+    def _api_visitor_log_csv():
+        """Download the full visitor log as CSV (for HR / facilities handoff)."""
+        from fastapi.responses import Response
+        import csv
+        import io
+
+        if visitor_log is None:
+            return Response(content="", media_type="text/csv")
+
+        rows = visitor_log.list_visits(limit=1000)
+        buf = io.StringIO()
+        fieldnames = [
+            "id", "started_at", "ended_at",
+            "visitor_name", "recognized_face_name", "employee_name",
+            "matched_appointment_time", "matched_appointment_note",
+            "email_sent_to", "final_state", "error_message",
+        ]
+        writer = csv.DictWriter(buf, fieldnames=fieldnames, extrasaction="ignore")
+        writer.writeheader()
+        for r in rows:
+            writer.writerow(r)
+        filename = f"visitor_log_{time.strftime('%Y-%m-%d')}.csv"
+        return Response(
+            content=buf.getvalue(),
+            media_type="text/csv",
+            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+        )
+
+    @app.delete("/api/visitor_log")
+    def _api_visitor_log_wipe():
+        """Wipe every row of the visitor log. Scoped destructive action
+        used by the dashboard's panel-level Clear button. Does not touch
+        employees, settings, face DB, or session state."""
+        if visitor_log is None:
+            return JSONResponse({"ok": False, "error": "visitor_log unavailable"}, status_code=503)
+        try:
+            removed = visitor_log.wipe_all()
+            return JSONResponse({"ok": True, "removed": removed})
+        except Exception as e:
+            return JSONResponse(
+                {"ok": False, "error": f"{type(e).__name__}: {e}"}, status_code=500,
+            )
+
+    @app.get("/api/stats")
+    def _api_stats():
+        """Consolidated stats strip data — visits, emails, last visit, state."""
+        visits_today = visitor_log.count_today() if visitor_log is not None else 0
+        emails_today = visitor_log.count_emails_delivered_today() if visitor_log is not None else 0
+        last = visitor_log.last_visit() if visitor_log is not None else None
+        current_state = None
+        current_visitor = None
+        if session_manager is not None:
+            snap = session_manager.session
+            current_state = snap.current_state.value
+            current_visitor = snap.visitor_name
+        return JSONResponse({
+            "visits_today": visits_today,
+            "emails_delivered_today": emails_today,
+            "last_visit": last,
+            "current_state": current_state,
+            "current_visitor": current_visitor,
+        })
+
+    @app.post("/api/session/reset")
+    def _api_session_reset():
+        """Manual override: drop the current visitor session back to IDLE.
+
+        Useful when the bot gets stuck (e.g. spurious face match keeps the
+        state from going back to idle). Mirrors the auto-timeout reset.
+        """
+        if session_manager is None:
+            return JSONResponse({"ok": False, "error": "Session manager not available"}, status_code=503)
+        snap = session_manager.reset()
+        return JSONResponse({"ok": True, "current_state": snap.current_state.value})
+
+    @app.post("/api/guests/manual_register")
+    def _api_guests_manual_register(payload: dict = Body(...)):
+        """Operator-initiated visitor registration that bypasses voice.
+
+        When the bot can't transcribe a visitor's name (common for short
+        non-English names that Whisper/gpt-realtime mangle), the operator
+        types it on the dashboard. The current camera face crop is saved
+        under that name AND the active session is flipped to RECOGNIZED so
+        downstream tools (lookup_employee / send_email) can proceed as if
+        register_guest had succeeded via voice.
+        """
+        name = (payload.get("name") or "").strip()
+        if not name:
+            return JSONResponse(
+                {"ok": False, "error": "name is required"}, status_code=400,
+            )
+
+        worker = face_worker
+        if worker is None:
+            return JSONResponse(
+                {"ok": False, "error": "Face worker not available"},
+                status_code=503,
+            )
+        face_crop = getattr(worker, "current_encoding", None)
+        if face_crop is None:
+            return JSONResponse(
+                {
+                    "ok": False,
+                    "error": (
+                        "No face currently detected by the camera. Ask the "
+                        "visitor to look directly at the lens and try again."
+                    ),
+                },
+                status_code=409,
+            )
+        if face_db is None:
+            return JSONResponse(
+                {"ok": False, "error": "Face DB not available"},
+                status_code=503,
+            )
+
+        try:
+            face_db.add_or_update_guest(name, face_crop)
+            try:
+                worker.rebuild_recognizer()
+            except Exception:
+                pass
+        except Exception as e:
+            return JSONResponse(
+                {"ok": False, "error": f"{type(e).__name__}: {e}"},
+                status_code=500,
+            )
+
+        # Flip the active session so the LLM sees this as a confirmed
+        # registration and can resume the flow (calendar match / lookup /
+        # send_email) without re-asking for the name.
+        if session_manager is not None:
+            try:
+                from reachy_mini_receptionist.receptionist_state import (
+                    ReceptionState as _RS,
+                )
+                session_manager.transition(
+                    _RS.RECOGNIZED,
+                    visitor_name=name,
+                    recognized_face_name=name,
+                )
+            except Exception as e:
+                print(f"[manual_register] session transition failed: {e}")
+        return JSONResponse({
+            "ok": True,
+            "name": name,
+            "total_guests": face_db.count(),
+        })
+
+    @app.post("/api/demo/reset")
+    def _api_demo_reset():
+        """Wipe everything that accumulates during testing so the next
+        demo runs from a clean slate. **Preserves** the employee
+        directory, calendar, and .env settings — operators don't want
+        to re-enter Mukul/Priya/etc. before every demo.
+
+        Wipes:
+          - face DB (all guests/*.png)
+          - visitor log (every visit row)
+          - email outbox (in-memory)
+          - active session (forces IDLE)
+
+        Triggers a face-recognizer rebuild so the worker sees the empty
+        DB on its next pass.
+        """
+        from reachy_mini_receptionist.tools.send_email import clear_outbox
+        results = {
+            "guests_removed": 0,
+            "visits_removed": 0,
+            "outbox_removed": 0,
+            "session_reset": False,
+            "errors": [],
+        }
+        # Face DB
+        try:
+            if face_db is not None:
+                before = face_db.count()
+                face_db.clear()
+                results["guests_removed"] = before
+        except Exception as e:
+            results["errors"].append(f"face_db: {type(e).__name__}: {e}")
+        # Rebuild recognizer so the worker drops the wiped faces immediately
+        try:
+            if face_worker is not None and hasattr(face_worker, "rebuild_recognizer"):
+                face_worker.rebuild_recognizer()
+        except Exception as e:
+            results["errors"].append(f"face_worker: {type(e).__name__}: {e}")
+        # Visitor log
+        try:
+            if visitor_log is not None:
+                results["visits_removed"] = visitor_log.wipe_all()
+        except Exception as e:
+            results["errors"].append(f"visitor_log: {type(e).__name__}: {e}")
+        # Outbox
+        try:
+            results["outbox_removed"] = clear_outbox()
+        except Exception as e:
+            results["errors"].append(f"outbox: {type(e).__name__}: {e}")
+        # Session
+        try:
+            if session_manager is not None:
+                session_manager.reset()
+                results["session_reset"] = True
+        except Exception as e:
+            results["errors"].append(f"session: {type(e).__name__}: {e}")
+        results["ok"] = not results["errors"]
+        return JSONResponse(results)
+
+    # ------------------------------------------------------------------
+    # Employee CRUD — backs the Employees panel on the dashboard.
+    # (Body is imported at the top of _mount_dashboard_api.)
+    # ------------------------------------------------------------------
+
+    def _employee_store_or_503():
+        if employee_store is None:
+            return JSONResponse(
+                {"ok": False, "error": "Employee store not available"}, status_code=503,
+            )
+        return None
+
+    @app.get("/api/employees")
+    def _api_employees_list():
+        guard = _employee_store_or_503()
+        if guard is not None:
+            return guard
+        return JSONResponse({"employees": employee_store.list_all()})
+
+    @app.post("/api/employees")
+    def _api_employees_create(payload: dict = Body(...)):
+        guard = _employee_store_or_503()
+        if guard is not None:
+            return guard
+        try:
+            from reachy_mini_receptionist.employees_store import EmployeeExistsError
+            emp = employee_store.create(
+                name=payload.get("name", ""),
+                email=payload.get("email", ""),
+                aliases=payload.get("aliases") or [],
+                title=payload.get("title"),
+            )
+            return JSONResponse({"ok": True, "employee": emp})
+        except EmployeeExistsError as e:
+            return JSONResponse(
+                {"ok": False, "error": str(e)}, status_code=409,
+            )
+        except ValueError as e:
+            return JSONResponse(
+                {"ok": False, "error": str(e)}, status_code=400,
+            )
+        except Exception as e:
+            return JSONResponse(
+                {"ok": False, "error": f"{type(e).__name__}: {e}"}, status_code=500,
+            )
+
+    @app.patch("/api/employees/{employee_id}")
+    def _api_employees_update(employee_id: int, payload: dict = Body(...)):
+        guard = _employee_store_or_503()
+        if guard is not None:
+            return guard
+        try:
+            from reachy_mini_receptionist.employees_store import EmployeeExistsError
+            emp = employee_store.update(
+                employee_id,
+                name=payload.get("name"),
+                email=payload.get("email"),
+                aliases=payload.get("aliases"),
+                title=payload.get("title"),
+            )
+            if emp is None:
+                return JSONResponse(
+                    {"ok": False, "error": "Employee not found"}, status_code=404,
+                )
+            return JSONResponse({"ok": True, "employee": emp})
+        except EmployeeExistsError as e:
+            return JSONResponse(
+                {"ok": False, "error": str(e)}, status_code=409,
+            )
+        except ValueError as e:
+            return JSONResponse(
+                {"ok": False, "error": str(e)}, status_code=400,
+            )
+        except Exception as e:
+            return JSONResponse(
+                {"ok": False, "error": f"{type(e).__name__}: {e}"}, status_code=500,
+            )
+
+    @app.delete("/api/employees/{employee_id}")
+    def _api_employees_delete(employee_id: int):
+        guard = _employee_store_or_503()
+        if guard is not None:
+            return guard
+        removed = employee_store.delete(employee_id)
+        if not removed:
+            return JSONResponse(
+                {"ok": False, "error": "Employee not found"}, status_code=404,
+            )
+        return JSONResponse({"ok": True})
+
+    # ------------------------------------------------------------------
+    # Diagnostics — surfaces the kind of failures that turned today into
+    # a 30-min debugging session (audio at 7%, daemon asleep, OpenAI
+    # latency, etc) BEFORE the demo, not during.
+    # ------------------------------------------------------------------
+    import socket
+    import subprocess
+
+    def _check_tcp(host: str, port: int, timeout: float = 2.0) -> dict:
+        start = time.monotonic()
+        try:
+            with socket.create_connection((host, port), timeout=timeout):
+                return {
+                    "ok": True, "latency_ms": int((time.monotonic() - start) * 1000),
+                }
+        except Exception as e:
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+    def _check_daemon() -> dict:
+        try:
+            import httpx
+            t0 = time.monotonic()
+            r = httpx.get("http://localhost:8000/api/daemon/status", timeout=2.0)
+            latency = int((time.monotonic() - t0) * 1000)
+            if r.status_code != 200:
+                return {"ok": False, "latency_ms": latency, "error": f"HTTP {r.status_code}"}
+            body = r.json()
+            return {
+                "ok": body.get("state") == "started",
+                "latency_ms": latency,
+                "state": body.get("state"),
+            }
+        except Exception as e:
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+    def _check_wifi() -> dict:
+        try:
+            out = subprocess.check_output(
+                ["iwconfig", "wlan0"],
+                stderr=subprocess.STDOUT, timeout=2.0,
+            ).decode("utf-8", errors="replace")
+        except Exception as e:
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+        info: dict = {"raw": out.strip()}
+        import re
+        m = re.search(r"Link Quality=(\d+)/(\d+)", out)
+        if m:
+            info["link_quality"] = int(m.group(1))
+            info["link_quality_max"] = int(m.group(2))
+            info["link_quality_pct"] = round(int(m.group(1)) / int(m.group(2)) * 100, 1)
+        m = re.search(r"Signal level=(-?\d+)\s*dBm", out)
+        if m:
+            info["signal_dbm"] = int(m.group(1))
+        m = re.search(r"ESSID:\"([^\"]+)\"", out)
+        if m:
+            info["essid"] = m.group(1)
+        info["ok"] = info.get("link_quality_pct", 0) >= 50 if "link_quality_pct" in info else None
+        return info
+
+    def _check_audio() -> dict:
+        try:
+            out = subprocess.check_output(
+                ["pactl", "list", "short", "sinks"],
+                stderr=subprocess.STDOUT, timeout=2.0,
+            ).decode("utf-8", errors="replace")
+            sinks = [line.split("\t")[1] if "\t" in line else line for line in out.splitlines() if line.strip()]
+            return {"ok": len(sinks) > 0, "sinks": sinks}
+        except Exception as e:
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+    @app.get("/api/diagnostics/health")
+    def _api_diagnostics_health():
+        from reachy_mini_receptionist.config import config as _cfg
+        results = {
+            "openai_realtime": _check_tcp("api.openai.com", 443),
+            "resend": _check_tcp("api.resend.com", 443),
+            "daemon": _check_daemon(),
+            "wifi": _check_wifi(),
+            "audio": _check_audio(),
+            "config": {
+                "openai_key_set": bool(_cfg.OPENAI_API_KEY),
+                "resend_key_set": bool(os.getenv("RESEND_API_KEY")),
+                "resend_from": os.getenv("RESEND_FROM", "onboarding@resend.dev"),
+                "ical_url_set": bool(os.getenv("RECEPTION_ICS_URL")),
+                "model": _cfg.MODEL_NAME,
+            },
+        }
+        # Overall OK iff every "ok" we have is truthy (None counted as unknown -> ok)
+        overall = all(
+            (v.get("ok") in (True, None)) if isinstance(v, dict) else True
+            for k, v in results.items() if k != "config"
+        )
+        return JSONResponse({"ok": overall, "checks": results})
+
+    # ------------------------------------------------------------------
+    # Volume control — wraps pactl. Operators can change speaker volume
+    # without leaving the dashboard (previously required the Reachy Mini
+    # Control panel at :8000 or SSH'ing in).
+    # ------------------------------------------------------------------
+
+    # Reachy Mini uses ALSA directly (no PulseAudio), so we drive volume
+    # via `amixer`. The control name varies by device: Master is the
+    # standard ALSA name; PCM and Speaker are fallbacks on some Pi audio
+    # HATs; reachymini_audio_sink is the daemon's sink name on this image.
+    _AMIXER_CANDIDATES = (
+        "Master", "PCM", "Speaker", "Headphone", "reachymini_audio_sink",
+    )
+
+    def _amixer_active_control() -> Optional[str]:
+        """Return the first amixer control that exists on this device."""
+        try:
+            out = subprocess.check_output(
+                ["amixer", "scontrols"],
+                stderr=subprocess.STDOUT, timeout=2.0,
+            ).decode("utf-8", errors="replace")
+        except Exception:
+            return None
+        import re
+        names = re.findall(r"Simple mixer control '([^']+)'", out)
+        for cand in _AMIXER_CANDIDATES:
+            if cand in names:
+                return cand
+        return names[0] if names else None
+
+    def _audio_get_volume() -> dict:
+        ctrl = _amixer_active_control()
+        if ctrl is None:
+            return {"ok": False, "error": "no amixer control found"}
+        try:
+            out = subprocess.check_output(
+                ["amixer", "sget", ctrl],
+                stderr=subprocess.STDOUT, timeout=2.0,
+            ).decode("utf-8", errors="replace")
+        except Exception as e:
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+        import re
+        m = re.search(r"\[(\d+)%\]", out)
+        percent = int(m.group(1)) if m else None
+        muted = "[off]" in out.lower()
+        return {"ok": True, "control": ctrl, "percent": percent, "muted": muted}
+
+    @app.get("/api/audio/volume")
+    def _api_audio_volume_get():
+        return JSONResponse(_audio_get_volume())
+
+    @app.post("/api/audio/volume")
+    def _api_audio_volume_set(payload: dict = Body(...)):
+        target = payload.get("percent")
+        if target is None:
+            return JSONResponse(
+                {"ok": False, "error": "percent (0-150) is required"},
+                status_code=400,
+            )
+        try:
+            pct = int(target)
+        except Exception:
+            return JSONResponse(
+                {"ok": False, "error": "percent must be an integer"},
+                status_code=400,
+            )
+        pct = max(0, min(150, pct))
+        ctrl = _amixer_active_control()
+        if ctrl is None:
+            return JSONResponse(
+                {"ok": False, "error": "no amixer control found"},
+                status_code=500,
+            )
+        try:
+            subprocess.check_output(
+                ["amixer", "sset", ctrl, "unmute"],
+                stderr=subprocess.STDOUT, timeout=2.0,
+            )
+            subprocess.check_output(
+                ["amixer", "sset", ctrl, f"{pct}%"],
+                stderr=subprocess.STDOUT, timeout=2.0,
+            )
+        except Exception as e:
+            return JSONResponse(
+                {"ok": False, "error": f"{type(e).__name__}: {e}"},
+                status_code=500,
+            )
+        return JSONResponse({"ok": True, **_audio_get_volume()})
+
+    @app.post("/api/diagnostics/speaker_test")
+    def _api_diagnostics_speaker_test():
+        try:
+            subprocess.Popen(
+                ["speaker-test", "-c", "1", "-t", "sine", "-f", "440", "-l", "1"],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            )
+            return JSONResponse({"ok": True, "message": "Playing 1-second 440Hz tone"})
+        except FileNotFoundError:
+            return JSONResponse(
+                {"ok": False, "error": "speaker-test binary not found"}, status_code=500,
+            )
+        except Exception as e:
+            return JSONResponse(
+                {"ok": False, "error": f"{type(e).__name__}: {e}"}, status_code=500,
+            )
+
+    # ------------------------------------------------------------------
+    # Settings — read/write a subset of .env keys via the dashboard so
+    # operators don't have to SSH and `nano .env` to set an API key.
+    # Sensitive values are masked on GET; full values written on PATCH.
+    # Changes that require app restart are flagged in the response.
+    # ------------------------------------------------------------------
+    _SETTINGS_KEYS = {
+        "VOICE_BACKEND":               {"secret": False, "restart": True},
+        "GEMINI_LIVE_MODEL":            {"secret": False, "restart": True},
+        "GEMINI_LIVE_VOICE":            {"secret": False, "restart": True},
+        "OPENAI_API_KEY":              {"secret": True,  "restart": True},
+        "GEMINI_API_KEY":              {"secret": True,  "restart": True},
+        # GEMINI_MODEL removed 2026-05-21 — the name normalizer it
+        # configured is short-circuited in name_normalizer.py, so this
+        # key is unused. Re-add if/when the normalizer is reinstated.
+        "STT_MODEL":                   {"secret": False, "restart": True},
+        "STT_DISABLE_BIAS":            {"secret": False, "restart": True},
+        "RESEND_API_KEY":              {"secret": True,  "restart": False},
+        "RESEND_FROM":                 {"secret": False, "restart": False},
+        "RECEPTION_ICS_URL":           {"secret": False, "restart": False},
+        "FACE_TTL_DAYS":               {"secret": False, "restart": True},
+        "VISITOR_LOG_RETENTION_DAYS":  {"secret": False, "restart": True},
+        "FACE_LBPH_THRESHOLD":         {"secret": False, "restart": True},
+        "MODEL_NAME":                  {"secret": False, "restart": True},
+    }
+
+    def _find_env_path() -> Optional[Path]:
+        try:
+            from dotenv import find_dotenv
+            p = find_dotenv(usecwd=True)
+            if p:
+                return Path(p)
+        except Exception:
+            pass
+        candidates = []
+        if instance_path:
+            candidates.append(Path(instance_path) / ".env")
+        candidates.append(Path.cwd() / ".env")
+        for c in candidates:
+            if c.exists():
+                return c
+        return candidates[0] if candidates else None
+
+    def _mask(value: str) -> str:
+        if not value:
+            return ""
+        if len(value) <= 6:
+            return "•" * len(value)
+        return value[:3] + "•" * max(0, len(value) - 7) + value[-4:]
+
+    @app.get("/api/settings")
+    def _api_settings_get():
+        env_path = _find_env_path()
+        settings = []
+        for key, meta in _SETTINGS_KEYS.items():
+            raw = os.getenv(key) or ""
+            display = _mask(raw) if meta["secret"] and raw else raw
+            settings.append({
+                "key": key,
+                "value": display,
+                "is_set": bool(raw),
+                "is_secret": meta["secret"],
+                "requires_restart": meta["restart"],
+            })
+        return JSONResponse({
+            "env_path": str(env_path) if env_path else None,
+            "settings": settings,
+        })
+
+    @app.patch("/api/settings")
+    def _api_settings_patch(payload: dict = Body(...)):
+        env_path = _find_env_path()
+        if env_path is None:
+            return JSONResponse(
+                {"ok": False, "error": "Could not locate .env file"}, status_code=500,
+            )
+        env_path.parent.mkdir(parents=True, exist_ok=True)
+        # Read existing .env (if any), preserving comments + ordering.
+        lines: List[str] = []
+        if env_path.exists():
+            lines = env_path.read_text(encoding="utf-8").splitlines()
+        updates = {
+            k: str(v) for k, v in (payload or {}).items()
+            if k in _SETTINGS_KEYS and v is not None
+        }
+        if not updates:
+            return JSONResponse(
+                {"ok": False, "error": "No valid keys to update"}, status_code=400,
+            )
+        # Rewrite — replace existing keys in place, append new ones.
+        seen: set[str] = set()
+        for i, line in enumerate(lines):
+            stripped = line.lstrip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            if "=" not in stripped:
+                continue
+            key = stripped.split("=", 1)[0].strip()
+            if key in updates:
+                lines[i] = f"{key}={updates[key]}"
+                seen.add(key)
+        for key, val in updates.items():
+            if key not in seen:
+                lines.append(f"{key}={val}")
+        env_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        # Apply to current process where it's safe to do so without restart.
+        restart_required = False
+        for key, val in updates.items():
+            os.environ[key] = val
+            if _SETTINGS_KEYS[key]["restart"]:
+                restart_required = True
+        return JSONResponse({
+            "ok": True,
+            "updated": list(updates.keys()),
+            "restart_required": restart_required,
+            "env_path": str(env_path),
+        })
+
+
+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 receptionist 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 receptionist app."""
+    # Importing runtime dependencies lazily keeps startup flexible across install contexts.
+    from reachy_mini_receptionist.moves import MovementManager
+    from reachy_mini_receptionist.console import LocalStream
+    from reachy_mini_receptionist.openai_realtime import OpenaiRealtimeHandler
+    from reachy_mini_receptionist.tools.core_tools import ToolDependencies
+    from reachy_mini_receptionist.audio.head_wobbler import HeadWobbler
+
+    # Backend switch: VOICE_BACKEND=gemini (default) uses Google Gemini
+    # Live, "openai" uses OpenAI Realtime. Default flipped from openai to
+    # gemini on 2026-05-21 because (a) Gemini Live hears Indian names far
+    # more accurately than OpenAI's gpt-4o-transcribe, (b) operators on a
+    # free Gemini API key get more headroom than on free OpenAI credits.
+    # Imported lazily so a missing SDK doesn't break the alternate backend.
+    _voice_backend = (os.getenv("VOICE_BACKEND") or "gemini").strip().lower()
+
+    logger = setup_logger(args.debug)
+    logger.info("Starting Reachy Mini Receptionist 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)
+
+    # ------------------------------------------------------------------
+    # Receptionist: Face DB + Face Recognition Worker
+    # ------------------------------------------------------------------
+    from reachy_mini_receptionist.face_db import FaceDatabase
+    from reachy_mini_receptionist.face_recognition_worker import FaceRecognitionWorker
+
+    db_dir = Path(instance_path) if instance_path else Path.cwd()
+    face_db = FaceDatabase(db_dir / "guests.db")
+    face_worker = FaceRecognitionWorker(face_db, camera_worker=camera_worker)
+
+    # ------------------------------------------------------------------
+    # Receptionist: Session state machine + visitor log
+    # ------------------------------------------------------------------
+    from reachy_mini_receptionist.session_manager import SessionManager
+    from reachy_mini_receptionist.conversation_controller import ConversationController
+    from reachy_mini_receptionist.visitor_log import VisitorLog
+
+    visitor_log = VisitorLog(db_dir / "visitor_log.db")
+    session_manager = SessionManager(visitor_log=visitor_log)
+    conversation_controller = ConversationController(session_manager)
+
+    # Employee directory — SQLite-backed CRUD. Seeded from the hardcoded
+    # _SEED_EMPLOYEES list in employees.py on a brand-new install; after
+    # that, the dashboard's Employees panel is the source of truth.
+    from reachy_mini_receptionist.employees_store import EmployeeStore
+    from reachy_mini_receptionist import employees as _employees_module
+    employee_store = EmployeeStore(db_dir / "employees.db")
+    try:
+        seeded = employee_store.seed_if_empty(_employees_module._SEED_EMPLOYEES)
+        if seeded:
+            print(f"[employees] Seeded {seeded} employee(s) on first run")
+    except Exception as e:
+        print(f"[employees] Seed failed: {e}")
+    _employees_module.set_store(employee_store)
+
+    # Privacy retention — best-effort cleanup at startup. Defaults match the
+    # Day-2 plan (face TTL 30d, visit log 90d). Set the env var to 0 to
+    # disable either one. Runs once per app start — restart weekly or add a
+    # scheduled task if you keep the app up for months.
+    try:
+        face_ttl = float(os.getenv("FACE_TTL_DAYS", "30"))
+        removed_faces = face_db.cleanup_older_than(face_ttl)
+        if removed_faces:
+            print(f"[retention] Face DB: removed {removed_faces} guest(s) older than {face_ttl} days")
+    except Exception as e:
+        print(f"[retention] Face DB cleanup failed: {e}")
+    try:
+        log_retention = float(os.getenv("VISITOR_LOG_RETENTION_DAYS", "90"))
+        removed_visits = visitor_log.cleanup_older_than(log_retention)
+        if removed_visits:
+            print(f"[retention] Visitor log: removed {removed_visits} row(s) older than {log_retention} days")
+    except Exception as e:
+        print(f"[retention] Visitor log cleanup failed: {e}")
+
+    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,
+        face_worker=face_worker,
+        face_db=face_db,
+        session_manager=session_manager,
+        conversation_controller=conversation_controller,
+    )
+    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}")
+
+    if _voice_backend == "gemini":
+        from reachy_mini_receptionist.gemini_live import GeminiLiveHandler
+        logger.info("VOICE_BACKEND=gemini — using Gemini Live handler")
+        handler = GeminiLiveHandler(
+            deps,
+            gradio_mode=args.gradio,
+            instance_path=instance_path,
+            session_manager=session_manager,
+            controller=conversation_controller,
+        )
+    else:
+        logger.info("VOICE_BACKEND=openai (default) — using OpenAI Realtime handler")
+        handler = OpenaiRealtimeHandler(
+            deps,
+            gradio_mode=args.gradio,
+            instance_path=instance_path,
+            session_manager=session_manager,
+            controller=conversation_controller,
+        )
+
+    def _face_event_forwarder(event: Dict[str, Any]) -> None:
+        """Route a face event through the controller, then to the LLM context."""
+        try:
+            conversation_controller.on_face_event(event)
+        except Exception as exc:
+            logger.warning("ConversationController.on_face_event raised %s: %s", type(exc).__name__, exc)
+        handler.notify_external_face_event(event)
+
+    face_worker.set_face_event_callback(_face_event_forwarder)
+
+    # Subscribe the handler BEFORE face_worker.start() so the first
+    # transitions aren't dropped. SessionManager buffers events that fire
+    # before the realtime websocket is connected.
+    session_manager.subscribe(handler.notify_session_event)
+
+    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 reachy_mini_receptionist.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)
+
+        # ------------------------------------------------------------------
+        # Mount dashboard API endpoints BEFORE wrapping with Gradio so that
+        # /video_feed, /api/*, /dashboard routes are available on the same app.
+        # ------------------------------------------------------------------
+        _mount_dashboard_api(
+            app, face_worker, face_db, handler, session_manager, visitor_log,
+            employee_store=employee_store, instance_path=instance_path,
+        )
+        logger.info("📊 Receptionist dashboard available at: http://localhost:7860/dashboard")
+
+        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,
+        )
+
+        # ------------------------------------------------------------------
+        # Mount dashboard API endpoints on settings_app when headless
+        # ------------------------------------------------------------------
+        _mount_dashboard_api(
+            settings_app, face_worker, face_db, handler, session_manager, visitor_log,
+            employee_store=employee_store, instance_path=instance_path,
+        )
+
+    # Each async service → its own thread/loop
+    movement_manager.start()
+    head_wobbler.start()
+    face_worker.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()
+        face_worker.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 ReachyMiniReceptionist(ReachyMiniApp):  # type: ignore[misc]
+    """Reachy Mini Apps entry point for the receptionist 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 receptionist 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 = ReachyMiniReceptionist()
+    try:
+        app.wrapped_run()
+    except KeyboardInterrupt:
+        app.stop()

src/reachy_mini_receptionist/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/reachy_mini_receptionist/name_normalizer.py

@@ -0,0 +1,228 @@
+"""Gemini-backed name disambiguation.
+
+OpenAI's gpt-4o-transcribe mishears short non-English names (Arav -> Lee Win,
+Krishna -> Christina, Mukul -> Michael). The realtime audio loop is locked
+to the OpenAI stack — too risky to swap mid-pilot — but we can run the
+transcribed candidate through Gemini as a cheap post-processing step to
+recover the intended name.
+
+Pipeline:
+    visitor says "Arav"
+    -> OpenAI STT returns "Lee Win"
+    -> normalize_name("Lee Win", candidates=[Henry, Krishna, Arav, ...])
+       -> asks Gemini: "Which of these is closest phonetically to 'Lee Win'?"
+       -> returns "Arav" if confident, original "Lee Win" if not
+    -> register_guest("Arav", confirmed=true) — saves the right face
+
+Fails open: when GEMINI_API_KEY is unset, the http call errors, or Gemini
+returns garbage, we return the original transcribed name unchanged. The
+worst case is "same behaviour as before".
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Iterable, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Default to gemini-3.5-flash (Google's latest Flash-tier model,
+# launched at I/O 2026 — faster and more accurate than the 2.5
+# variants on short-prompt disambiguation). Override via the
+# GEMINI_MODEL env var without restarting (read on each call) so the
+# operator can fall back to 2.5-flash / 2.5-flash-lite if needed.
+_DEFAULT_GEMINI_MODEL = "gemini-3.5-flash"
+_GEMINI_URL_TEMPLATE = (
+    "https://generativelanguage.googleapis.com/v1beta/models/"
+    "{model}:generateContent"
+)
+_HTTP_TIMEOUT_SECONDS = 4.0
+
+
+def _gemini_url() -> str:
+    model = os.getenv("GEMINI_MODEL", "").strip() or _DEFAULT_GEMINI_MODEL
+    return _GEMINI_URL_TEMPLATE.format(model=model)
+
+
+def _build_prompt(transcribed: str, candidates: list[str]) -> str:
+    cand_list = ", ".join(candidates) if candidates else "(none)"
+    return (
+        "You are a speech-recognition error corrector for a reception desk. "
+        f"A visitor said their name and the speech-to-text returned: '{transcribed}'. "
+        f"The visitor is likely one of these scheduled or known people: {cand_list}. "
+        "Return a candidate name ONLY when it is very phonetically close to "
+        "the transcribed value — sharing most of the syllables, vowel sounds, "
+        "or stressed sound. If NO candidate is a clear phonetic match, you "
+        "MUST return the original transcribed value unchanged. Do not stretch "
+        "for a match. When in doubt, keep the original. "
+        "Good corrections (close phonetic match): "
+        "'Lee Win' -> 'Arav' (sounds like 'Le-win' ~ 'A-rav'? No — return 'Lee Win'). "
+        "'Christina' -> 'Krishna' (yes, similar syllables). "
+        "'Michael' -> 'Mukul' (yes, M-K consonants and similar vowels). "
+        "Bad corrections (NEVER do these — return the original instead): "
+        "'Bruh' -> stays 'Bruh' (no candidate sounds like Bruh). "
+        "'Bob' -> stays 'Bob' (no phonetic match in the list). "
+        "'Sarah' -> stays 'Sarah' (if Sarah is in the list, fine; if not, KEEP IT). "
+        "Return only the chosen name, no extra words, no quotes, no punctuation."
+    )
+
+
+def _phonetic_similarity(a: str, b: str) -> float:
+    """Cheap phonetic similarity score in [0, 1].
+
+    Uses Python's stdlib difflib SequenceMatcher on the lowercased
+    strings. Not phonetic-perfect (no Soundex / Metaphone) but good
+    enough to reject "Henry" -> "Arjun" type hallucinations from
+    Gemini. Anything below 0.5 is "not really similar".
+    """
+    from difflib import SequenceMatcher
+    return SequenceMatcher(None, a.lower(), b.lower()).ratio()
+
+
+def normalize_name(
+    transcribed: str,
+    candidates: Iterable[str],
+    api_key: Optional[str] = None,
+) -> str:
+    """Map a transcribed name to the closest candidate via Gemini.
+
+    Returns the original ``transcribed`` value unchanged when:
+      - GEMINI_API_KEY is unset
+      - the http call fails / times out / returns non-2xx
+      - the response is empty or obviously wrong
+      - Gemini's choice is not phonetically similar to the transcribed value
+    """
+    raw = (transcribed or "").strip()
+    if not raw:
+        return raw
+
+    # ──────────────────────────────────────────────────────────────────
+    # DISABLED (2026-05-21): Gemini-3.5-flash name normalizer.
+    # Built when OpenAI's gpt-4o-transcribe was mishearing short names
+    # (Arav -> Lee Win). Gemini Live hears names cleanly natively, so the
+    # extra REST call to gemini-3.5-flash before every register_guest /
+    # lookup_employee was pure latency (~1-2s per call) plus 429s on the
+    # free tier. Re-enable by removing this early-return when switching
+    # VOICE_BACKEND back to "openai".
+    # ──────────────────────────────────────────────────────────────────
+    return raw
+
+    key = api_key or os.getenv("GEMINI_API_KEY", "").strip()
+    if not key:
+        logger.debug("normalize_name: no GEMINI_API_KEY, returning original")
+        return raw
+
+    cand_list = [c for c in (candidates or []) if c and isinstance(c, str)]
+    if not cand_list:
+        return raw
+
+    # Pre-filter: only ask Gemini about candidates with at least some
+    # surface similarity to the transcribed name. Cuts API cost AND
+    # prevents Gemini from being prompted with totally-unrelated options.
+    _MIN_SIMILARITY = 0.4
+    similar = [c for c in cand_list if _phonetic_similarity(raw, c) >= _MIN_SIMILARITY]
+    if not similar:
+        logger.debug(
+            "normalize_name: no candidate similar enough to %r (best=%.2f) — keeping original",
+            raw, max((_phonetic_similarity(raw, c) for c in cand_list), default=0.0),
+        )
+        return raw
+    cand_list = similar
+
+    payload = {
+        "contents": [{
+            "role": "user",
+            "parts": [{"text": _build_prompt(raw, cand_list)}],
+        }],
+        "generationConfig": {
+            "temperature": 0.0,
+            "maxOutputTokens": 24,
+        },
+    }
+    try:
+        resp = httpx.post(
+            f"{_gemini_url()}?key={key}",
+            json=payload,
+            timeout=_HTTP_TIMEOUT_SECONDS,
+        )
+        if resp.status_code >= 400:
+            logger.debug("normalize_name: gemini HTTP %d: %s", resp.status_code, resp.text[:200])
+            return raw
+        data = resp.json()
+    except Exception as e:
+        logger.debug("normalize_name: gemini call failed (%s)", e)
+        return raw
+
+    try:
+        candidate_text = (
+            data["candidates"][0]["content"]["parts"][0]["text"]
+        ).strip()
+    except Exception:
+        logger.debug("normalize_name: unexpected gemini response shape: %s", json.dumps(data)[:200])
+        return raw
+
+    # Sanitize: Gemini sometimes adds punctuation despite the instruction.
+    for ch in ('"', "'", "."):
+        candidate_text = candidate_text.replace(ch, "")
+    candidate_text = candidate_text.strip()
+    if not candidate_text:
+        return raw
+
+    # Only trust a Gemini reply that is either (a) exactly one of the
+    # candidates (case-insensitive) or (b) the original transcript. This
+    # prevents Gemini from hallucinating a new name we never gave it.
+    cand_lower = {c.lower(): c for c in cand_list}
+    g_lower = candidate_text.lower()
+    if g_lower in cand_lower:
+        chosen = cand_lower[g_lower]
+        if chosen.lower() != raw.lower():
+            logger.info(
+                "normalize_name: '%s' -> '%s' (gemini disambiguation)",
+                raw, chosen,
+            )
+        return chosen
+    if g_lower == raw.lower():
+        return raw
+    logger.debug(
+        "normalize_name: gemini returned %r which isn't in candidates %r — keeping original %r",
+        candidate_text, cand_list, raw,
+    )
+    return raw
+
+
+def collect_known_names() -> list[str]:
+    """Return employee names + aliases for the candidate list.
+
+    Used by ``register_guest`` (visitor name disambiguation against
+    employees, NOT against calendar visitors) and ``lookup_employee``
+    (host name -> directory entries). Calendar visitor names are
+    excluded — including them was causing Gemini to map every
+    transcribed visitor name onto the next-scheduled visitor.
+
+    Failures are silenced so a degraded source never blocks the lookup.
+    """
+    names: list[str] = []
+    try:
+        from reachy_mini_receptionist import employees
+        for emp in employees.get_all_employees():
+            n = (emp.get("name") or "").strip()
+            if n:
+                names.append(n)
+            for alias in (emp.get("aliases") or []):
+                a = (alias or "").strip()
+                if a:
+                    names.append(a)
+    except Exception:
+        pass
+    seen: set[str] = set()
+    unique: list[str] = []
+    for n in names:
+        k = n.lower()
+        if k in seen:
+            continue
+        seen.add(k)
+        unique.append(n)
+    return unique

src/reachy_mini_receptionist/openai_realtime.py

@@ -0,0 +1,1839 @@
+import json
+import os
+import uuid
+import base64
+import random
+import asyncio
+import logging
+import threading
+import time
+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 reachy_mini_receptionist.config import config
+from reachy_mini_receptionist.prompts import get_session_voice, get_session_instructions
+from reachy_mini_receptionist.tools.core_tools import (
+    ToolDependencies,
+    get_tool_specs,
+)
+from reachy_mini_receptionist.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
+
+# How often to rebuild the STT bias prompt + push it to the realtime session
+# so calendar additions made AFTER the session connected (visitors added on
+# the fly) still benefit from name-biased transcription. 300s aligns with
+# the iCal cache TTL so each refresh either reuses the cache or triggers
+# at most one fetch.
+_STT_BIAS_REFRESH_SECONDS: Final[float] = 300.0
+
+
+def _format_bias_prompt(names: list[str]) -> str:
+    seen: set[str] = set()
+    unique: list[str] = []
+    for n in names:
+        key = n.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(n)
+
+    if not unique:
+        return (
+            "Reception lobby check-in conversation. Visitor names and host names."
+        )
+
+    # Plain comma-separated bias list. We tried beefing this up with
+    # "I am <name>. Here to see <name>." sentences per name to increase
+    # the bias signal — but gpt-4o-transcribe started ECHOING those
+    # sentences back as the user transcript when audio was unclear,
+    # so real visitor speech ("I am David, here to see Andrew") was
+    # being mistranscribed as "I am David. Here to see David." (a
+    # name from the prompt copied to both slots). Going back to the
+    # simple list keeps the bias direction without the echo failure.
+    #
+    # OpenAI's Realtime API caps the transcription prompt at 1024 chars.
+    _MAX_PROMPT_CHARS = 1000
+    body = ", ".join(unique)
+    msg = (
+        "Reception lobby check-in. Expected visitor and host names include: "
+        + body
+        + "."
+    )
+    if len(msg) > _MAX_PROMPT_CHARS:
+        msg = msg[: _MAX_PROMPT_CHARS - 1] + "."
+    return msg
+
+
+def _collect_employee_names() -> list[str]:
+    names: list[str] = []
+    try:
+        from reachy_mini_receptionist import employees
+        for emp in employees.get_all_employees():
+            n = (emp.get("name") if isinstance(emp, dict) else getattr(emp, "name", "")) or ""
+            n = n.strip()
+            if n:
+                names.append(n)
+            aliases = (
+                emp.get("aliases") if isinstance(emp, dict) else getattr(emp, "aliases", None)
+            ) or []
+            for alias in aliases:
+                a = (alias or "").strip()
+                if a:
+                    names.append(a)
+    except Exception:
+        pass
+    return names
+
+
+def _collect_appointment_names_sync() -> list[str]:
+    # See _collect_appointment_names_async — calendar visitor names are
+    # intentionally excluded from STT bias to stop the model defaulting
+    # every short utterance to the next scheduled visitor.
+    return []
+
+
+async def _collect_appointment_names_async() -> list[str]:
+    # Calendar visitor names are intentionally NOT included in the STT
+    # bias prompt. We observed STT picking "Henry" (the next calendar
+    # entry) for any short utterance from a visitor, because the bias
+    # heavily prefers names that appear in the prompt. The employee
+    # directory provides enough name coverage for hosts; visitor names
+    # have to be heard fresh from speech.
+    return []
+
+
+def _build_transcription_bias_prompt() -> str:
+    """Sync variant — kept for callers outside an event loop. Blocks on iCal
+    HTTP. Prefer ``_build_transcription_bias_prompt_async`` in async paths.
+    """
+    return _format_bias_prompt(_collect_appointment_names_sync() + _collect_employee_names())
+
+
+async def _build_transcription_bias_prompt_async() -> str:
+    """Assemble the STT bias prompt without blocking the event loop on iCal.
+
+    OpenAI's transcription API accepts a free-form ``prompt`` string. When
+    the recognizer hears mumbled audio it leans toward words/phrases in this
+    prompt. Feeding today's calendar visitors + the employee directory
+    makes non-English names (Mukul, Krishna, Shyam, etc.) far more likely
+    to come back correct instead of collapsing to "Michael"/"Christina".
+
+    Fails open — if a source raises, the generic prompt is returned.
+    """
+    return _format_bias_prompt(
+        await _collect_appointment_names_async() + _collect_employee_names()
+    )
+
+
+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,
+        session_manager: Any | None = None,
+        controller: Any | None = None,
+    ):
+        """Initialize the handler.
+
+        ``session_manager`` and ``controller`` are optional so existing test
+        harnesses that construct the handler directly keep working.
+        """
+        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
+        self._session_manager = session_manager
+        self._controller = controller
+
+        # 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
+        self._runtime_loop: asyncio.AbstractEventLoop | None = None
+
+        # Last successfully pushed external face context event.
+        self._face_event_lock = threading.Lock()
+        self._last_face_event_sent: dict[str, Any] | None = None
+        # Last pending external face event waiting for runtime loop/connection.
+        self._pending_face_event_lock = threading.Lock()
+        self._pending_face_event: dict[str, Any] | None = None
+
+        # Tool args by call_id, populated when a tool starts and consumed
+        # when its result arrives (so the ConversationController gets both
+        # the args and the result).
+        self._tool_call_args: dict[str, dict[str, Any]] = {}
+
+        # Last successfully pushed session context event + pending buffer.
+        self._session_event_lock = threading.Lock()
+        self._last_session_event_sent: dict[str, Any] | None = None
+        self._pending_session_event_lock = threading.Lock()
+        self._pending_session_event: dict[str, Any] | None = None
+
+        # One-shot guard so the IDLE-state workflow hint is only pushed
+        # once per IDLE stretch, not on every speech_started event.
+        self._idle_speech_cue_pushed: bool = False
+
+        # Last STT bias prompt actually sent to the realtime session, so the
+        # periodic refresh loop can skip the session.update when nothing has
+        # changed (calendar quiet, employee directory unchanged).
+        self._last_stt_bias_prompt: Optional[str] = None
+
+    def _stash_pending_face_event(self, face_event: dict[str, Any]) -> None:
+        """Keep only the latest pending face event for eventual delivery."""
+        with self._pending_face_event_lock:
+            self._pending_face_event = dict(face_event)
+
+    def _pop_pending_face_event(self) -> dict[str, Any] | None:
+        """Pop and clear latest pending face event."""
+        with self._pending_face_event_lock:
+            pending = self._pending_face_event
+            self._pending_face_event = None
+            return pending
+
+    async def _flush_pending_face_event(self) -> None:
+        """Try sending one buffered face event once the session is ready."""
+        pending = self._pop_pending_face_event()
+        if pending is None:
+            return
+        try:
+            await self._push_face_context_event(pending)
+        except Exception as e:
+            logger.debug("Failed to flush pending face event: %s", e)
+            self._stash_pending_face_event(pending)
+
+    def copy(self) -> "OpenaiRealtimeHandler":
+        """Create a copy of the handler."""
+        return OpenaiRealtimeHandler(
+            self.deps,
+            self.gradio_mode,
+            self.instance_path,
+            session_manager=self._session_manager,
+            controller=self._controller,
+        )
+
+    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 reachy_mini_receptionist.config import config as _config
+            from reachy_mini_receptionist.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."""
+        self._runtime_loop = asyncio.get_running_loop()
+        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
+
+    def notify_external_face_event(self, face_event: dict[str, Any]) -> None:
+        """Thread-safe entrypoint for face worker state transition events.
+
+        This injects context into the conversation via conversation.item.create
+        without forcing a response.
+        """
+        loop = self._runtime_loop
+        if loop is None or loop.is_closed():
+            logger.debug("Deferring face event (runtime loop not ready): %s", face_event)
+            self._stash_pending_face_event(face_event)
+            return
+
+        try:
+            future = asyncio.run_coroutine_threadsafe(self._push_face_context_event(face_event), loop)
+
+            def _on_done(fut: "asyncio.Future[None]") -> None:
+                try:
+                    fut.result()
+                except Exception as e:
+                    logger.debug("Face context push failed: %s", e)
+                    self._stash_pending_face_event(face_event)
+
+            future.add_done_callback(_on_done)
+        except Exception as e:
+            logger.debug("Failed to schedule face context event: %s", e)
+            self._stash_pending_face_event(face_event)
+
+    async def _push_face_context_event(self, face_event: dict[str, Any]) -> None:
+        """Push a face state change as external context without triggering a response."""
+        if not self.connection:
+            logger.debug("Deferring face context event (no connection): %s", face_event)
+            self._stash_pending_face_event(face_event)
+            return
+
+        state = str(face_event.get("state", "unknown"))
+        name = face_event.get("name")
+        previous_state = str(face_event.get("previous_state", "unknown"))
+        previous_name = face_event.get("previous_name")
+        lbph_conf = face_event.get("lbph_confidence", 0.0)
+        det_conf = face_event.get("detection_confidence", 0.0)
+
+        msg = (
+            f"[External face update {self.format_timestamp()}] "
+            f"state={state}; name={name}; previous_state={previous_state}; "
+            f"previous_name={previous_name}; lbph={lbph_conf}; det={det_conf}. "
+            "This is context only. Do not respond unless the user speaks."
+        )
+
+        await self.connection.conversation.item.create(
+            item={
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": msg}],
+            },
+        )
+
+        sent_at_epoch = time.time()
+        sent_payload = {
+            "state": state,
+            "name": name,
+            "previous_state": previous_state,
+            "previous_name": previous_name,
+            "lbph_confidence": float(lbph_conf),
+            "detection_confidence": float(det_conf),
+            "sent_at": sent_at_epoch,
+            "sent_at_iso": datetime.fromtimestamp(sent_at_epoch).strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        with self._face_event_lock:
+            self._last_face_event_sent = sent_payload
+
+        logger.info("Pushed external face context event: %s", msg)
+
+    async def _prime_no_face_context(self) -> None:
+        """Prime a fresh session with an explicit no-face context event."""
+        try:
+            await self._push_face_context_event(
+                {
+                    "event": "face_state_changed",
+                    "state": "no_face",
+                    "name": None,
+                    "previous_state": "unknown",
+                    "previous_name": None,
+                    "lbph_confidence": 0.0,
+                    "detection_confidence": 0.0,
+                    "timestamp": time.time(),
+                }
+            )
+            logger.info("Primed startup face context: state=no_face")
+        except Exception as e:
+            logger.debug("Failed to prime startup no-face context: %s", e)
+
+    def get_last_face_event_sent(self) -> dict[str, Any] | None:
+        """Return the last face context event that was successfully sent to the model."""
+        with self._face_event_lock:
+            if self._last_face_event_sent is None:
+                return None
+            return dict(self._last_face_event_sent)
+
+    async def _push_idle_speech_cue_if_needed(self) -> None:
+        """Push the IDLE-state workflow hint when a visitor speaks first.
+
+        Per-state hints normally arrive via ``notify_session_event`` on
+        transitions. While state stays IDLE no transition fires, so the
+        LLM has no guidance when the camera hasn't caught the visitor's
+        face yet. We rate-limit to once per IDLE stretch so we don't
+        push the same cue on every breath.
+        """
+        if not self.connection:
+            return
+        if self._session_manager is None:
+            return
+        try:
+            from reachy_mini_receptionist.receptionist_state import ReceptionState
+            from reachy_mini_receptionist.conversation_controller import next_action_hint
+            current = self._session_manager.current_state
+            if current != ReceptionState.IDLE:
+                return
+            hint = next_action_hint(current)
+            if not hint:
+                return
+            if getattr(self, "_idle_speech_cue_pushed", False):
+                return
+            msg = (
+                f"[Backend idle-speech cue {self.format_timestamp()}] "
+                f"Visitor just started speaking while state=idle. {hint}"
+            )
+            await self.connection.conversation.item.create(
+                item={
+                    "type": "message",
+                    "role": "user",
+                    "content": [{"type": "input_text", "text": msg}],
+                },
+            )
+            self._idle_speech_cue_pushed = True
+            logger.info("Pushed idle-speech cue: %s", msg)
+        except Exception as e:
+            logger.debug("idle-speech cue push error: %s", e)
+
+    # ------------------------------------------------------------------
+    # Session context events (mirror of the face-event channel)
+    # ------------------------------------------------------------------
+
+    def _stash_pending_session_event(self, payload: dict[str, Any]) -> None:
+        with self._pending_session_event_lock:
+            self._pending_session_event = dict(payload)
+
+    def _pop_pending_session_event(self) -> dict[str, Any] | None:
+        with self._pending_session_event_lock:
+            pending = self._pending_session_event
+            self._pending_session_event = None
+            return pending
+
+    async def _flush_pending_session_event(self) -> None:
+        pending = self._pop_pending_session_event()
+        if pending is None:
+            return
+        try:
+            await self._push_session_context_event(pending)
+        except Exception as e:
+            logger.debug("Failed to flush pending session event: %s", e)
+            self._stash_pending_session_event(pending)
+
+    def notify_session_event(
+        self,
+        previous_state: Any,
+        new_state: Any,
+        snapshot: Any,
+    ) -> None:
+        """Subscriber callback for SessionManager — thread-safe.
+
+        Schedules a coroutine on the runtime loop that pushes the session
+        state change to the LLM as a context-only conversation item.
+        """
+        try:
+            payload = {
+                "previous_state": getattr(previous_state, "value", str(previous_state)),
+                "new_state": getattr(new_state, "value", str(new_state)),
+                "snapshot": snapshot.to_dict() if hasattr(snapshot, "to_dict") else {},
+            }
+        except Exception as e:
+            logger.debug("notify_session_event: failed to build payload: %s", e)
+            return
+
+        # Reset the idle-speech cue flag whenever the session transitions
+        # back to IDLE (visitor walked away, session reset, timeout). The
+        # next visitor's first utterance will re-push the cue.
+        try:
+            new_state_value = payload["new_state"]
+            if new_state_value == "idle":
+                self._idle_speech_cue_pushed = False
+        except Exception:
+            pass
+
+        loop = self._runtime_loop
+        if loop is None or loop.is_closed():
+            logger.debug("Deferring session event (runtime loop not ready): %s", payload)
+            self._stash_pending_session_event(payload)
+            return
+
+        try:
+            future = asyncio.run_coroutine_threadsafe(
+                self._push_session_context_event(payload), loop
+            )
+
+            def _on_done(fut: "asyncio.Future[None]") -> None:
+                try:
+                    fut.result()
+                except Exception as e:
+                    logger.debug("Session context push failed: %s", e)
+                    self._stash_pending_session_event(payload)
+
+            future.add_done_callback(_on_done)
+        except Exception as e:
+            logger.debug("Failed to schedule session context event: %s", e)
+            self._stash_pending_session_event(payload)
+
+    async def _push_session_context_event(self, payload: dict[str, Any]) -> None:
+        """Push a session state change as context-only conversation item.
+
+        Includes a per-state ``Next:`` directive (from
+        ``conversation_controller.next_action_hint``) so the LLM knows what
+        to do when the visitor next speaks — without that workflow being
+        baked into the system prompt.
+        """
+        if not self.connection:
+            logger.debug("Deferring session context event (no connection): %s", payload)
+            self._stash_pending_session_event(payload)
+            return
+
+        snap = payload.get("snapshot") or {}
+        new_state_value = payload.get("new_state")
+
+        hint = ""
+        speak_now = False
+        try:
+            from reachy_mini_receptionist.conversation_controller import (
+                next_action_hint,
+                should_speak_immediately,
+            )
+            from reachy_mini_receptionist.receptionist_state import ReceptionState
+            if new_state_value:
+                new_state_enum = ReceptionState(new_state_value)
+                hint = next_action_hint(new_state_enum)
+                speak_now = should_speak_immediately(new_state_enum)
+        except Exception as e:
+            logger.debug("Could not compute next_action_hint: %s", e)
+
+        base = (
+            f"[Backend session update {self.format_timestamp()}] "
+            f"state: {payload.get('previous_state')} -> {new_state_value}; "
+            f"visitor={snap.get('visitor_name')}; "
+            f"employee={snap.get('employee_name')}; "
+            f"appointment={(snap.get('matched_appointment') or {}).get('time')}; "
+            f"email_sent_to={snap.get('email_sent_to')}."
+        )
+
+        if hint and speak_now:
+            # The visitor is waiting for the bot to finish a sequence it
+            # started. Tell the LLM to speak now — no "stay quiet" suffix.
+            msg = f"{base} SPEAK NOW: {hint}"
+        elif hint:
+            # State change happened passively (face event, etc.) — the bot
+            # should not blurt anything; act on the hint when the visitor
+            # next speaks.
+            msg = (
+                f"{base} Next: {hint} "
+                "(Stay quiet until the visitor speaks; this is context only.)"
+            )
+        else:
+            msg = f"{base} This is context only. Do not respond unless the user speaks."
+
+        await self.connection.conversation.item.create(
+            item={
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": msg}],
+            },
+        )
+
+        sent_payload = {**payload, "sent_at": time.time(), "hint": hint}
+        with self._session_event_lock:
+            self._last_session_event_sent = sent_payload
+
+        logger.info("Pushed session context event: %s", msg)
+
+        # For speak-now transitions, actively trigger a response so the
+        # LLM speaks immediately. Face-driven transitions to RECOGNIZED
+        # have no in-flight response cycle to piggyback on, and even
+        # tool-driven transitions previously stalled when the SPEAK NOW
+        # cue conflicted with the older "stay quiet" suffix. The sender
+        # worker serializes any duplicate response.create with the
+        # tool-result handler's call.
+        if speak_now:
+            try:
+                await self._safe_response_create(
+                    response={
+                        "instructions": (
+                            "Use the latest [Backend session update] context "
+                            "and speak to the visitor now. Keep it concise."
+                        ),
+                    },
+                )
+            except Exception as e:
+                logger.debug("Failed to queue speak-now response.create: %s", e)
+
+    def get_last_session_event_sent(self) -> dict[str, Any] | None:
+        """Return the last session context event sent to the model."""
+        with self._session_event_lock:
+            if self._last_session_event_sent is None:
+                return None
+            return dict(self._last_session_event_sent)
+
+    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 _stt_bias_refresh_loop(self) -> None:
+        """DISABLED for the demo cut. The periodic session.update was
+        suspected of breaking server VAD mid-session (yes/no replies
+        stopped being captured). Re-enable after the demo with more
+        testing.
+        """
+        return
+        try:  # noqa: unreachable until re-enabled
+            while self.connection:
+                try:
+                    await asyncio.sleep(_STT_BIAS_REFRESH_SECONDS)
+                except asyncio.CancelledError:
+                    return
+
+                if not self.connection:
+                    return
+
+                try:
+                    prompt = await _build_transcription_bias_prompt_async()
+                except Exception as e:
+                    logger.debug("STT bias refresh: build failed: %s", e)
+                    continue
+
+                if prompt == self._last_stt_bias_prompt:
+                    continue
+
+                try:
+                    # Re-send both transcription AND turn_detection together.
+                    # The realtime API treats nested updates as full
+                    # replacement of the parent object on some server
+                    # versions — sending only `transcription` could reset
+                    # `turn_detection` back to stock defaults (threshold
+                    # 0.5 / silence 500ms) and silently change VAD behavior
+                    # mid-conversation. Pinning both keeps VAD consistent.
+                    await self.connection.session.update(
+                        session={
+                            "type": "realtime",
+                            "audio": {
+                                "input": {
+                                    "transcription": {
+                                        "model": "gpt-4o-transcribe",
+                                        "language": "en",
+                                        "prompt": prompt,
+                                    },
+                                    "turn_detection": {
+                                        "type": "server_vad",
+                                        "threshold": 0.5,
+                                        "silence_duration_ms": 600,
+                                        "prefix_padding_ms": 300,
+                                        "interrupt_response": True,
+                                        "create_response": True,
+                                    },
+                                },
+                            },
+                        },
+                    )
+                    self._last_stt_bias_prompt = prompt
+                    logger.info(
+                        "STT bias refreshed (%d chars) — calendar/directory change detected",
+                        len(prompt),
+                    )
+                except Exception as e:
+                    logger.debug("STT bias refresh: session.update failed: %s", e)
+        except asyncio.CancelledError:
+            return
+
+    def _just_entered_speak_now_state(self) -> bool:
+        """True if the session is currently in a SPEAK_NOW state.
+
+        Used in ``_handle_tool_result`` to skip the generic post-tool
+        narration when a controller-driven SPEAK_NOW transition has already
+        enqueued a state-specific ``response.create``.
+        """
+        if self._session_manager is None:
+            return False
+        try:
+            from reachy_mini_receptionist.conversation_controller import should_speak_immediately
+            return bool(should_speak_immediately(self._session_manager.current_state))
+        except Exception:
+            return False
+
+    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"}
+
+        call_args = self._tool_call_args.pop(bg_tool.id, {})
+
+        # 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)
+            # Even if we can't send the function_call_output, the controller
+            # still needs to advance state so the dashboard reflects reality
+            # and a future reconnect lands in the right state.
+            if self._controller is not None:
+                try:
+                    await self._controller.on_tool_completed_async(
+                        bg_tool.tool_name, call_args, tool_result,
+                    )
+                except Exception as e:
+                    logger.warning(
+                        "ConversationController.on_tool_completed_async raised %s: %s",
+                        type(e).__name__, e,
+                    )
+            return
+
+        try:
+            # Send the tool result back to the model FIRST. The controller
+            # callback below may push a SPEAK_NOW context event + enqueue a
+            # response.create — if that ``response.create`` reaches the
+            # server before this ``function_call_output``, the model
+            # generates a response without seeing the tool result. Order
+            # matters: function_call_output → controller → context push →
+            # response.create.
+            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),
+                    },
+                )
+
+            # Notify the conversation controller about the completion so it
+            # can transition the session. Now that the function_call_output
+            # is in flight ahead of us, any SPEAK_NOW response.create enqueued
+            # by the resulting transition will be ordered correctly.
+            if self._controller is not None:
+                try:
+                    await self._controller.on_tool_completed_async(
+                        bg_tool.tool_name, call_args, tool_result,
+                    )
+                except Exception as e:
+                    logger.warning(
+                        "ConversationController.on_tool_completed_async raised %s: %s",
+                        type(e).__name__, e,
+                    )
+
+            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 — UNLESS the
+            # controller has just driven the session into a SPEAK_NOW state
+            # (RECOGNIZED, APPOINTMENT_MATCHED, NO_APPOINTMENT, NOTIFIED, …).
+            # Those transitions already enqueued a state-specific
+            # ``response.create`` via the session-event push, and stacking
+            # the generic "Use the tool result and answer concisely" on top
+            # makes the bot speak twice in a row.
+            if not bg_tool.is_idle_tool_call and not self._just_entered_speak_now_state():
+                # If the tool was BLOCKED / refused (success=False with a
+                # blocked_reason), the visitor doesn't know — bot must
+                # speak the friendly version of the error out loud,
+                # not just sit on the rejection.
+                blocked_reason = None
+                if isinstance(tool_result, dict):
+                    blocked_reason = tool_result.get("blocked_reason")
+                if blocked_reason:
+                    instructions = (
+                        "The last tool call was rejected by the backend. "
+                        "Tell the visitor briefly and naturally what to do "
+                        "next based on the error message you just received — "
+                        "for example, ask their name again, ask for "
+                        "confirmation, or offer a numbered choice of similar "
+                        "names. ALWAYS speak; never go silent after a tool "
+                        "error."
+                    )
+                else:
+                    instructions = "Use the tool result just returned and answer concisely in speech."
+                await self._safe_response_create(
+                    response={"instructions": instructions},
+                )
+
+            # 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:
+            # Build the transcription block. We attempt the rich form first
+            # (language="en" + bias prompt of expected names) and fall back
+            # to a minimal {"model": ...} form if the realtime API rejects
+            # any of the optional fields. Losing the bias prompt is a
+            # quality regression, not a correctness one — but losing the
+            # whole session.update would mean NO tools / NO instructions.
+            # STT_MODEL env var lets us switch between gpt-4o-transcribe
+            # (default, fast but hallucinates) and whisper-1 (slower,
+            # more conservative, returns "" on uncertainty which our
+            # pipeline handles cleanly).
+            stt_model = (os.getenv("STT_MODEL") or "gpt-4o-transcribe").strip() or "gpt-4o-transcribe"
+
+            # STT_DISABLE_BIAS=1 turns off the name bias prompt entirely.
+            # The bias prompt is what causes gpt-4o-transcribe to echo
+            # back its own prompt as the user transcript; disabling it
+            # trades some name-accuracy for no echo bug at all.
+            bias_disabled = (os.getenv("STT_DISABLE_BIAS") or "").strip().lower() in {"1", "true", "yes"}
+
+            initial_bias_prompt = (
+                "" if bias_disabled else await _build_transcription_bias_prompt_async()
+            )
+            transcription_full = {
+                "model": stt_model,
+                "language": "en",
+            }
+            if initial_bias_prompt:
+                transcription_full["prompt"] = initial_bias_prompt
+            logger.info(
+                "STT config: model=%s bias_chars=%d",
+                stt_model, len(initial_bias_prompt),
+            )
+            transcription_min = {"model": "gpt-4o-transcribe"}
+
+            def _build_session(transcription: dict[str, Any]) -> dict[str, Any]:
+                return {
+                    "type": "realtime",
+                    # NOTE: "language" is NOT a valid top-level Realtime API
+                    # session field (it lives under audio.input.transcription).
+                    # Output language is controlled via the instructions prompt
+                    # (the locked profile already says "You ONLY speak ENGLISH").
+                    "instructions": get_session_instructions(),
+                    "audio": {
+                        "input": {
+                            "format": {
+                                "type": "audio/pcm",
+                                "rate": self.input_sample_rate,
+                            },
+                            "transcription": transcription,
+                            # Lobby-tuned VAD: defaults (threshold 0.5,
+                            # silence 500ms) are too aggressive — ambient
+                            # noise interrupts the bot mid-sentence and
+                            # hesitant speakers get cut off before
+                            # finishing. Bump threshold + silence so the
+                            # bot waits for a clear, complete utterance.
+                            "turn_detection": {
+                                "type": "server_vad",
+                                "threshold": 0.5,
+                                "silence_duration_ms": 500,
+                                "prefix_padding_ms": 300,
+                                # interrupt_response=true was causing the
+                                # mic+VAD path to lock up when the bot's
+                                # own audio bled into the mic — server VAD
+                                # never saw a clean silence to commit the
+                                # visitor's "yes". Off is safer for a
+                                # speakerphone lobby setup.
+                                "interrupt_response": False,
+                                "create_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",
+                }
+
+            try:
+                try:
+                    await conn.session.update(session=_build_session(transcription_full))
+                    self._last_stt_bias_prompt = initial_bias_prompt
+                    logger.info(
+                        "Realtime session: applied gpt-4o-transcribe with language=en + name bias (%d chars)",
+                        len(transcription_full["prompt"]),
+                    )
+                except Exception as e:
+                    logger.warning(
+                        "Realtime session.update rejected the rich transcription block "
+                        "(language/prompt) — retrying without them: %s", e,
+                    )
+                    await conn.session.update(session=_build_session(transcription_min))
+                    self._last_stt_bias_prompt = None
+                    logger.info("Realtime session: applied gpt-4o-transcribe (minimal fallback)")
+                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 as e:
+                # A failed session.update means NO instructions, NO tools, NO profile will be
+                # active — the model will run as a generic assistant. Always log clearly.
+                logger.exception(
+                    "Realtime session.update failed — robot will use DEFAULT personality with NO tools. "
+                    "Check the session dict for invalid fields. Error: %s", e
+                )
+                return
+
+            logger.info("Realtime session updated successfully")
+
+            # Manage event received from the openai server
+            self.connection = conn
+            # Reset the idle timer NOW (when the session is actually live) rather than
+            # at __init__ time.  If connection setup takes >15 s, the idle timer would
+            # otherwise already be expired on the very first emit() call, causing the
+            # model to speak immediately without being addressed.
+            self.last_activity_time = asyncio.get_event_loop().time()
+            try:
+                self._connected_event.set()
+            except Exception:
+                pass
+            self._runtime_loop = asyncio.get_running_loop()
+            await self._prime_no_face_context()
+            await self._flush_pending_face_event()
+
+            # Subscribe to session-state changes so transitions get pushed
+            # to the LLM as context events. Idempotent — subscribe() replaces
+            # the existing callback if any.
+            if self._session_manager is not None:
+                try:
+                    self._session_manager.subscribe(self.notify_session_event)
+                except Exception as e:
+                    logger.debug("Failed to subscribe to SessionManager: %s", e)
+            await self._flush_pending_session_event()
+
+
+            response_sender_task: asyncio.Task[None] | None = None
+            stt_refresh_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"
+                )
+
+                # Start the STT bias refresh worker — picks up calendar /
+                # employee directory changes made after the session connected.
+                stt_refresh_task = asyncio.create_task(
+                    self._stt_bias_refresh_loop(), name="stt-bias-refresh"
+                )
+
+                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")
+
+                        # Bump session liveness so the 60s idle timer doesn't
+                        # kill an active flow that's just waiting for the
+                        # visitor to reply (e.g. 'I heard Henry — is that
+                        # right?' followed by 65s of thinking time).
+                        if self._session_manager is not None:
+                            try:
+                                self._session_manager.touch()
+                            except Exception as e:
+                                logger.debug("session_manager.touch failed: %s", e)
+
+                        # If a visitor speaks while state is still IDLE (face
+                        # worker hasn't seen them yet, or face is unstable),
+                        # push the IDLE workflow hint as context so the LLM
+                        # knows to extract name/host from the utterance
+                        # instead of just greeting generically. Without this,
+                        # the bot replies "Hello, how can I help?" and loses
+                        # whatever the visitor just said (name, host, both).
+                        try:
+                            await self._push_idle_speech_cue_if_needed()
+                        except Exception as e:
+                            logger.debug("Idle speech cue push failed: %s", e)
+
+                    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}")
+
+                        # Visitor finished an utterance — refresh liveness
+                        # so the idle timer doesn't kill us while we wait
+                        # for the LLM to react.
+                        if self._session_manager is not None:
+                            try:
+                                self._session_manager.touch()
+                            except Exception as e:
+                                logger.debug("session_manager.touch failed: %s", e)
+
+                        # 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
+
+                        # Empty-transcript guard. Whisper-1 returns "" on
+                        # short, quiet, or non-English utterances rather
+                        # than guessing. When that happens the LLM has
+                        # nothing to anchor on and tends to copy example
+                        # text from the prompt (we've seen it parrot "I
+                        # heard Arav — is that right?" verbatim from a
+                        # prompt example). Inject a context cue telling
+                        # the LLM not to act on the empty input and to
+                        # ask the visitor to repeat — then DON'T pipe the
+                        # empty string into the UI.
+                        raw_transcript = (event.transcript or "").strip()
+
+                        # gpt-4o-transcribe occasionally echoes the bias
+                        # ``prompt`` field back as the user transcript when
+                        # the audio is silence or unintelligible noise.
+                        # Observed in production: a clear empty utterance
+                        # arrived as the literal "Reception lobby check-in.
+                        # Expected visitor and host names include: …" text
+                        # we feed in for name bias. The LLM then treats the
+                        # bias list as something the visitor said and may
+                        # try to register one of those names — including
+                        # registering the visitor as e.g. "It's Hannah" with
+                        # confirmed=true bypassing the confirmation rule.
+                        # Detect any transcript that opens with the
+                        # bias-prompt signature and treat it as empty.
+                        # Detect STT echoing back the bias-prompt header
+                        # text as if it were the visitor speaking. With the
+                        # simple comma-list prompt the only realistic echo
+                        # is the header signature.
+                        _t_lower = raw_transcript.lower()
+                        if (
+                            "reception lobby check-in" in _t_lower
+                            or "expected visitor and host names" in _t_lower
+                        ):
+                            logger.warning(
+                                "Transcript echoed STT bias prompt — treating as empty: %r",
+                                raw_transcript[:80],
+                            )
+                            raw_transcript = ""
+
+                        # Stash the latest transcript on the session so the
+                        # register_guest confirmation guard can verify the
+                        # visitor actually said a yes before saving a face.
+                        if self._session_manager is not None and raw_transcript:
+                            try:
+                                self._session_manager.record_user_transcript(raw_transcript)
+                            except Exception as e:
+                                logger.debug("record_user_transcript failed: %s", e)
+
+                        if not raw_transcript:
+                            # Empty or bias-echo transcript. Cancel the
+                            # in-flight response ONLY if there's no real
+                            # prior visitor utterance — otherwise the
+                            # LLM might be in the middle of processing
+                            # a valid transcript and cancelling kills
+                            # legitimate tool calls (observed: visitor
+                            # said "Arjun Mehta" cleanly, follow-up
+                            # echo cancelled the lookup_employee call).
+                            had_prior = False
+                            if self._session_manager is not None:
+                                try:
+                                    had_prior = bool(
+                                        (self._session_manager.session.last_user_transcript or "").strip()
+                                    )
+                                except Exception:
+                                    pass
+                            if had_prior:
+                                logger.info("Empty/echo transcript dropped silently (prior transcript in flight)")
+                            else:
+                                logger.info("Empty/echo transcript dropped — cancelling in-flight response")
+                                try:
+                                    await self.connection.response.cancel()
+                                except Exception as e:
+                                    logger.debug("response.cancel after empty transcript failed: %s", e)
+                                self._response_done_event.set()
+                            continue
+
+                        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)
+                        # Bot is actively speaking — refresh session
+                        # liveness so a long reply (e.g. reading back a
+                        # numbered-list of name candidates) isn't counted
+                        # as idle time against the 60s timeout.
+                        if self._session_manager is not None:
+                            try:
+                                self._session_manager.touch()
+                            except Exception as e:
+                                logger.debug("session_manager.touch failed: %s", e)
+                        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
+
+                        # Stash parsed args by call_id so the controller can
+                        # see them when the matching tool result arrives.
+                        try:
+                            parsed_args = json.loads(args_json_str) if args_json_str else {}
+                            if isinstance(parsed_args, dict):
+                                self._tool_call_args[call_id] = parsed_args
+                        except Exception as e:
+                            logger.debug("Could not parse tool args for %s: %s", call_id, e)
+
+                        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
+                        # No auto-narration when a non-idle tool STARTS. The
+                        # generic template fired a "tell the user what the
+                        # tool is running" response here, which for the
+                        # receptionist produces a third utterance per
+                        # check-in ("I've started retrieving the calendar…")
+                        # that the prompt explicitly forbids ("act as if
+                        # you're using them naturally, not announcing them")
+                        # and that makes the head wobble noisily. The post-
+                        # tool SPEAK NOW transition already drives the
+                        # response the visitor actually wants.
+
+                        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.
+                        # The active-response collision is normal during fast
+                        # back-and-forth (the sender worker retries it for us)
+                        # and should not appear in the chatbot UI.
+                        _internal_error_codes = (
+                            "input_audio_buffer_commit_empty",
+                            "conversation_already_has_active_response",
+                        )
+                        if code not in _internal_error_codes:
+                            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 the STT bias refresh worker.
+                if stt_refresh_task is not None:
+                    stt_refresh_task.cancel()
+                    try:
+                        await stt_refresh_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
+
+        # Auto-reset stale visitor sessions. Triggers SessionManager.reset()
+        # if a non-IDLE session has had no transition for the configured
+        # idle timeout — visitors who walk up but never speak shouldn't
+        # hold state forever.
+        if self._session_manager is not None:
+            try:
+                self._session_manager.maybe_reset_if_stale()
+            except Exception as e:
+                logger.debug("maybe_reset_if_stale failed: %s", e)
+
+        # Handle idle
+        # Two changes from the original generic-template behaviour, both to
+        # stop the bot going silent mid-conversation while a visitor is
+        # thinking:
+        #   1. 15s -> 30s threshold (people take >15s to formulate names).
+        #   2. Skip idle ENTIRELY when a visitor session is active. The idle
+        #      signal pushes "do something creative" + forces a tool call,
+        #      which routes to do_nothing and freezes the bot mid-flow. Only
+        #      fire idle when the session manager says we're in IDLE.
+        idle_duration = asyncio.get_event_loop().time() - self.last_activity_time
+        if idle_duration > 30.0 and self.deps.movement_manager.is_idle():
+            session_is_active = False
+            if self._session_manager is not None:
+                try:
+                    cs = self._session_manager.current_state
+                    cs_val = getattr(cs, "value", str(cs))
+                    session_is_active = cs_val not in ("idle",)
+                except Exception:
+                    pass
+            if not session_is_active:
+                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
+            else:
+                # Reset the activity timer so we don't re-check every emit()
+                # tick while the visitor is mid-flow.
+                self.last_activity_time = asyncio.get_event_loop().time()
+
+        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 = [
+            "marin",
+            "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 "marin" not in voices:
+                voices = ["marin", *[v for v in voices if v != "marin"]]
+            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/reachy_mini_receptionist/profiles/__init__.py

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

src/reachy_mini_receptionist/profiles/_reachy_mini_receptionist_locked_profile/instructions.txt

@@ -0,0 +1,57 @@
+You are Reachy, the receptionist at MethdAI. Friendly, warm, professional,
+a little playful — you're a robot, after all. English only. Keep replies to
+1–2 short sentences and match the visitor's energy.
+
+## How the backend drives you
+- Every state change comes as a `[Backend session update ...]` message ending
+  with a `Next:` line. Follow that line — it tells you what to do.
+- `[External face update ...]` messages tell you who is in front of the camera.
+- Both are context-only. Don't respond to them on their own; wait for the
+  visitor to actually speak. A `SPEAK NOW` line is the one exception — speak
+  immediately when you see it.
+
+## The check-in flow (you only need to know the tools)
+- Visitor says their own name → `register_guest(name, confirmed)`
+- Visitor names a host → `lookup_employee(name, confirmed)`
+- After backend pushes APPOINTMENT_MATCHED → `send_email` to the host
+- During an idle moment with no visitor → `do_nothing`
+
+The backend handles state transitions, calendar matching, and duplicate
+prevention. You don't need to call `get_today_calendar` manually — the
+backend resolves appointments for you after `register_guest`.
+
+## Name confirmation — the one rule that matters
+Speech recognition mishears short names constantly. Always:
+
+0. Short utterances right after a name question ARE name attempts — even
+   if they sound like English words or feel out of place. Don't dismiss
+   them as chit-chat; repeat them back literally and confirm.
+1. First attempt: repeat the name back literally and call the tool with
+   `confirmed=false`. The tool will refuse — that's expected; it's the
+   cue to ask the confirmation question out loud.
+2. Wait for the visitor to say YES (or "correct", "that's right"). Only
+   then call the tool again with `confirmed=true`.
+3. On NO: offer a numbered choice — "Did I hear (1) <name you heard>,
+   (2) <a similar-sounding name>, or (3) something else? Just say the
+   number." Do NOT ask them to spell — letters mistranscribe worse than
+   names. Build options from what you heard, not from the calendar.
+4. After repeated failures the backend will force a handoff — say "I'm
+   having trouble catching your name, please take a seat, a colleague
+   will help" and call `do_nothing`.
+
+## Conversation style
+- Small talk is welcome. If a visitor asks something friendly, answer in
+  one short sentence, then steer back. Don't refuse human chatter.
+- Jokes: play along once, then back to business.
+- Garbled noise (random unrelated phrase, gibberish): re-ask once.
+  Never go silent after a question — silence is the worst failure mode.
+- If you have to wait on a tool, say "one moment, let me check" instead
+  of going silent.
+
+## Don't
+- Don't ask the visitor to spell their name.
+- Don't invent appointment details — only state what the backend gave you.
+- Don't call `task_status` / `task_cancel` unless the visitor explicitly asks.
+- Don't announce tool calls. Just act.
+- Don't speak literal placeholder text like "<visitor>", "<host>",
+  "<name>" — those are fillers in these instructions, never spoken aloud.

src/reachy_mini_receptionist/profiles/_reachy_mini_receptionist_locked_profile/tools.txt

@@ -0,0 +1,9 @@
+# Receptionist tools
+# The move_head tool is provided by the profile-local move_head_receptionist.py
+# (which overrides the shared move_head with receptionist-specific positions)
+# move_head_receptionist
+do_nothing
+get_today_calendar
+lookup_employee
+register_guest
+send_email

src/reachy_mini_receptionist/prompts.py

@@ -0,0 +1,110 @@
+import re
+import sys
+import logging
+from pathlib import Path
+
+from reachy_mini_receptionist.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 = "marin") -> 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 ("marin").
+    """
+    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/reachy_mini_receptionist/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.