Upload 344 files

.env.example

@@ -0,0 +1,79 @@
+# =============================================================================
+# OpenWebUI connection
+# =============================================================================
+# OpenWebUI base URL. Values ending in /api are accepted.
+OPENWEBUI_URL=http://localhost:3001/api
+
+# Model/workspace id as known by OpenWebUI.
+OPENWEB_LOADED_LLM=reachy-convo
+
+# API key for OpenWebUI HTTP endpoints when API-key bearer auth is accepted.
+OPENWEBUI_API_KEY=
+
+# OpenWebUI browser/session JWT. Preferred over OPENWEBUI_API_KEY and required
+# for authenticated Socket.IO user-join behavior.
+OPENWEBUI_TOKEN=
+
+# Optional browser User-Agent sent with OpenWebUI requests.
+OPENWEBUI_USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36
+
+
+# =============================================================================
+# OpenWebUI chat state
+# =============================================================================
+# Leave blank on first launch. The app saves the real OpenWebUI chat id after a
+# successful turn. Callback and daily rollover clear this value on purpose.
+OPENWEBUI_CHAT_ID=
+OPENWEBUI_CHAT_WINDOW_START=
+OPENWEBUI_CHAT_PENDING_REASON=
+OPENWEBUI_CHAT_PENDING_EVENT_ID=
+
+
+# =============================================================================
+# OpenWebUI variables and user context
+# =============================================================================
+OPENWEBUI_USER_ID=
+OPENWEBUI_USER_NAME=Reachy
+OPENWEBUI_USER_EMAIL=reachy@example.local
+OPENWEBUI_USER_LANGUAGE=en-US
+OPENWEBUI_USER_LOCATION=Unknown
+OPENWEBUI_USER_TIMEZONE=America/New_York
+
+
+# =============================================================================
+# Audio, speech, and VAD
+# =============================================================================
+# Digital gain applied to microphone input before VAD and transcription upload.
+MIC_GAIN=1.0
+
+# OpenWebUI speech read timeout in seconds.
+OPENWEBUI_TTS_READ_TIMEOUT=15.0
+
+# No-wake-word VAD tuning. ONNX Silero is preferred; audio-level fallback keeps
+# startup alive if ONNX Runtime or the model is unavailable.
+VAD_THRESHOLD=0.12
+VAD_FALLBACK_THRESHOLD=0.010
+VAD_SPEECH_ONSET_CHUNKS=2
+VAD_SILENCE_END_CHUNKS=70
+VAD_MIN_SPEECH_CHUNKS=8
+
+# Optional override for the downloaded Silero ONNX model path. Blank uses
+# ~/.cache/reachy-openwebui-vad/silero_vad.onnx.
+SILERO_VAD_ONNX_PATH=
+
+# Optional idle timeout. 0 disables idle-based conversation reset.
+OPENWEBUI_CONVERSATION_IDLE_RESET_SECONDS=0
+
+
+# =============================================================================
+# Vision and Hugging Face cache
+# =============================================================================
+# Local device vision model used only when optional local vision code is present
+# and the app is launched with --smolvlm.
+LOCAL_DEV_VISION_MODEL=HuggingFaceTB/SmolVLM2-2.2B-Instruct
+
+# Cache directory for downloaded Hugging Face assets.
+HF_HOME=./cache
+
+# Optional Hugging Face token for gated/private assets.
+HF_TOKEN=

.gitattributes

@@ -1,35 +1,61 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# 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 text eol=lf
+*.svgz text eol=lf
+*.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
+docs/assets/reachy_mini_dance.gif filter=lfs diff=lfs merge=lfs -text
+src/reachy_mini_conversation_app/images/reachymini_avatar.png filter=lfs diff=lfs merge=lfs -text
+src/reachy_mini_conversation_app/images/user_avatar.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/reachymini_avatar.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/user_avatar.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/static/assets/reachy-conversation-app.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/__pycache__/console.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/astronaut.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/captain.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/cowboy.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/explorer.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/farmer-2sejRPMv.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/plumber.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/reachy-conversation-app.jpg filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/reachy-conversation-app.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/reachy-how-to-create-app.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/reachy-icon.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/images/sleeping-reachy.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/static/assets/pwa-icon-512.png filter=lfs diff=lfs merge=lfs -text
+src/Reachy_OpenWebUI/static/assets/settings-icon.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,15 @@
+.env
+__pycache__/
+*.py[cod]
+build/
+*.egg-info/
+.tmp_wheel_test/
+dist/
+
+# Local-only developer scratch files and private bot overlays.
+dev/
+turbo/
+local_bot/
+
+# Raw OpenWebUI model exports can include user ids, emails, and access grants.
+profiles/*/*.json

APP_INTEGRATION_LAYER.md

@@ -0,0 +1,57 @@
+# App Integration Layer
+
+Each mini app keeps its own files inside its own app folder.
+
+For CookAIware, the app folder is:
+
+`src/Reachy_OpenWebUI/sub_apps/cookAIware/`
+
+That folder owns CookAIware-specific tools, prompts, profile files, data helpers, assets, and app behavior. If CookAIware needs to be removed, this folder should be safe to wipe after removing its integration-layer hooks.
+
+For the base conversation app, the app folder is:
+
+`src/Reachy_OpenWebUI/sub_apps/conversation_app/`
+
+That folder owns conversation-mode support code such as chat history, VAD helpers, and the OpenWebUI local handler/LLM/TTS pipeline. Keep conversation-only state and helpers there instead of spreading them through the global app package.
+
+## Integration Layer
+
+The integration layer is the only place where app-specific code is allowed to touch the shared Reachy app.
+
+Current CookAIware integration-layer files:
+
+`src/Reachy_OpenWebUI/static/index.html`
+
+`src/Reachy_OpenWebUI/static/main.js`
+
+`src/Reachy_OpenWebUI/static/style.css`
+
+`src/Reachy_OpenWebUI/console.py`
+
+`src/Reachy_OpenWebUI/local/handler.py`
+
+`src/Reachy_OpenWebUI/tools/core_tools.py`
+
+`pyproject.toml`
+
+## Rule
+
+Do not scatter app-owned files through shared folders.
+
+Shared files should only contain the wiring needed to:
+
+- show or launch the app
+- route app requests to the backend
+- load the app profile/tools
+- pass runtime context into the shared conversation spine
+- package the app folder
+
+Everything else belongs in the app folder.
+
+## Removal Checklist
+
+To remove an app:
+
+1. Delete its app folder.
+2. Remove its entries from the integration-layer files.
+3. Restart and verify the shared app still starts.

ATTITUDE_PLAN.md

@@ -0,0 +1,128 @@
+# Reachy Attitude Plan
+
+## Goal
+
+Make Reachy feel different per contact/model by selecting one simple user-facing `Attitude`.
+
+The app should not expose separate controls for idle, speaking, and tool moves. The chosen attitude should control those internal pieces together.
+
+## Core Idea
+
+One setting:
+
+```text
+Attitude
+```
+
+That attitude controls:
+
+```text
+idle movement
+speaking movement
+available emotion/dance tool moves
+```
+
+All robot movement stays bot-side/local. OpenWebUI models can trigger tools, but Reachy decides what moves are available and how they execute.
+
+## Movement Types
+
+`Idle movement`
+
+Runs when Reachy is waiting, listening, or between responses.
+
+`Speaking movement`
+
+Runs while TTS is playing. This should be procedural and loopable, not a big recorded emotion every sentence.
+
+`Accent moves`
+
+One-shot recorded emotion/dance moves, usually triggered by tool calls or selected from an attitude's allowed move pool.
+
+## Attitude Examples
+
+`flirty`
+
+Soft, playful, attentive. Good candidate accents: `shy1`, `loving1`, `welcoming2`, `laughing2`, `thoughtful2`.
+
+`serious`
+
+Restrained, direct, minimal. Good candidate accents: `attentive1`, `understanding2`, `inquiring1`, `thoughtful1`.
+
+`spaceshot`
+
+Distracted, wandering, odd timing. Good candidate accents: `lost1`, `curious1`, `confused1`, `inquiring3`, `indifferent1`.
+
+`depressed`
+
+Low energy, slower, downward posture. Good candidate accents: `downcast1`, `sad2`, `tired1`, `resigned1`, `lonely1`.
+
+`tough`
+
+Harder, less friendly, guarded. Good candidate accents: `impatient1`, `impatient2`, `irritated1`, `displeased2`, `contempt1`.
+
+`silly`
+
+Goofy, bouncy, reactive. Good candidate accents: `curious1`, `indifferent1`, `proud2`, `laughing2`, `dance1`.
+
+## Emotion Library Use
+
+The emotion library source is:
+
+```text
+C:\Users\jsnmd\Documents\Reachy_OpenWebUI\reachy-mini-emotions-library
+```
+
+The `.json` files are the recorded motion data. The matching `.wav` files are audio and should not be used unless we intentionally want robot-side sound.
+
+Most recorded moves are too theatrical for idle. Use them as occasional accent moves, not continuous behavior.
+
+## Tool Move Gating
+
+The app sends tool schemas with each model message turn.
+
+That means allowed `play_emotion` and `dance` choices can be changed before each model response based on the currently selected attitude.
+
+Example:
+
+```text
+Attitude = flirty
+play_emotion enum = shy1, loving1, welcoming2, laughing2
+
+Attitude = serious
+play_emotion enum = attentive1, understanding2, inquiring1, thoughtful1
+```
+
+The model only sees the allowed list for that turn. If the attitude changes, the next message can send a different list.
+
+## UI Plan
+
+Keep the settings UI simple:
+
+```text
+Attitude
+```
+
+Do not expose separate idle/speaking/accent settings in the first pass.
+
+Rename the current `Idle attitude` field to `Attitude`.
+
+## Implementation Plan
+
+1. Rename current user-facing `Idle attitude` wording to `Attitude`.
+2. Keep the existing backend setting for now unless renaming it is worth the churn.
+3. Add an attitude definition structure that includes:
+   - idle motion parameters
+   - speaking motion parameters
+   - allowed emotion moves
+   - allowed dance moves
+4. Use selected attitude to filter `play_emotion` tool enum per message.
+5. Use selected attitude to filter `dance` tool enum per message.
+6. Keep full tool enable/disable separate from move gating.
+7. Later, allow OpenWebUI model/contact metadata to select attitude automatically, with manual app setting as fallback or override.
+
+## Do Not Do Yet
+
+- Do not dump the full emotion library into the app repo.
+- Do not make separate UI controls for idle and speaking movement.
+- Do not use long theatrical moves as random idle loops.
+- Do not depend on OpenWebUI to execute robot movement.

CODE_OF_CONDUCT.md

@@ -0,0 +1,89 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, please, send an email to contact@pollen-robotics.com. 
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) **Warning**
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) **Temporarily Limited Activities**
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) **Temporary Suspension**
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) **Permanent Ban**
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing
+
+Thank you for helping improve Reachy OpenWebUI.
+
+This repository is an OpenWebUI-native Reachy Mini app. Keep changes aligned with the current shape of the code: OpenWebUI owns transcription, model/workspace behavior, variables, and speech; the Reachy app owns robot media, settings, tool dispatch, VAD, and motion.
+
+## Quick Start
+
+1. Fork and clone the repo.
+
+```bash
+git clone https://github.com/pollen-robotics/Reachy_OpenWebUI
+cd Reachy_OpenWebUI
+```
+
+2. Create an environment.
+
+```bash
+uv venv --python python3.12 .venv
+source .venv/bin/activate
+uv sync --group dev
+```
+
+3. Copy `.env.example` only for local development. Do not commit real `.env` files or secrets.
+
+## Current Project Shape
+
+- Python package: `Reachy_OpenWebUI`
+- Reachy Mini Apps entry point: `Reachy_OpenWebUI`
+- Console script: `reachy-mini-conversation-app-openwebui`
+- Main runtime code: `src/Reachy_OpenWebUI/`
+- Settings/call UI: `src/Reachy_OpenWebUI/static/`
+- Default tool allow-list: `src/Reachy_OpenWebUI/profiles/default/tools.txt`
+- Hugging Face Space project page: `app.py`
+
+`requirements.txt` is for the Space project page only. Use `pyproject.toml` for the robot app dependencies.
+
+## Development Workflow
+
+- Keep pull requests focused on one behavior or documentation update.
+- Prefer small, reviewable changes over broad rewrites.
+- Do not reintroduce legacy local STT, voice-provider, or old package-name docs unless the code actually supports them again.
+- Keep OpenWebUI auth wording precise: API keys may work for HTTP endpoints, but the realtime socket path needs a JWT in `OPENWEBUI_TOKEN`.
+- Update README and `.env.example` whenever settings, CLI flags, package names, or user-visible behavior change.
+- Avoid committing generated files, real settings files, downloaded models, caches, or secrets.
+
+## Checks
+
+Run the checks that are available in this checkout:
+
+```bash
+uv run ruff check .
+uv run ruff format . --check
+uv run mypy --pretty --show-error-codes
+uv run python -m compileall src app.py
+```
+
+There is no `tests/` directory in this checkout. Add focused tests when you add behavior that can be tested without robot hardware.
+
+## Documentation Checklist
+
+Before opening a PR, verify docs against the actual code:
+
+- CLI flags come from `src/Reachy_OpenWebUI/utils.py`.
+- Env keys come from `src/Reachy_OpenWebUI/settings_keys.py` and `src/Reachy_OpenWebUI/config.py`.
+- Settings UI routes come from `src/Reachy_OpenWebUI/console.py`.
+- Tool names come from `src/Reachy_OpenWebUI/profiles/default/tools.txt` and `src/Reachy_OpenWebUI/tools/`.
+- Package names and entry points come from `pyproject.toml`.
+
+## Release Notes
+
+When preparing a release:
+
+1. Update the version in `pyproject.toml`.
+2. Confirm README and `.env.example` match the release behavior.
+3. Run the checks above.
+4. Commit the version bump.
+5. Create and push a tag.
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+## AI-Assisted Contributions
+
+AI tools are fine for exploration and drafts, but the human author is responsible for the final patch. Keep AI-assisted changes readable, minimal, and verified against the code that is actually in the repo.
+
+## Filing Issues
+
+For bugs, include the Reachy Mini environment, Python version, OpenWebUI URL shape, auth mode, exact command or launcher path, and relevant logs. Use `--debug` when collecting local logs.
+
+For feature requests, describe the user workflow, expected robot behavior, and whether the change belongs in OpenWebUI, the Reachy settings UI, or the robot-side tool/runtime layer.

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.

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/Reachy_OpenWebUI/profiles *.txt *.py

README.md

@@ -1,11 +1,253 @@
----
-title: Reachy OpenWebUI
-emoji: 📊
-colorFrom: gray
-colorTo: red
-sdk: static
-pinned: false
-license: apache-2.0
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Reachy OpenWebUI
+emoji: 🐞
+colorFrom: gray
+colorTo: blue
+sdk: gradio
+app_file: app.py
+pinned: false
+short_description: Phone-style OpenWebUI conversations for Reachy Mini.
+tags:
+- reachy_mini
+- reachy_mini_python_app
+sdk_version: 6.18.0
+license: apache-2.0
+---
+
+<p align="center">
+  <img src="src/Reachy_OpenWebUI/static/assets/reachy-conversation-app.png" width="112" alt="Reachy OpenWebUI icon">
+</p>
+
+# Reachy OpenWebUI
+
+Reachy OpenWebUI is a phone-style conversation app for Reachy Mini. OpenWebUI owns the model, transcription, chat behavior, user context, and TTS. This app owns the robot-side runtime: settings, no-wake-word listening, camera buffering, local Reachy tools, avatars, chat state, and motion.
+
+This Hugging Face Space is a project page. The real app runs inside the Reachy Mini app environment where it can access the robot daemon, microphone, speaker, camera, and movement APIs.
+
+## Highlights
+
+- Phone-inspired settings and conversation UI served by the Reachy Mini app webserver.
+- OpenWebUI model/workspace picker shown as contacts.
+- OpenWebUI conversation list support for returning to saved chats.
+- Model and user avatar proxying from OpenWebUI profile image endpoints.
+- No-wake-word voice loop using Reachy audio, Silero VAD, OpenWebUI STT, OpenWebUI chat, and OpenWebUI TTS.
+- Sentence-by-sentence speech streaming so audio starts before the full model answer is finished.
+- Reachy-side tools for dance, recorded emotions, camera, head tracking, head movement, and speech.
+- Speech-reactive head motion blended with queued robot moves.
+- Robot attitudes that can shape idle motion, speaking motion, and which dance/emotion moves the model can choose.
+
+## Runtime Flow
+
+```text
+Reachy microphone
+  -> audio startup tuning and SDK record loop
+  -> Silero VAD and level fallback
+  -> OpenWebUI audio transcription
+  -> OpenWebUI chat stream with optional Reachy tool specs
+  -> optional Reachy-side tool execution
+  -> OpenWebUI speech
+  -> Reachy speaker output plus speech-reactive motion
+```
+
+OpenWebUI may accept requests at `/api/chat/completions` while returning either
+classic chat-completion chunks (`chat.completion.chunk`) or Responses-style
+events (`response.output_text.delta`, `response.output_text.done`,
+`response.completed`). The runtime reader must support both formats because the
+selected OpenWebUI model/contact can route through different providers even when
+the model id shown in the UI is unchanged.
+
+## Install
+
+This repo currently has no `uv.lock`, so do not use `uv sync --frozen`.
+
+```bash
+uv venv --python python3.12 .venv
+source .venv/bin/activate
+uv sync
+```
+
+Editable pip install:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Optional local vision extra:
+
+```bash
+uv sync --extra local_vision
+pip install -e .[local_vision]
+```
+
+Developer tools:
+
+```bash
+uv sync --group dev
+```
+
+`requirements.txt` is only for this Hugging Face Space project page. The robot app dependencies live in `pyproject.toml`.
+
+## Configuration
+
+The app reads `~/.config/settings/.env` first, then a local `.env` if present. The settings UI writes the stable file at `~/.config/settings/.env`.
+
+Core OpenWebUI settings:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENWEBUI_URL` | OpenWebUI base URL. Values ending in `/api` are accepted. |
+| `OPENWEB_LOADED_LLM` | Selected OpenWebUI model, workspace, or contact id. |
+| `OPENWEBUI_API_KEY` | API key for HTTP requests when your OpenWebUI server accepts API-key bearer auth. |
+| `OPENWEBUI_TOKEN` | Browser/session JWT. Preferred for chat, Socket.IO, transcription, and speech. |
+| `OPENWEBUI_CHAT_ID` | Saved OpenWebUI chat id. Leave blank on first launch. |
+| `MIC_GAIN` | Digital gain applied before VAD and transcription upload. |
+| `HF_HOME` | Hugging Face cache directory. |
+| `HF_TOKEN` | Optional token for gated or private assets. |
+
+User/context variables sent to OpenWebUI:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENWEBUI_USER_ID` | Optional user id. If blank, the app tries to derive it from the JWT. |
+| `OPENWEBUI_USER_NAME` | User name supplied to OpenWebUI variables and socket context. |
+| `OPENWEBUI_USER_EMAIL` | User email supplied to OpenWebUI variables and socket context. |
+| `OPENWEBUI_USER_LANGUAGE` | User language variable. |
+| `OPENWEBUI_USER_LOCATION` | User location variable. |
+| `OPENWEBUI_USER_TIMEZONE` | User timezone variable. |
+
+Audio and timing settings:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENWEBUI_TTS_READ_TIMEOUT` | Read timeout for OpenWebUI speech responses. |
+| `OPENWEBUI_CONVERSATION_IDLE_RESET_SECONDS` | Optional idle reset. `0` disables it. |
+| `VAD_THRESHOLD` | Silero speech probability threshold. |
+| `VAD_FALLBACK_THRESHOLD` | RMS fallback threshold. |
+| `VAD_SPEECH_ONSET_CHUNKS` | Speech chunks required before a turn starts. |
+| `VAD_SILENCE_END_CHUNKS` | Silence chunks required before a turn ends. |
+| `VAD_MIN_SPEECH_CHUNKS` | Minimum speech chunks before sending audio to OpenWebUI transcription. |
+| `SILERO_VAD_ONNX_PATH` | Optional path for the Silero ONNX model. |
+
+## TTS Voices
+
+Set TTS voices in OpenWebUI. This app reads the selected model/contact voice metadata and sends that voice back to the OpenWebUI speech endpoint.
+
+If a model/contact has no voice set in OpenWebUI, the app sends no voice value and lets OpenWebUI use its default TTS behavior. There is intentionally no app-level voice picker because every OpenWebUI install can expose different TTS engines and voice names.
+
+## Running
+
+The normal runtime path is the Reachy Mini Apps launcher. It provides the FastAPI settings app and serves the phone UI declared by:
+
+```python
+custom_app_url = "http://0.0.0.0:7860/"
+```
+
+Console entry point:
+
+```bash
+reachy-mini-conversation-app-openwebui
+```
+
+CLI options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--no-camera` | `False` | Skip camera frame buffering. |
+| `--smolvlm` | `False` | Try to initialize the optional local SmolVLM vision manager. |
+| `--robot-name <name>` | `None` | Connect to a daemon started with the same robot name. |
+| `--debug` | `False` | Enable verbose app logging. |
+
+## Settings UI
+
+The phone-style UI lives in `src/Reachy_OpenWebUI/static/`.
+
+It includes:
+
+- Power-on screen while the backend is getting ready.
+- Home screen with contacts, conversations, quick connect, and settings.
+- Contacts page backed by OpenWebUI models.
+- Conversations page backed by OpenWebUI chat history.
+- Call screen with transcript bubbles, typing indicators, model avatar, user avatar, mute, end call, and back navigation.
+- Settings for OpenWebUI URL, model/contact, credentials, mic gain, vision-only contacts, attitude, and Reachy-side tools.
+
+## Tools
+
+Default Reachy-side tool allow-list:
+
+```text
+src/Reachy_OpenWebUI/profiles/default/tools.txt
+```
+
+Enabled by default:
+
+| Tool | Behavior |
+| --- | --- |
+| `dance` | Queue a named or random dance from `reachy_mini_dances_library`. |
+| `stop_dance` | Clear the dance queue. |
+| `play_emotion` | Queue a recorded emotion from `reachy-mini-emotions-library`. |
+| `stop_emotion` | Clear the emotion queue. |
+| `camera` | Read the latest buffered camera frame and pass it to an optional vision manager. |
+| `idle_do_nothing` | Explicit idle no-op for idle turns. |
+| `head_tracking` | Attempt to toggle camera-worker head tracking. |
+| `move_head` | Queue a head pose change: left, right, up, down, or front. |
+| `speak` | Send text through the same OpenWebUI speech path used by normal assistant responses. |
+
+The settings page can enable or disable Reachy-side tools. OpenWebUI tools are still managed in OpenWebUI.
+
+## Attitudes
+
+`Attitude` is one user-facing movement setting. It is designed to control:
+
+- idle motion
+- speech-reactive motion
+- which dance and emotion moves are offered to the model
+
+The goal is simple: a serious model should not move like a silly one, and a playful model should not be stuck with the same tiny idle pattern as a formal one.
+
+## Chat State
+
+OpenWebUI chat state is stored in the stable settings file and recorded in:
+
+```text
+~/.config/settings/openwebui_chat_history.json
+```
+
+The conversation window rolls over at local 7 AM. Callback and conversation selection clear or replace the saved chat id so OpenWebUI can attach the next turn to the right conversation.
+
+## Vision Status
+
+Camera frame buffering is bundled and enabled unless `--no-camera` is passed. The optional local vision manager expects `Reachy_OpenWebUI.vision.processors`, which is not present in this checkout. If that module is absent, startup logs a warning and the `camera` tool returns an unavailable-vision error.
+
+## Project Layout
+
+```text
+app.py                                    Hugging Face Space project page
+pyproject.toml                            package metadata, dependencies, app entry points
+requirements.txt                          Space-only dependency file
+src/Reachy_OpenWebUI/main.py              Reachy Mini App entry point
+src/Reachy_OpenWebUI/console.py           settings routes and media loop
+src/Reachy_OpenWebUI/local/               OpenWebUI chat, speech, transcription, VAD
+src/Reachy_OpenWebUI/tools/               Reachy-side tools
+src/Reachy_OpenWebUI/static/              phone-style UI
+src/Reachy_OpenWebUI/profiles/default/    default tool allow-list
+external_content/                         starter external profile/tool examples
+```
+
+## Development Checks
+
+Run the checks available in this checkout:
+
+```bash
+uv run ruff check .
+uv run ruff format . --check
+uv run mypy --pretty --show-error-codes
+uv run python -m compileall src app.py
+```
+
+There is no `tests/` directory in this checkout. Add focused tests when adding behavior that can be tested off-robot.
+
+## License
+
+Apache 2.0

app.py

@@ -0,0 +1,239 @@
+import base64
+from pathlib import Path
+
+import gradio as gr
+
+
+CSS = """
+:root {
+  color-scheme: dark;
+}
+
+.gradio-container {
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 18% 8%, rgba(0, 122, 204, 0.20), transparent 28rem),
+    radial-gradient(circle at 90% 16%, rgba(80, 180, 150, 0.12), transparent 24rem),
+    linear-gradient(145deg, #0b0f14 0%, #121821 48%, #070a0f 100%) !important;
+  color: #eef3f8;
+  font-family: Inter, Segoe UI, Arial, sans-serif;
+}
+
+.main {
+  max-width: 1120px;
+  margin: 0 auto;
+  padding: 36px 20px 44px;
+}
+
+.hero {
+  display: grid;
+  grid-template-columns: minmax(0, 1.25fr) minmax(280px, 0.75fr);
+  gap: 28px;
+  align-items: center;
+  padding: 24px 0 34px;
+}
+
+.eyebrow {
+  margin: 0 0 12px;
+  color: #7bb9e8;
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.hero h1 {
+  margin: 0;
+  color: #ffffff;
+  font-size: clamp(2.5rem, 7vw, 5.4rem);
+  line-height: 0.94;
+  letter-spacing: 0;
+}
+
+.lead {
+  max-width: 680px;
+  margin: 22px 0 0;
+  color: #b8c6d5;
+  font-size: 1.08rem;
+  line-height: 1.65;
+}
+
+.hero-card,
+.panel {
+  border: 1px solid rgba(180, 198, 213, 0.16);
+  border-radius: 8px;
+  background: rgba(13, 19, 28, 0.74);
+  box-shadow: 0 22px 70px rgba(0, 0, 0, 0.36);
+}
+
+.hero-card {
+  display: grid;
+  gap: 16px;
+  padding: 22px;
+}
+
+.app-mark {
+  width: 90px;
+  height: 90px;
+  border-radius: 22px;
+  background: #0f1620;
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.08);
+}
+
+.hero-card h2,
+.panel h2 {
+  margin: 0;
+  color: #ffffff;
+  font-size: 1.15rem;
+}
+
+.hero-card p,
+.panel p {
+  margin: 0;
+  color: #b8c6d5;
+  line-height: 1.55;
+}
+
+.chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 4px;
+}
+
+.chip {
+  border: 1px solid rgba(123, 185, 232, 0.28);
+  border-radius: 999px;
+  padding: 6px 10px;
+  color: #d9ecfb;
+  background: rgba(0, 122, 204, 0.14);
+  font-size: 0.86rem;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 14px;
+  margin-top: 18px;
+}
+
+.panel {
+  padding: 18px;
+}
+
+.section-title {
+  margin: 36px 0 12px;
+  color: #ffffff;
+  font-size: 1.35rem;
+}
+
+.flow {
+  display: grid;
+  gap: 8px;
+  padding: 18px;
+  border: 1px solid rgba(180, 198, 213, 0.14);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.045);
+  color: #d5e2ec;
+  font-family: Consolas, Monaco, monospace;
+  font-size: 0.92rem;
+}
+
+.flow span {
+  display: block;
+}
+
+.footer-note {
+  margin-top: 28px;
+  color: #8393a2;
+  font-size: 0.92rem;
+}
+
+@media (max-width: 820px) {
+  .hero,
+  .grid {
+    grid-template-columns: 1fr;
+  }
+}
+"""
+
+
+def _image_data_uri(path: str) -> str:
+    image_path = Path(path)
+    if not image_path.exists():
+        return ""
+    encoded = base64.b64encode(image_path.read_bytes()).decode("ascii")
+    return f"data:image/png;base64,{encoded}"
+
+
+ICON_URI = _image_data_uri("src/Reachy_OpenWebUI/static/assets/reachy-conversation-app.png")
+
+
+HTML = f"""
+<main class="main">
+  <section class="hero">
+    <div>
+      <p class="eyebrow">Reachy Mini + OpenWebUI</p>
+      <h1>Reachy OpenWebUI</h1>
+      <p class="lead">
+        A phone-style conversation app for Reachy Mini. OpenWebUI handles the model,
+        transcription, user context, and TTS; the Reachy app handles the robot runtime,
+        settings UI, local tools, avatars, chat state, and movement.
+      </p>
+    </div>
+    <aside class="hero-card">
+      <img class="app-mark" src="{ICON_URI}" alt="">
+      <h2>Project Page</h2>
+      <p>
+        This Space is a lightweight overview. The real app runs in the Reachy Mini
+        app environment where it can access robot audio, camera, speaker, and motion.
+      </p>
+      <div class="chips">
+        <span class="chip">Phone UI</span>
+        <span class="chip">OpenWebUI TTS</span>
+        <span class="chip">Robot tools</span>
+        <span class="chip">Attitudes</span>
+      </div>
+    </aside>
+  </section>
+
+  <h2 class="section-title">What It Does</h2>
+  <section class="grid">
+    <div class="panel">
+      <h2>Contacts</h2>
+      <p>OpenWebUI models and workspaces appear as phone contacts with cached avatars.</p>
+    </div>
+    <div class="panel">
+      <h2>Conversations</h2>
+      <p>Saved OpenWebUI chat ids can be selected from a phone-style conversation list.</p>
+    </div>
+    <div class="panel">
+      <h2>Motion</h2>
+      <p>Speech-reactive head movement blends with Reachy-side dances and recorded emotions.</p>
+    </div>
+  </section>
+
+  <h2 class="section-title">Runtime Flow</h2>
+  <div class="flow" aria-label="Runtime flow">
+    <span>Reachy microphone</span>
+    <span>-> VAD and OpenWebUI transcription</span>
+    <span>-> OpenWebUI chat completion with Reachy tool specs</span>
+    <span>-> optional local Reachy tool execution</span>
+    <span>-> OpenWebUI speech</span>
+    <span>-> Reachy speaker output plus motion</span>
+  </div>
+
+  <p class="footer-note">
+    Install from the repository and launch through Reachy Mini Apps for the full robot runtime.
+    This hosted Space intentionally does not attempt to control hardware.
+  </p>
+</main>
+"""
+
+
+with gr.Blocks(title="Reachy OpenWebUI") as demo:
+    gr.HTML(HTML)
+
+
+if __name__ == "__main__":
+    demo.launch(css=CSS)

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,12 @@
+# This file is an explicit allow-list.
+# Every tool name listed below must be either:
+# - a built-in tool from src/Reachy_OpenWebUI/tools/
+# - or an external tool file in TOOLS_DIRECTORY (e.g. external_tools/starter_custom_tool.py)
+
+dance
+stop_dance
+play_emotion
+stop_emotion
+move_head
+starter_custom_tool
+

external_content/external_tools/starter_custom_tool.py

@@ -0,0 +1,34 @@
+"""Example external tool implementation."""
+
+import logging
+from typing import Any, Dict
+
+from Reachy_OpenWebUI.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

@@ -1,19 +1,125 @@
-<!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
-</html>
+<!doctype html>
+<html>
+
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1" />
+	<title>Reachy Mini Conversation OpenWebUI</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">OpenWebUI managed voice and personality · No wake word</div>
+		</div>
+		<div class="hero-grid">
+			<div class="hero-copy">
+				<p class="eyebrow">Local Conversation App</p>
+				<h1>Run Reachy Mini conversations on your own stack.</h1>
+				<p class="lede">
+					An OpenWebUI-first, camera-aware companion for Reachy Mini. Use OpenWebUI workspaces/models for personality and voice behavior, with VAD listening without a wake word.
+				</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>OpenWebUI model dropdown</span>
+					<span>OpenWebUI-managed TTS</span>
+					<span>No-wake-word VAD</span>
+					<span>Workspace-managed personalities</span>
+				</div>
+			</div>
+			<div class="hero-visual">
+				<div class="glass-card">
+					<img src="docs/assets/reachy_mini_dance.gif" alt="Reachy Mini dancing" class="hero-gif">
+					<p class="caption">Reachy Mini can move, dance, and emote while holding a natural conversation.</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 conversational layer for your robot</h2>
+			<p class="intro">
+				The app blends local speech, vision, and motion so Reachy Mini feels present.
+			</p>
+		</div>
+		<div class="feature-grid">
+			<div class="feature-card">
+				<span class="icon">🎤</span>
+				<h3>Natural voice chat</h3>
+				<p>Talk freely and get replies from your configured local chat-completions model.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🎥</span>
+				<h3>Vision-aware replies</h3>
+				<p>Ask the camera tool to see what’s in front, track a face, or keep attention on whoever is speaking.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">💃</span>
+				<h3>Expressive motion</h3>
+				<p>Queue dances, play recorded emotions while Reachy listens and talks.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🧠</span>
+				<h3>Personalities on demand</h3>
+				<p>Switch conversation styles in OpenWebUI workspaces/models while the bot exposes tools like dance, camera, and tracking.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🌐</span>
+				<h3>Ready for your setup</h3>
+				<p>Works with wired or wireless Reachy Mini, and can run vision locally or through the default cloud model.</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 hello to helpful in seconds</h3>
+				<ul class="story-list">
+					<li><span>👋</span> Say “Hey Reachy” and start chatting—no extra setup in the moment.</li>
+					<li><span>👀</span> Ask what it sees; it can peek through the camera or keep focus on your face.</li>
+					<li><span>🎭</span> Trigger emotions or dance breaks to keep the conversation lively.</li>
+					<li><span>📝</span> Follow along with live transcripts in the web UI or run audio-only from the console.</li>
+				</ul>
+			</div>
+			<div class="story-card secondary">
+				<p class="eyebrow">Where it shines</p>
+				<h3>Great for demos, teaching, and playful exploration</h3>
+				<p class="story-text">
+					Show off how Reachy Mini listens, responds, and moves in sync. Whether you’re guiding a class, hosting a booth, or experimenting at home, the app keeps the robot expressive without juggling scripts or joystick controls.
+				</p>
+				<div class="chips">
+					<span class="chip">Live conversation</span>
+					<span class="chip">Face tracking</span>
+					<span class="chip">Camera tool</span>
+					<span class="chip">Dance library</span>
+					<span class="chip">Profiles & tools</span>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<footer class="footer">
+		<p>
+			Reachy Mini Conversation OpenWebUI, based on the Reachy Mini app ecosystem.
+			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>

pyproject.toml

@@ -0,0 +1,150 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "Reachy_OpenWebUI"
+version = "0.6.4.86"
+authors = [{ name = "Jacid23" }]
+description = "OpenWebUI-first Reachy Mini conversation app using OpenWebUI-managed STT, chat, workspace tools, and TTS."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    #Media
+    "av",
+    "aiortc>=1.13.0",
+    "fastrtc>=0.0.34",
+    "gradio==5.50.1.dev1",
+    "huggingface-hub==1.3.0",
+    "httpx",
+    "numpy",
+    "onnxruntime",
+    "opencv-python>=4.12.0.88",
+    "zxing-cpp>=2.3.0",
+
+    #Environment variables
+    "python-dotenv",
+
+    # Client library used for local Ollama/vLLM/OpenWebUI chat endpoints
+    "openai>=2.30.0",
+
+    #Reachy mini
+    "reachy_mini_dances_library",
+    "reachy_mini_toolbox",
+    "reachy-mini>=1.7.1",
+    "gradio_client>=1.13.3",
+
+    #Required at import/runtime by camera_worker, local audio, and local pipeline
+    "scipy",
+
+    #OpenWebUI pipeline (VAD/audio upload/chat/TTS). Torch/Silero are optional at runtime
+    # because Reachy's shared venv already owns torch, and fresh torch pulls can
+    # drag in giant CUDA/triton wheels.
+    "soundfile",
+    "setuptools<82",
+]
+
+[project.optional-dependencies]
+local_vision = [
+  "accelerate>=1.13.0; platform_machine != 'aarch64' and platform_machine != 'arm64'",
+  "torch>=2.1; platform_machine != 'aarch64' and platform_machine != 'arm64'",
+  "transformers==5.3.0; platform_machine != 'aarch64' and platform_machine != 'arm64'",
+  "num2words",
+]
+
+[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.scripts]
+reachy-mini-conversation-app-openwebui = "Reachy_OpenWebUI.main:main"
+
+[tool.uv]
+dependency-metadata = [
+    # Upstream metadata currently marks `gstreamer-msvc-runtime` as unconditional.
+    # It should only be required on Windows. Temp fix.
+    { name = "gstreamer-libs", version = "1.28.1", requires-dist = ["gstreamer-msvc-runtime; sys_platform == 'win32'", "setuptools"] },
+]
+
+[project.entry-points."reachy_mini_apps"]
+Reachy_OpenWebUI = "Reachy_OpenWebUI.main:ReachyMiniConversationOpenWebUIApp"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+Reachy_OpenWebUI = [
+  "images/*",
+  "static/*",
+  "static/assets/*",
+  "sub_apps/cookAIware/data/*.json",
+  "sub_apps/cookAIware/profiles/**/*.txt",
+  "sub_apps/cookAIware/profiles/**/*.py",
+  ".env.example",
+  "demos/**/*.txt",
+  "profiles/**/*.txt",
+  "profiles/**/*.py",
+]
+reachy_talk_data = [
+  "profiles/**/*.txt",
+  "profiles/**/*.py",
+]
+
+[tool.ruff]
+line-length = 119
+exclude = [".venv", "dist", "build", "**/__pycache__", "*.egg-info", ".mypy_cache", ".pytest_cache"]
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "F",   # pyflakes
+  "W",   # pycodestyle warnings
+  "I",   # isort
+  "C4",  # flake8-comprehensions
+  "D",   # pydocstyle
+]
+ignore = [
+  "E501",  # handled by formatter
+  "D100",  # ignore missing module docstrings
+  "D203",  # blank line before class docstring (conflicts with D211)
+  "D213",  # summary on second line (conflicts with D212)
+]
+
+[tool.ruff.lint.isort]
+length-sort = true
+lines-after-imports = 2
+no-lines-before = ["standard-library", "local-folder"]
+known-local-folder = ["Reachy_OpenWebUI"]
+known-first-party = ["reachy_mini", "reachy_mini_dances_library", "reachy_mini_toolbox"]
+split-on-trailing-comma = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src/"]
+ignore_missing_imports = true
+strict = true
+show_error_codes = true
+warn_unused_ignores = true
+
+
+
+
+
+

requirements.txt

@@ -0,0 +1 @@
+# Hugging Face Spaces provides Gradio from the README Space SDK config.

setup.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+from shutil import copytree
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+
+
+PROJECT_ROOT = Path(__file__).parent.resolve()
+SOURCE_PROFILES_DIR = PROJECT_ROOT / "src" / "Reachy_OpenWebUI" / "profiles"
+TARGET_PACKAGE = "reachy_talk_data"
+TARGET_SUBDIR = "profiles"
+
+
+class BuildPyWithProfiles(build_py):
+    """Copy built-in profiles into the wheel data package at build time."""
+
+    def run(self) -> None:
+        """Build Python modules, then copy root-level profiles into reachy_talk_data."""
+        super().run()
+
+        target_root = Path(self.build_lib) / TARGET_PACKAGE / TARGET_SUBDIR
+        copytree(SOURCE_PROFILES_DIR, target_root, dirs_exist_ok=True)
+
+
+setup(
+    cmdclass={"build_py": BuildPyWithProfiles},
+)

src/Reachy_OpenWebUI/.env.example

@@ -0,0 +1,44 @@
+# =============================================================================
+# LLM Configuration (Judgy Reachy local OpenWebUI)
+# =============================================================================
+# OpenWebUI native API base. The client posts to /api/chat/completions.
+OPENWEBUI_URL="http://localhost:3001/api"
+
+# Model name as known by your LLM server
+OPENWEBUI_MODEL="reachy-convo"
+
+# API key for your LLM server. Leave as ollama unless OpenWebUI auth is enabled.
+OPENWEBUI_API_KEY="ollama"
+
+# =============================================================================
+# Speech-to-Text
+# =============================================================================
+# Faster-Whisper model size: tiny.en, small.en, medium.en, large-v3
+LOCAL_STT_MODEL="small.en"
+
+# Digital gain applied to microphone input (e.g., 2.0 to double volume)
+MIC_GAIN=1.0
+
+# No-wake-word VAD tuning. Each chunk is about 32 ms at 16 kHz.
+VAD_THRESHOLD=0.50
+VAD_FALLBACK_THRESHOLD=0.012
+VAD_SPEECH_ONSET_CHUNKS=4
+VAD_SILENCE_END_CHUNKS=55
+VAD_MIN_SPEECH_CHUNKS=10
+WEBRTC_VAD_AGGRESSIVENESS=2
+SILERO_VAD_ONNX_PATH=
+
+
+# =============================================================================
+# Vision
+# =============================================================================
+# Local vision model (only used with --smolvlm CLI flag)
+LOCAL_VISION_MODEL=HuggingFaceTB/SmolVLM2-2.2B-Instruct
+
+# Cache directory for downloaded models
+HF_HOME=./cache
+
+# Hugging Face token (optional, falls back to `hf auth login`)
+HF_TOKEN=
+
+

src/Reachy_OpenWebUI/__init__.py

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

src/Reachy_OpenWebUI/__pycache__/console.cpython-311.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:385ef54b921814f767d47368f47749120f1eb632ecbe9929f196b06547d1a1a3
+size 149921

src/Reachy_OpenWebUI/app_profiles.py

@@ -0,0 +1,62 @@
+"""Profile source registry for app-owned tool and profile files.
+
+Shared loaders should ask this module where a profile lives instead of hardcoding
+mini-app package names in core runtime code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_PROFILE = "default"
+COOKAIWARE_PROFILE = "cookaiware"
+
+
+@dataclass(frozen=True)
+class ToolProfileSource:
+    """Locations used to load a profile's tool list and tool modules."""
+
+    profile: str
+    profile_path: Path
+    profile_package: str
+    shared_tool_packages: tuple[str, ...]
+
+    @property
+    def tools_txt_path(self) -> Path:
+        return self.profile_path / "tools.txt"
+
+
+_PACKAGE_ROOT = Path(__file__).parent
+
+_PROFILE_SOURCES: dict[str, ToolProfileSource] = {
+    DEFAULT_PROFILE: ToolProfileSource(
+        profile=DEFAULT_PROFILE,
+        profile_path=_PACKAGE_ROOT / "profiles" / DEFAULT_PROFILE,
+        profile_package="Reachy_OpenWebUI.profiles.default",
+        shared_tool_packages=("Reachy_OpenWebUI.tools",),
+    ),
+    COOKAIWARE_PROFILE: ToolProfileSource(
+        profile=COOKAIWARE_PROFILE,
+        profile_path=_PACKAGE_ROOT / "sub_apps" / "cookAIware" / "profiles" / COOKAIWARE_PROFILE,
+        profile_package="Reachy_OpenWebUI.sub_apps.cookAIware.profiles.cookaiware",
+        shared_tool_packages=("Reachy_OpenWebUI.sub_apps.cookAIware.tools",),
+    ),
+}
+
+
+def resolve_tool_profile_source(profile: str | None) -> ToolProfileSource:
+    """Return the registered tool/profile source for the selected mode."""
+    selected = (profile or DEFAULT_PROFILE).strip() or DEFAULT_PROFILE
+    return _PROFILE_SOURCES.get(selected) or ToolProfileSource(
+        profile=selected,
+        profile_path=_PACKAGE_ROOT / "profiles" / selected,
+        profile_package=f"Reachy_OpenWebUI.profiles.{selected}",
+        shared_tool_packages=("Reachy_OpenWebUI.tools",),
+    )
+
+
+def registered_tool_profiles() -> tuple[str, ...]:
+    """Return known profile ids for settings/status UIs."""
+    return tuple(_PROFILE_SOURCES)

src/Reachy_OpenWebUI/audio/__init__.py

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

src/Reachy_OpenWebUI/audio/attitude_wobbler.py

@@ -0,0 +1,243 @@
+"""Per-attitude speech wobble — extends HeadWobbler with axis-specific scaling and offsets.
+
+Originals (speech_tapper.py, head_wobbler.py) are untouched.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+import queue
+import logging
+import threading
+from typing import Tuple
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from Reachy_OpenWebUI.audio.speech_tapper import SwayRollRT, HOP_MS
+from Reachy_OpenWebUI.sub_apps.attitudes import AttitudeProfile, resolve_attitude
+
+
+SAMPLE_RATE = 24000
+MOVEMENT_LATENCY_S = 0.2
+logger = logging.getLogger(__name__)
+
+
+class AttitudeSwayRT(SwayRollRT):
+    """SwayRollRT that also exposes the speech envelope in each hop dict."""
+
+    def feed(self, pcm, sr=None):
+        results = super().feed(pcm, sr)
+        for r in results:
+            r["env"] = self.sway_env
+        return results
+
+
+class AttitudeHeadWobbler:
+    """HeadWobbler with per-attitude axis scales and speech-time pose offsets.
+
+    Drop-in replacement: same public API as HeadWobbler.
+    """
+
+    def __init__(
+        self,
+        set_speech_offsets: Callable[[Tuple[float, float, float, float, float, float]], None],
+        attitude: str = "calm",
+    ) -> None:
+        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 = AttitudeSwayRT()
+
+        self._state_lock = threading.Lock()
+        self._sway_lock = threading.Lock()
+        self._generation = 0
+
+        profile = resolve_attitude(attitude)
+        self._scale = profile.speaking_motion_scale
+        self._pitch_scale = profile.speaking_pitch_scale
+        self._yaw_scale = profile.speaking_yaw_scale
+        self._roll_scale = profile.speaking_roll_scale
+        self._x_scale = profile.speaking_x_scale
+        self._y_scale = profile.speaking_y_scale
+        self._z_scale = profile.speaking_z_scale
+        self._pitch_offset = math.radians(profile.speaking_pitch_offset_deg)
+        self._z_offset = profile.speaking_z_offset_m
+
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def feed(self, delta_b64: str) -> None:
+        import base64
+        buf = np.frombuffer(base64.b64decode(delta_b64), dtype=np.int16)
+        self.feed_pcm(buf, SAMPLE_RATE)
+
+    def feed_pcm(self, pcm: NDArray[np.int16], sample_rate: int = SAMPLE_RATE) -> None:
+        buf = np.asarray(pcm, dtype=np.int16).reshape(1, -1)
+        if buf.size == 0:
+            return
+        with self._state_lock:
+            generation = self._generation
+        self.audio_queue.put((generation, int(sample_rate or SAMPLE_RATE), buf))
+
+    def start(self) -> None:
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self.working_loop, daemon=True)
+        self._thread.start()
+        logger.debug("Attitude head wobbler started")
+
+    def set_attitude(self, attitude: str) -> None:
+        profile = resolve_attitude(attitude)
+        with self._state_lock:
+            self._scale = profile.speaking_motion_scale
+            self._pitch_scale = profile.speaking_pitch_scale
+            self._yaw_scale = profile.speaking_yaw_scale
+            self._roll_scale = profile.speaking_roll_scale
+            self._x_scale = profile.speaking_x_scale
+            self._y_scale = profile.speaking_y_scale
+            self._z_scale = profile.speaking_z_scale
+            self._pitch_offset = math.radians(profile.speaking_pitch_offset_deg)
+            self._z_offset = profile.speaking_z_offset_m
+        logger.info(
+            "Speech attitude set to %s (scale=%.2f, pitch_off=%.1f°, z_off=%.3fm)",
+            profile.name, profile.speaking_motion_scale,
+            profile.speaking_pitch_offset_deg, profile.speaking_z_offset_m,
+        )
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join()
+        logger.debug("Attitude head wobbler stopped")
+
+    def working_loop(self) -> None:
+        hop_dt = HOP_MS / 1000.0
+
+        logger.debug("Attitude 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()
+            except queue.Empty:
+                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]
+                    with self._state_lock:
+                        if self._generation != current_generation:
+                            break
+                        scale = self._scale
+                        ps = self._pitch_scale
+                        ys = self._yaw_scale
+                        rs = self._roll_scale
+                        xs = self._x_scale
+                        y_s = self._y_scale
+                        zs = self._z_scale
+                        p_off = self._pitch_offset
+                        z_off = self._z_offset
+
+                    env = r.get("env", 1.0)
+
+                    offsets = (
+                        (r["x_mm"] / 1000.0) * scale * xs,
+                        (r["y_mm"] / 1000.0) * scale * y_s,
+                        (r["z_mm"] / 1000.0) * scale * zs + env * z_off,
+                        r["roll_rad"] * scale * rs,
+                        r["pitch_rad"] * scale * ps + env * p_off,
+                        r["yaw_rad"] * scale * ys,
+                    )
+
+                    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("Attitude head wobbler thread exited")
+
+    def drain_audio_queue(self) -> None:
+        self._drain_audio_queue()
+
+    def _drain_audio_queue(self) -> bool:
+        drained_any = False
+        try:
+            while True:
+                self.audio_queue.get_nowait()
+                self.audio_queue.task_done()
+                drained_any = True
+        except queue.Empty:
+            return drained_any
+
+    def reset(self) -> None:
+        with self._state_lock:
+            self._generation += 1
+            self._base_ts = None
+            self._hops_done = 0
+
+        drained_any = self._drain_audio_queue()
+
+        with self._sway_lock:
+            self.sway.reset()
+
+        self._apply_offsets((0.0, 0.0, 0.0, 0.0, 0.0, 0.0))
+
+        if drained_any:
+            logger.debug("Attitude head wobbler queue drained during reset")

src/Reachy_OpenWebUI/audio/head_wobbler.py

@@ -0,0 +1,205 @@
+"""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_OpenWebUI.audio.speech_tapper import HOP_MS, SwayRollRT
+from Reachy_OpenWebUI.sub_apps.attitudes import resolve_attitude
+
+
+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],
+        attitude: str = "calm",
+    ) -> 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._speech_motion_scale = resolve_attitude(attitude).speaking_motion_scale
+
+        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)
+        self.feed_pcm(buf, SAMPLE_RATE)
+
+    def feed_pcm(self, pcm: NDArray[np.int16], sample_rate: int = SAMPLE_RATE) -> None:
+        """Thread-safe: push raw mono PCM into the consumer queue."""
+        buf = np.asarray(pcm, dtype=np.int16).reshape(1, -1)
+        if buf.size == 0:
+            return
+        with self._state_lock:
+            generation = self._generation
+        self.audio_queue.put((generation, int(sample_rate or 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 set_attitude(self, attitude: str) -> None:
+        """Apply the selected attitude's speech movement scale."""
+        profile = resolve_attitude(attitude)
+        with self._state_lock:
+            self._speech_motion_scale = profile.speaking_motion_scale
+        logger.info("Speech motion attitude set to %s (scale %.2f)", profile.name, profile.speaking_motion_scale)
+
+    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]
+                    with self._state_lock:
+                        if self._generation != current_generation:
+                            break
+                        scale = self._speech_motion_scale
+
+                    offsets = (
+                        (r["x_mm"] / 1000.0) * scale,
+                        (r["y_mm"] / 1000.0) * scale,
+                        (r["z_mm"] / 1000.0) * scale,
+                        r["roll_rad"] * scale,
+                        r["pitch_rad"] * scale,
+                        r["yaw_rad"] * scale,
+                    )
+
+                    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."""
+        self._drain_audio_queue()
+
+    def _drain_audio_queue(self) -> bool:
+        """Empty queued audio chunks and return whether anything was drained."""
+        drained_any = False
+        try:
+            while True:
+                self.audio_queue.get_nowait()
+                self.audio_queue.task_done()
+                drained_any = True
+        except queue.Empty:
+            return drained_any
+
+    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 = self._drain_audio_queue()
+
+        with self._sway_lock:
+            self.sway.reset()
+
+        self._apply_offsets((0.0, 0.0, 0.0, 0.0, 0.0, 0.0))
+
+        if drained_any:
+            logger.debug("Head wobbler queue drained during reset")

src/Reachy_OpenWebUI/audio/speech_tapper.py

@@ -0,0 +1,274 @@
+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
+
+# Speech wobble oscillator amplitudes and frequencies.
+# NOTE: The head is world-stabilised (gaze-locked like a gimbal).  Yaw
+# directly shifts where the robot looks — even small values make it glance
+# away from the user.  Pitch (nodding) and roll (tilting) are far less
+# disruptive to gaze.  Keep yaw the SMALLEST amplitude, not the largest.
+# Per-attitude overrides live in AttitudeHeadWobbler (attitude_wobbler.py).
+SWAY_F_PITCH = 2.2
+SWAY_A_PITCH_DEG = 4.5
+SWAY_F_YAW = 0.6
+SWAY_A_YAW_DEG = 7.5      # WARNING: large — shifts gaze noticeably
+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_OpenWebUI/audio/startup_config.py

@@ -0,0 +1,68 @@
+"""Startup configuration for the Reachy Mini XVF3800 audio processor.
+
+Ported from the official reachy_mini_conversation_app. Applied at every
+pipeline start so the mic chain recovers from drifted/stuck AGC state.
+"""
+
+from __future__ import annotations
+import logging
+from collections.abc import Sequence
+
+
+AudioControlValue = float | int
+AudioStartupParameter = tuple[str, tuple[AudioControlValue, ...]]
+WRITE_SETTLE_SECONDS = 0.1
+
+AUDIO_STARTUP_CONFIG: tuple[AudioStartupParameter, ...] = (
+    ("PP_AGCMAXGAIN", (10.0,)),
+    ("PP_MIN_NS", (0.8,)),
+    ("PP_MIN_NN", (0.8,)),
+    ("PP_GAMMA_E", (0.5,)),
+    ("PP_GAMMA_ETAIL", (0.5,)),
+    ("PP_NLATTENONOFF", (0,)),
+    ("PP_MGSCALE", (4.0, 1.0, 1.0)),
+)
+
+
+def apply_audio_startup_config(
+    robot: object,
+    *,
+    logger: logging.Logger | None = None,
+    verify: bool = True,
+    write_settle_seconds: float = WRITE_SETTLE_SECONDS,
+) -> bool:
+    """Apply the tuned XVF3800 audio configuration for the conversation app."""
+    log = logger or logging.getLogger(__name__)
+    audio = getattr(getattr(robot, "media", None), "audio", None)
+
+    if audio is None:
+        log.warning("Skipping Reachy audio startup config: robot media audio is unavailable.")
+        return False
+
+    apply_audio_config = getattr(audio, "apply_audio_config", None)
+    if not callable(apply_audio_config):
+        log.warning("Skipping Reachy audio startup config: SDK audio config API is unavailable.")
+        return False
+
+    try:
+        applied = bool(
+            apply_audio_config(
+                AUDIO_STARTUP_CONFIG,
+                verify=verify,
+                write_settle_seconds=write_settle_seconds,
+            )
+        )
+    except Exception as exc:
+        log.warning("Skipping Reachy audio startup config: SDK audio config failed: %s", exc)
+        return False
+
+    if applied:
+        log.info("Applied Reachy audio startup config: %s", _format_config(AUDIO_STARTUP_CONFIG))
+    else:
+        log.warning("Reachy audio startup config was not applied.")
+
+    return applied
+
+
+def _format_config(config: Sequence[AudioStartupParameter]) -> str:
+    return ", ".join(f"{name}={' '.join(str(value) for value in values)}" for name, values in config)

src/Reachy_OpenWebUI/camera_frame_encoding.py

@@ -0,0 +1,27 @@
+"""Helpers for encoding camera frames."""
+
+from fractions import Fraction
+
+import av
+import numpy as np
+from numpy.typing import NDArray
+
+
+def encode_bgr_frame_as_jpeg(frame: NDArray[np.uint8]) -> bytes:
+    """Encode a BGR camera frame as JPEG bytes."""
+    rgb_frame = np.ascontiguousarray(frame[..., ::-1])
+    video_frame = av.VideoFrame.from_ndarray(rgb_frame, format="rgb24")
+
+    codec = av.CodecContext.create("mjpeg", "w")
+    codec.width = rgb_frame.shape[1]  # type: ignore[attr-defined]
+    codec.height = rgb_frame.shape[0]  # type: ignore[attr-defined]
+    codec.pix_fmt = "yuvj444p"  # type: ignore[attr-defined]
+    codec.time_base = Fraction(1, 1)
+    codec.options = {"qscale": "3"}
+
+    packets = codec.encode(video_frame)  # type: ignore[attr-defined]
+    packets += codec.encode(None)  # type: ignore[attr-defined]
+    if not packets:
+        raise RuntimeError("Failed to encode frame as JPEG")
+
+    return b"".join(bytes(packet) for packet in packets)

src/Reachy_OpenWebUI/camera_worker.py

@@ -0,0 +1,78 @@
+"""Camera worker thread with frame buffering.
+
+Provides:
+- 30Hz+ camera polling with thread-safe frame buffering
+- Latest frame always available for tools
+"""
+
+import time
+import logging
+import threading
+
+import numpy as np
+from numpy.typing import NDArray
+
+from reachy_mini import ReachyMini
+
+
+logger = logging.getLogger(__name__)
+
+
+class CameraWorker:
+    """Thread-safe camera worker with frame buffering."""
+
+    def __init__(self, reachy_mini: ReachyMini) -> None:
+        """Initialize."""
+        self.reachy_mini = reachy_mini
+
+        # 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
+
+    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 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:
+        """Poll frames from the camera and store the latest one."""
+        logger.debug("Starting camera working loop")
+
+        while not self._stop_event.is_set():
+            try:
+                # 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
+
+                # Small sleep to prevent excessive CPU usage
+                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_OpenWebUI/config.py

@@ -0,0 +1,145 @@
+import os
+import logging
+from pathlib import Path
+
+from dotenv import find_dotenv, load_dotenv
+
+from Reachy_OpenWebUI import settings_keys as keys
+
+
+logger = logging.getLogger(__name__)
+
+STABLE_ENV_PATH = Path.home() / ".config" / "settings" / ".env"
+
+
+def _truthy(value: str | None, default: bool = False) -> bool:
+    raw = (value or "").strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+if STABLE_ENV_PATH.exists():
+    load_dotenv(dotenv_path=str(STABLE_ENV_PATH), override=True)
+    logger.info("Stable OpenWebUI configuration loaded from %s", STABLE_ENV_PATH)
+
+# Locate .env file (search upward from current working directory)
+dotenv_path = find_dotenv(usecwd=True)
+
+if dotenv_path:
+    # Load .env but don't override existing environment variables (CLI takes precedence)
+    load_dotenv(dotenv_path=dotenv_path, override=False)
+    logger.info(f"Configuration loaded from {dotenv_path}")
+else:
+    logger.warning("No .env file found, using environment variables")
+
+
+class Config:
+    """Configuration class for the conversation app."""
+
+    # Optional
+    HF_HOME = os.getenv("HF_HOME", "./cache")
+    OPENWEBUI_MODEL = (
+        os.getenv(keys.OPENWEB_LOADED_LLM)
+        or os.getenv(keys.LEGACY_OPENWEB_MODEL)
+        or os.getenv(keys.LEGACY_LOCAL_LLM_MODEL)
+        or "reachy-convo"
+    )
+    OPENWEBUI_URL = (
+        os.getenv(keys.OPENWEBUI_URL)
+        or os.getenv(keys.LEGACY_LOCAL_LLM_URL)
+        or "http://localhost:3001"
+    )
+    OPENWEBUI_API_KEY = (
+        os.getenv(keys.OPENWEBUI_API_KEY)
+        or os.getenv(keys.LEGACY_LOCAL_LLM_API_KEY)
+        or ""
+    )
+    OPENWEBUI_TOKEN = (
+        os.getenv(keys.OPENWEBUI_TOKEN)
+        or os.getenv(keys.LEGACY_OPENWEBUI_TOKEN)
+        or ""
+    )
+    OPENWEBUI_USER_AGENT = (
+        os.getenv(keys.OPENWEBUI_USER_AGENT)
+        or "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36"
+    ).strip()
+    OPENWEBUI_CHAT_ID = (
+        os.getenv(keys.OPENWEBUI_CHAT_ID)
+        or ""
+    ).strip()
+    OPENWEBUI_CHAT_WINDOW_START = (
+        os.getenv(keys.OPENWEBUI_CHAT_WINDOW_START)
+        or ""
+    ).strip()
+    OPENWEBUI_CHAT_PENDING_REASON = (
+        os.getenv(keys.OPENWEBUI_CHAT_PENDING_REASON)
+        or ""
+    ).strip()
+    OPENWEBUI_CHAT_PENDING_EVENT_ID = (
+        os.getenv(keys.OPENWEBUI_CHAT_PENDING_EVENT_ID)
+        or ""
+    ).strip()
+    OPENWEBUI_USER_ID = os.getenv(keys.OPENWEBUI_USER_ID, "").strip()
+    OPENWEBUI_USER_NAME = os.getenv(keys.OPENWEBUI_USER_NAME, "Reachy").strip()
+    OPENWEBUI_USER_EMAIL = os.getenv(keys.OPENWEBUI_USER_EMAIL, "reachy@example.local").strip()
+    OPENWEBUI_USER_LANGUAGE = os.getenv(keys.OPENWEBUI_USER_LANGUAGE, "en-US").strip()
+    OPENWEBUI_USER_LOCATION = os.getenv(keys.OPENWEBUI_USER_LOCATION, "Unknown").strip()
+    OPENWEBUI_USER_TIMEZONE = os.getenv(keys.OPENWEBUI_USER_TIMEZONE, "America/New_York").strip()
+    OPENWEBUI_CONTACTS_REQUIRE_VISION = _truthy(os.getenv(keys.OPENWEBUI_CONTACTS_REQUIRE_VISION), default=True)
+    OPENWEBUI_ENABLED_TOOLS = os.getenv(keys.OPENWEBUI_ENABLED_TOOLS, "").strip()
+    REACHY_MINI_CUSTOM_PROFILE = os.getenv(keys.REACHY_MINI_CUSTOM_PROFILE, "").strip()
+    REACHY_IDLE_ATTITUDE = os.getenv(keys.REACHY_IDLE_ATTITUDE, "calm").strip() or "calm"
+    WEATHER_POSTAL_CODE = os.getenv(keys.WEATHER_POSTAL_CODE, "").strip()
+    OPENWEBUI_TTS_READ_TIMEOUT = float(os.getenv("OPENWEBUI_TTS_READ_TIMEOUT", "") or "15.0")
+    HF_TOKEN = os.getenv("HF_TOKEN")  # Optional, falls back to hf auth login if not set
+
+    logger.debug(f"HF_HOME: {HF_HOME}, LLM Model: {OPENWEBUI_MODEL}")
+
+
+
+
+    # Audio Settings
+    MIC_GAIN = float(os.getenv(keys.MIC_GAIN, "") or "1.0")
+    LOCAL_DEV_VISION_MODEL = (
+        os.getenv(keys.LOCAL_DEV_VISION_MODEL)
+        or os.getenv(keys.LEGACY_LOCAL_VISION_MODEL)
+        or "HuggingFaceTB/SmolVLM2-2.2B-Instruct"
+    )
+    VAD_THRESHOLD = float(os.getenv("VAD_THRESHOLD", "") or "0.12")
+    VAD_FALLBACK_THRESHOLD = float(os.getenv("VAD_FALLBACK_THRESHOLD", "") or "0.010")
+    VAD_SPEECH_ONSET_CHUNKS = int(os.getenv("VAD_SPEECH_ONSET_CHUNKS", "") or "2")
+    VAD_SILENCE_END_CHUNKS = int(os.getenv("VAD_SILENCE_END_CHUNKS", "") or "70")
+    VAD_MIN_SPEECH_CHUNKS = int(os.getenv("VAD_MIN_SPEECH_CHUNKS", "") or "8")
+    SILERO_VAD_ONNX_PATH = os.getenv(
+        "SILERO_VAD_ONNX_PATH",
+        str(Path.home() / ".cache" / "reachy-openwebui-vad" / "silero_vad.onnx"),
+    )
+    OPENWEBUI_CONVERSATION_IDLE_RESET_SECONDS = int(
+        os.getenv("OPENWEBUI_CONVERSATION_IDLE_RESET_SECONDS", "0")
+    )
+
+
+
+config = Config()
+
+
+def active_profile(default: str = "default") -> str:
+    """Return the selected profile, falling back to the normal conversation profile."""
+    profile = (config.REACHY_MINI_CUSTOM_PROFILE or os.getenv(keys.REACHY_MINI_CUSTOM_PROFILE, "")).strip()
+    return profile or default
+
+
+def set_runtime_mode(profile: str | None = None, model: str | None = None) -> None:
+    """Set mode-specific runtime values before app-specific modules initialize."""
+    selected_profile = (profile or "").strip()
+    config.REACHY_MINI_CUSTOM_PROFILE = selected_profile
+    if selected_profile:
+        os.environ[keys.REACHY_MINI_CUSTOM_PROFILE] = selected_profile
+    else:
+        os.environ.pop(keys.REACHY_MINI_CUSTOM_PROFILE, None)
+
+    selected_model = (model or "").strip()
+    if selected_model:
+        config.OPENWEBUI_MODEL = selected_model
+        os.environ[keys.OPENWEB_LOADED_LLM] = selected_model

src/Reachy_OpenWebUI/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):
+    """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):
+    """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):
+    """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)