Initial commit

.env.example

@@ -0,0 +1,2 @@
+CLAWDBOT_TOKEN="PUT YOUR CLAWDBOT TOKEN HERE"
+ELEVENLABS_API_KEY="PUT YOUR ELEVENLABS API KEY HERE"

.gitignore

@@ -0,0 +1,7 @@
+.venv/
+*.egg-info/
+*.code-workspace
+.env
+build/
+dist/
+__pycache__/

.python-version

@@ -0,0 +1 @@
+3.12

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,212 @@
+---
+title: Moltbot Body
+emoji: 🤖
+colorFrom: green
+colorTo: blue
+sdk: static
+pinned: false
+short_description: Give Moltbot a physical presence with Reachy Mini
+tags:
+ - reachy_mini
+ - reachy_mini_python_app
+ - clawdbot
+ - moltbot
+---
+
+# Moltbot's Body
+
+> **Security Warning**: This project uses Moltbot, which runs AI-generated code with access to your system. Ensure you understand the security implications before installation. Only run Moltbot from trusted sources and review its permissions carefully. See the [Moltbot Security documentation](https://docs.molt.bot/gateway/security) for details.
+
+Reachy Mini integration with Moltbot — giving Moltbot a physical presence.
+
+## What is Moltbot?
+
+[Moltbot](https://docs.molt.bot/start/getting-started) is an AI assistant platform that can connect to various chat surfaces (WhatsApp, Telegram, Discord, etc.) and execute tasks autonomously. This project extends Moltbot by giving it a physical robot body using [Reachy Mini](https://huggingface.co/spaces/pollen-robotics/Reachy_Mini), a small expressive robot from Pollen Robotics.
+
+With this integration, Moltbot can:
+- Listen to speech via the robot's microphone
+- Transcribe speech locally using Whisper
+- Generate responses through the Moltbot gateway
+- Speak responses through ElevenLabs TTS
+- Move its head expressively while speaking
+
+## Architecture
+
+```
+Microphone → VAD → Whisper STT → Moltbot Gateway → ElevenLabs TTS → Speaker
+                                        ↓
+                                   MovementManager
+                                   HeadWobbler (speech-driven head movement)
+```
+
+## Prerequisites
+
+Before running this project, you need:
+
+### 1. Moltbot Gateway (Required)
+
+Moltbot must be installed and the gateway must be running. Follow the [Moltbot Getting Started guide](https://docs.molt.bot/start/getting-started) to:
+
+1. Install the CLI: `curl -fsSL https://molt.bot/install.sh | bash`
+2. Run the onboarding wizard: `moltbot onboard --install-daemon`
+3. Start the gateway: `moltbot gateway --port 18789`
+
+Verify it's running:
+```bash
+moltbot gateway status
+```
+
+### 2. Reachy Mini Robot (Required)
+
+You need a [Reachy Mini](https://huggingface.co/spaces/pollen-robotics/Reachy_Mini) robot from Pollen Robotics with its daemon running.
+
+Verify the daemon is running:
+```bash
+curl -s http://localhost:8000/api/daemon/status | jq .state
+```
+
+### 3. ElevenLabs Account (Required)
+
+Sign up at [ElevenLabs](https://elevenlabs.io/) and get an API key for text-to-speech.
+
+### 4. Python 3.12+ and uv
+
+This project requires Python 3.12 or later and uses [uv](https://docs.astral.sh/uv/) for package management.
+
+## Setup
+
+```bash
+git clone <this-repo>
+cd reachy
+uv sync
+```
+
+### Environment Variables
+
+Create a `.env` file:
+
+```bash
+CLAWDBOT_TOKEN=your_gateway_token
+ELEVENLABS_API_KEY=your_elevenlabs_key
+```
+
+Get your gateway token from the Moltbot configuration, or these will be pulled from the Moltbot config automatically if not set.
+
+## Running
+
+```bash
+# Make sure Reachy Mini daemon is running
+curl -s http://localhost:8000/api/daemon/status | jq .state
+
+# Make sure Moltbot gateway is running
+moltbot gateway status
+
+# Start Moltbot's body
+uv run moltbot-body
+```
+
+## CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--debug` | Enable debug logging (verbose output) |
+| `--profile` | Enable timing profiler - prints detailed timing breakdown after each conversation turn |
+| `--profile-once` | Profile one conversation turn then exit (useful for benchmarking) |
+| `--robot-name NAME` | Specify robot name for connection (if you have multiple robots) |
+| `--gateway-url URL` | Moltbot gateway URL (default: `http://localhost:18789`) |
+
+### Examples
+
+```bash
+# Run with debug logging
+uv run moltbot-body --debug
+
+# Profile a single conversation turn
+uv run moltbot-body --profile-once
+
+# Connect to a specific robot and gateway
+uv run moltbot-body --robot-name my-reachy --gateway-url http://192.168.1.100:18789
+```
+
+### Profiling Output
+
+When using `--profile` or `--profile-once`, you'll see a detailed timing breakdown after each turn:
+
+```
+============================================================
+CONVERSATION TIMING PROFILE
+============================================================
+
+📝 User: "Hello, how are you?"
+🤖 Assistant: "I'm doing well, thank you for asking!"
+
+------------------------------------------------------------
+TIMING BREAKDOWN
+------------------------------------------------------------
+
+🎤 Speech Detection:
+   Duration spoken:     1.23s
+
+📜 Whisper Transcription:
+   Time:                0.45s
+
+🧠 LLM (Moltbot):
+   Time to first token: 0.32s
+   Streaming time:      1.15s
+   Total time:          1.47s
+   Tokens:              42 (36.5 tok/s)
+
+🔊 TTS (ElevenLabs):
+   Time to first audio: 0.28s
+   Total streaming:     1.82s
+   Audio chunks:        15
+
+------------------------------------------------------------
+END-TO-END LATENCY
+------------------------------------------------------------
+
+⏱️  Speech end → First audio: 1.05s
+⏱️  Total turn time:          4.50s
+
+============================================================
+```
+
+## Features
+
+- **Voice Activation**: Listens for speech, processes when silence detected
+- **Whisper STT**: Local speech-to-text transcription using faster-whisper
+- **Moltbot Brain**: Claude-powered responses via the Moltbot gateway API
+- **ElevenLabs TTS**: Natural voice output with streaming
+- **Head Wobble**: Audio-driven head movement while speaking for natural expressiveness
+- **Movement Manager**: 100Hz control loop for smooth robot motion
+- **Breathing Animation**: Gentle idle breathing when not actively engaged
+
+## Tips for a Better Experience
+
+### Use a Low-Latency Inference Provider
+
+For natural, conversational interactions, response latency is critical. The time from when you stop speaking to when the robot starts responding should ideally be under 1 second. 
+
+Consider using a fast inference provider like [Groq](https://groq.com/) which offers extremely low latency for supported models. You can configure this in your Moltbot settings. Use the `--profile` flag to measure your end-to-end latency and identify bottlenecks.
+
+### Let Moltbot Help You Set Up
+
+Since Moltbot is an AI coding assistant, you can chat with it to help configure and customize the robot body! Try asking Moltbot (via any of its chat surfaces) to:
+
+- Help you tune the head movement parameters
+- Adjust the voice activation sensitivity
+- Add new expressions or gestures
+- Debug connection issues
+
+Moltbot can read and modify this codebase, so it's a great collaborator for extending the robot's capabilities.
+
+## Roadmap
+
+- [ ] Face tracking (look at the person speaking)
+- [ ] DoA-based head tracking (direction of arrival for speaker localization)
+- [ ] Wake word detection
+- [ ] Expression gestures
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

index.html

@@ -0,0 +1,143 @@
+<!doctype html>
+<html>
+
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1" />
+	<title>Moltbot Body - Reachy Mini App</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">Moltbot Body</span>
+			</div>
+			<div class="pill">Voice conversation · Moltbot AI · Expressive motion</div>
+		</div>
+		<div class="hero-grid">
+			<div class="hero-copy">
+				<p class="eyebrow">Reachy Mini App</p>
+				<h1>Give Moltbot a physical presence.</h1>
+				<p class="lede">
+					Connect your Moltbot AI assistant to a Reachy Mini robot. Listen through the microphone, transcribe with Whisper, respond through Moltbot, and speak with natural TTS—all while moving expressively.
+				</p>
+				<div class="hero-actions">
+					<a class="btn primary" href="#highlights">Explore features</a>
+					<a class="btn ghost" href="#architecture">See how it works</a>
+				</div>
+				<div class="hero-badges">
+					<span>Local Whisper STT</span>
+					<span>Moltbot Gateway</span>
+					<span>ElevenLabs TTS</span>
+					<span>Expressive head movement</span>
+				</div>
+			</div>
+			<div class="hero-visual">
+				<div class="glass-card">
+					<div class="architecture-preview">
+						<pre>
+Microphone → VAD → Whisper STT
+                      ↓
+              Moltbot Gateway
+                      ↓
+              ElevenLabs TTS → Speaker
+                      ↓
+              MovementManager
+              HeadWobbler
+						</pre>
+					</div>
+					<p class="caption">End-to-end voice conversation pipeline with expressive robot motion.</p>
+				</div>
+			</div>
+		</div>
+	</header>
+
+	<section id="highlights" class="section features">
+		<div class="section-header">
+			<p class="eyebrow">What's inside</p>
+			<h2>A complete voice interface for your robot</h2>
+			<p class="intro">
+				Moltbot Body combines speech recognition, AI conversation, and expressive motion into a seamless experience.
+			</p>
+		</div>
+		<div class="feature-grid">
+			<div class="feature-card">
+				<span class="icon">🎤</span>
+				<h3>Voice activation</h3>
+				<p>Listens continuously and detects when you're speaking using voice activity detection.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">📝</span>
+				<h3>Local transcription</h3>
+				<p>Fast, private speech-to-text using Whisper running locally on your machine.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🧠</span>
+				<h3>Moltbot brain</h3>
+				<p>Claude-powered responses through the Moltbot gateway with full tool access and memory.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🔊</span>
+				<h3>Natural voice</h3>
+				<p>High-quality streaming text-to-speech through ElevenLabs for natural conversation.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">💃</span>
+				<h3>Expressive motion</h3>
+				<p>Audio-driven head wobble and breathing animations bring the robot to life while speaking.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">⚡</span>
+				<h3>Low latency</h3>
+				<p>Optimized pipeline with profiling tools to measure and minimize response time.</p>
+			</div>
+		</div>
+	</section>
+
+	<section id="architecture" class="section story">
+		<div class="story-grid">
+			<div class="story-card">
+				<p class="eyebrow">How it works</p>
+				<h3>From speech to response in under a second</h3>
+				<ul class="story-list">
+					<li><span>🎤</span> Robot microphone captures your voice continuously.</li>
+					<li><span>🔇</span> Voice Activity Detection identifies when you stop speaking.</li>
+					<li><span>📝</span> Whisper transcribes your speech locally and privately.</li>
+					<li><span>🧠</span> Moltbot gateway processes your message with full AI capabilities.</li>
+					<li><span>🔊</span> ElevenLabs streams natural voice output in real-time.</li>
+					<li><span>🤖</span> Head wobbles expressively while the robot speaks.</li>
+				</ul>
+			</div>
+			<div class="story-card secondary">
+				<p class="eyebrow">Prerequisites</p>
+				<h3>What you need to get started</h3>
+				<p class="story-text">
+					This app requires a running Moltbot gateway, an ElevenLabs API key for TTS, and a Reachy Mini robot connected to your network.
+				</p>
+				<div class="chips">
+					<span class="chip">Moltbot Gateway</span>
+					<span class="chip">ElevenLabs API</span>
+					<span class="chip">Reachy Mini</span>
+					<span class="chip">Python 3.12+</span>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<footer class="footer">
+		<p>
+			Moltbot Body — giving Moltbot a physical presence with Reachy Mini.
+			Learn more about <a href="https://docs.molt.bot/" target="_blank" rel="noopener">Moltbot</a> and
+			<a href="https://huggingface.co/spaces/pollen-robotics/Reachy_Mini" target="_blank" rel="noopener">Reachy Mini</a>.
+		</p>
+	</footer>
+
+</body>
+
+</html>

moltbot_body/__init__.py

@@ -0,0 +1,3 @@
+"""Moltbot's physical body - Reachy Mini integration with Clawdbot."""
+
+__version__ = "0.1.0"

moltbot_body/audio/__init__.py

@@ -0,0 +1 @@
+"""Audio processing modules for head movement."""

moltbot_body/audio/head_wobbler.py

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

moltbot_body/audio/speech_tapper.py

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

moltbot_body/clawdbot_handler.py

@@ -0,0 +1,672 @@
+"""Handler that bridges audio I/O with Clawdbot via Whisper STT and ElevenLabs TTS."""
+
+import io
+import os
+import json
+import time
+import base64
+import queue
+import asyncio
+import logging
+import tempfile
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Tuple, Optional, Callable, AsyncIterator
+from pathlib import Path
+
+import httpx
+import numpy as np
+import soundfile as sf
+import websockets
+from httpx_sse import aconnect_sse
+from numpy.typing import NDArray
+from dotenv import load_dotenv, find_dotenv
+
+if TYPE_CHECKING:
+    from moltbot_body.audio.head_wobbler import HeadWobbler
+
+load_dotenv(find_dotenv())
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ConversationTiming:
+    """Tracks timing for a single conversation turn."""
+    
+    # Speech detection
+    speech_start: float = 0.0
+    speech_end: float = 0.0
+    
+    # Transcription
+    transcription_start: float = 0.0
+    transcription_end: float = 0.0
+    
+    # LLM
+    llm_request_start: float = 0.0
+    llm_first_token: float = 0.0
+    llm_last_token: float = 0.0
+    llm_token_count: int = 0
+    
+    # TTS
+    tts_websocket_open: float = 0.0
+    tts_first_audio: float = 0.0
+    tts_last_audio: float = 0.0
+    tts_audio_chunks: int = 0
+    
+    # Overall
+    turn_start: float = 0.0
+    turn_end: float = 0.0
+    
+    # Content
+    user_text: str = ""
+    assistant_text: str = ""
+    
+    def print_summary(self) -> None:
+        """Print a formatted timing summary."""
+        print("\n" + "=" * 60)
+        print("CONVERSATION TIMING PROFILE")
+        print("=" * 60)
+        
+        print(f"\n📝 User: \"{self.user_text[:80]}{'...' if len(self.user_text) > 80 else ''}\"")
+        print(f"🤖 Assistant: \"{self.assistant_text[:80]}{'...' if len(self.assistant_text) > 80 else ''}\"")
+        
+        print("\n" + "-" * 60)
+        print("TIMING BREAKDOWN")
+        print("-" * 60)
+        
+        # Speech duration
+        speech_duration = self.speech_end - self.speech_start if self.speech_end else 0
+        print(f"\n🎤 Speech Detection:")
+        print(f"   Duration spoken:     {speech_duration:.2f}s")
+        
+        # Transcription
+        transcription_time = self.transcription_end - self.transcription_start if self.transcription_end else 0
+        print(f"\n📜 Whisper Transcription:")
+        print(f"   Time:                {transcription_time:.2f}s")
+        
+        # LLM
+        if self.llm_first_token:
+            llm_ttft = self.llm_first_token - self.llm_request_start
+            llm_total = self.llm_last_token - self.llm_request_start if self.llm_last_token else 0
+            llm_streaming = self.llm_last_token - self.llm_first_token if self.llm_last_token else 0
+            tokens_per_sec = self.llm_token_count / llm_streaming if llm_streaming > 0 else 0
+            print(f"\n🧠 LLM (Clawdbot):")
+            print(f"   Time to first token: {llm_ttft:.2f}s")
+            print(f"   Streaming time:      {llm_streaming:.2f}s")
+            print(f"   Total time:          {llm_total:.2f}s")
+            print(f"   Tokens:              {self.llm_token_count} ({tokens_per_sec:.1f} tok/s)")
+        
+        # TTS
+        if self.tts_first_audio:
+            tts_ttfa = self.tts_first_audio - self.tts_websocket_open
+            tts_total = self.tts_last_audio - self.tts_websocket_open if self.tts_last_audio else 0
+            print(f"\n🔊 TTS (ElevenLabs):")
+            print(f"   Time to first audio: {tts_ttfa:.2f}s")
+            print(f"   Total streaming:     {tts_total:.2f}s")
+            print(f"   Audio chunks:        {self.tts_audio_chunks}")
+        
+        # End-to-end
+        print("\n" + "-" * 60)
+        print("END-TO-END LATENCY")
+        print("-" * 60)
+        
+        if self.tts_first_audio and self.speech_end:
+            e2e_to_first_audio = self.tts_first_audio - self.speech_end
+            print(f"\n⏱️  Speech end → First audio: {e2e_to_first_audio:.2f}s")
+        
+        total_turn = self.turn_end - self.turn_start if self.turn_end else 0
+        print(f"⏱️  Total turn time:          {total_turn:.2f}s")
+        
+        print("\n" + "=" * 60 + "\n")
+
+# Audio settings
+SAMPLE_RATE = 16000  # Whisper expects 16kHz
+SILENCE_THRESHOLD = 0.015  # RMS threshold for silence detection
+SILENCE_DURATION = 0.8  # Seconds of silence to end utterance (reduced for responsiveness)
+MIN_SPEECH_DURATION = 0.3  # Minimum speech duration to process
+
+
+class ClawdbotHandler:
+    """Handles the Clawdbot conversation loop with Whisper STT and ElevenLabs TTS."""
+
+    def __init__(
+        self,
+        gateway_url: str = "http://localhost:18789",
+        gateway_token: Optional[str] = None,
+        elevenlabs_api_key: Optional[str] = None,
+        elevenlabs_voice_id: str = "qA5SHJ9UjGlW2QwXWR7w",
+        head_wobbler: Optional["HeadWobbler"] = None,
+        on_listening: Optional[Callable[[], None]] = None,
+        on_thinking: Optional[Callable[[], None]] = None,
+        on_speaking: Optional[Callable[[], None]] = None,
+        profile_mode: bool = False,
+        on_profile_complete: Optional[Callable[[ConversationTiming], None]] = None,
+    ):
+        """Initialize the handler.
+        
+        Args:
+            gateway_url: Clawdbot gateway URL
+            gateway_token: Gateway auth token
+            elevenlabs_api_key: ElevenLabs API key
+            elevenlabs_voice_id: ElevenLabs voice ID
+            head_wobbler: HeadWobbler instance for audio-driven head movement
+            on_listening: Callback when listening starts
+            on_thinking: Callback when processing/thinking
+            on_speaking: Callback when speaking starts
+            profile_mode: If True, print timing summary after each turn
+            on_profile_complete: Callback with timing data after each turn completes
+        """
+        self.gateway_url = gateway_url
+        self.gateway_token = gateway_token or os.getenv("CLAWDBOT_TOKEN")
+        self.elevenlabs_api_key = elevenlabs_api_key or os.getenv("ELEVENLABS_API_KEY")
+        self.elevenlabs_voice_id = elevenlabs_voice_id
+        self.head_wobbler = head_wobbler
+        
+        # State callbacks
+        self.on_listening = on_listening
+        self.on_thinking = on_thinking
+        self.on_speaking = on_speaking
+        
+        # Profiling
+        self.profile_mode = profile_mode
+        self.on_profile_complete = on_profile_complete
+        self._current_timing: Optional[ConversationTiming] = None
+        self._timing_history: list[ConversationTiming] = []
+        
+        # Audio buffers
+        self._audio_buffer: list[NDArray[np.float32]] = []
+        self._buffer_lock = threading.Lock()
+        
+        # Speech detection state
+        self._is_speaking = False
+        self._silence_start: Optional[float] = None
+        self._speech_start: Optional[float] = None
+        
+        # Output queue for TTS audio
+        self.output_queue: asyncio.Queue[Tuple[int, NDArray[np.float32]]] = asyncio.Queue()
+        
+        # Whisper model (lazy load)
+        self._whisper_model = None
+        
+        # Processing state
+        self._processing = False
+        self._stop_event = threading.Event()
+        
+    def _load_whisper(self):
+        """Lazy load Whisper model."""
+        if self._whisper_model is None:
+            from faster_whisper import WhisperModel
+            logger.info("Loading Whisper model...")
+            self._whisper_model = WhisperModel("small.en")
+            logger.info("Whisper model loaded")
+        return self._whisper_model
+    
+    def _compute_rms(self, audio: NDArray[np.float32]) -> float:
+        """Compute RMS of audio signal."""
+        return float(np.sqrt(np.mean(audio ** 2)))
+    
+    async def receive(self, audio_frame: Tuple[int, NDArray]) -> None:
+        """Receive an audio frame from the microphone.
+        
+        Args:
+            audio_frame: Tuple of (sample_rate, audio_data)
+        """
+        input_sr, audio_data = audio_frame
+        
+        # Convert to float32 if needed
+        if audio_data.dtype == np.int16:
+            audio_data = audio_data.astype(np.float32) / 32768.0
+        
+        # Resample to 16kHz if needed
+        if input_sr != SAMPLE_RATE:
+            from scipy.signal import resample
+            num_samples = int(len(audio_data) * SAMPLE_RATE / input_sr)
+            audio_data = resample(audio_data, num_samples).astype(np.float32)
+        
+        # Check for speech
+        rms = self._compute_rms(audio_data)
+        is_speech = rms > SILENCE_THRESHOLD
+        
+        now = time.time()
+        
+        with self._buffer_lock:
+            if is_speech:
+                # Speech detected
+                if not self._is_speaking:
+                    self._is_speaking = True
+                    self._speech_start = now
+                    self._silence_start = None
+                    if self.on_listening:
+                        self.on_listening()
+                    logger.debug("Speech started")
+                
+                self._audio_buffer.append(audio_data)
+                self._silence_start = None
+                
+            else:
+                # Silence
+                if self._is_speaking:
+                    # Still accumulating (might resume speaking)
+                    self._audio_buffer.append(audio_data)
+                    
+                    if self._silence_start is None:
+                        self._silence_start = now
+                    elif now - self._silence_start > SILENCE_DURATION:
+                        # End of utterance
+                        speech_duration = now - (self._speech_start or now)
+                        if speech_duration >= MIN_SPEECH_DURATION:
+                            # Process the utterance
+                            audio_to_process = np.concatenate(self._audio_buffer)
+                            speech_start_time = self._speech_start
+                            speech_end_time = now
+                            self._audio_buffer.clear()
+                            self._is_speaking = False
+                            self._silence_start = None
+                            
+                            # Process in background with timing info
+                            asyncio.create_task(self._process_utterance(
+                                audio_to_process, 
+                                speech_start_time, 
+                                speech_end_time
+                            ))
+                        else:
+                            # Too short, discard
+                            self._audio_buffer.clear()
+                            self._is_speaking = False
+                            self._silence_start = None
+                            logger.debug("Utterance too short, discarding")
+    
+    async def _process_utterance(
+        self, 
+        audio: NDArray[np.float32],
+        speech_start: Optional[float] = None,
+        speech_end: Optional[float] = None,
+    ) -> None:
+        """Process a complete utterance: transcribe, stream to Clawdbot, stream TTS."""
+        if self._processing:
+            logger.warning("Already processing, skipping utterance")
+            return
+        
+        self._processing = True
+        
+        # Initialize timing for this turn
+        timing = ConversationTiming()
+        timing.turn_start = time.time()
+        timing.speech_start = speech_start or timing.turn_start
+        timing.speech_end = speech_end or timing.turn_start
+        self._current_timing = timing
+        
+        try:
+            if self.on_thinking:
+                self.on_thinking()
+            
+            # 1. Transcribe with Whisper
+            logger.info("Transcribing...")
+            timing.transcription_start = time.time()
+            transcript = await self._transcribe(audio)
+            timing.transcription_end = time.time()
+            
+            if not transcript or transcript.strip() == "":
+                logger.debug("Empty transcript, skipping")
+                return
+            
+            timing.user_text = transcript
+            logger.info(f"User said: {transcript}")
+            
+            # 2. Stream from Clawdbot directly to TTS via WebSocket
+            # This starts speaking as soon as LLM tokens arrive
+            logger.info("Streaming response...")
+            if self.on_speaking:
+                self.on_speaking()
+            
+            await self._stream_llm_to_tts(transcript, timing)
+            
+            timing.turn_end = time.time()
+            
+            # Print/record timing summary
+            if self.profile_mode:
+                timing.print_summary()
+            
+            self._timing_history.append(timing)
+            
+            if self.on_profile_complete:
+                self.on_profile_complete(timing)
+            
+        except Exception as e:
+            logger.error(f"Error processing utterance: {e}", exc_info=True)
+        finally:
+            self._processing = False
+            self._current_timing = None
+    
+    async def _transcribe(self, audio: NDArray[np.float32]) -> str:
+        """Transcribe audio using Whisper."""
+        model = self._load_whisper()
+        
+        # Write to temp file (Whisper expects a file path)
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+            sf.write(f.name, audio, SAMPLE_RATE)
+            temp_path = f.name
+        
+        try:
+            # Run in executor to not block
+            loop = asyncio.get_event_loop()
+            segments, _ = await loop.run_in_executor(
+                None,
+                lambda: model.transcribe(temp_path, language="en")
+            )
+            # faster-whisper returns an iterator of segments
+            return "".join(segment.text for segment in segments).strip()
+        finally:
+            Path(temp_path).unlink(missing_ok=True)
+    
+    async def _stream_clawdbot(self, message: str) -> AsyncIterator[str]:
+        """Stream response from Clawdbot via OpenAI-compatible SSE endpoint.
+        
+        Uses httpx-sse for proper SSE parsing without buffering issues.
+        """
+        async with httpx.AsyncClient(timeout=httpx.Timeout(120.0)) as client:
+            headers = {
+                "Content-Type": "application/json",
+                "x-clawdbot-agent-id": "main",
+            }
+            if self.gateway_token:
+                headers["Authorization"] = f"Bearer {self.gateway_token}"
+            
+            url = f"{self.gateway_url}/v1/chat/completions"
+            payload = {
+                "model": "clawdbot:main",
+                "messages": [{"role": "user", "content": message}],
+                "user": "moltbot-body",
+                "stream": True,
+            }
+            
+            stream_start_time = time.time()
+            logger.info(f"[STREAM] Opening SSE connection to {url}")
+            
+            try:
+                async with aconnect_sse(
+                    client, 
+                    "POST", 
+                    url, 
+                    json=payload, 
+                    headers=headers
+                ) as event_source:
+                    # Check response status
+                    event_source.response.raise_for_status()
+                    
+                    connection_time = time.time() - stream_start_time
+                    content_type = event_source.response.headers.get("content-type", "")
+                    logger.info(f"[STREAM] SSE connected in {connection_time:.2f}s, content-type: {content_type}")
+                    
+                    first_event_time = None
+                    event_count = 0
+                    
+                    # Iterate over SSE events (no buffering!)
+                    async for sse in event_source.aiter_sse():
+                        event_count += 1
+                        now = time.time()
+                        elapsed = now - stream_start_time
+                        
+                        if first_event_time is None:
+                            first_event_time = now
+                            logger.info(f"[STREAM] First SSE event at {elapsed:.2f}s")
+                        
+                        # Check for stream end
+                        if sse.data == "[DONE]":
+                            break
+                        
+                        # Parse the JSON data
+                        try:
+                            data = json.loads(sse.data)
+                            choices = data.get("choices", [])
+                            if choices:
+                                delta = choices[0].get("delta", {})
+                                content = delta.get("content", "")
+                                if content:
+                                    logger.debug(f"[STREAM] Event {event_count} at {elapsed:.2f}s: {content[:50]}")
+                                    yield content
+                        except json.JSONDecodeError:
+                            logger.debug(f"[STREAM] Non-JSON SSE data: {sse.data[:50]}")
+                            continue
+                    
+                    # Log stream completion stats
+                    stream_end_time = time.time()
+                    total_stream_time = stream_end_time - stream_start_time
+                    if first_event_time:
+                        time_to_first = first_event_time - stream_start_time
+                        streaming_duration = stream_end_time - first_event_time
+                        logger.info(f"[STREAM] Complete: {event_count} events in {total_stream_time:.2f}s "
+                                   f"(TTFE: {time_to_first:.2f}s, streaming: {streaming_duration:.2f}s)")
+                    else:
+                        logger.warning(f"[STREAM] Complete: No events received in {total_stream_time:.2f}s")
+                        
+            except httpx.HTTPStatusError as e:
+                logger.error(f"Clawdbot HTTP error: {e.response.status_code} - {e.response.text[:200]}")
+            except Exception as e:
+                logger.error(f"Clawdbot streaming error: {e}")
+    
+    async def _stream_llm_to_tts(
+        self, 
+        message: str, 
+        timing: Optional[ConversationTiming] = None
+    ) -> None:
+        """Stream LLM response directly to ElevenLabs WebSocket TTS for minimal latency.
+        
+        Waits for first LLM token before opening WebSocket to avoid 20-second timeout,
+        then streams remaining tokens as they arrive.
+        """
+        if not self.elevenlabs_api_key:
+            logger.warning("No ElevenLabs API key, skipping TTS")
+            return
+        
+        tts_sample_rate = 22050
+        ws_url = f"wss://api.elevenlabs.io/v1/text-to-speech/{self.elevenlabs_voice_id}/stream-input?model_id=eleven_flash_v2_5&output_format=pcm_22050"
+        
+        full_response = []  # Collect for logging and fallback
+        receive_task = None
+        ws = None
+        
+        # Track timing for TTS audio reception
+        first_audio_received = False
+        
+        try:
+            # Get async iterator for LLM tokens
+            if timing:
+                timing.llm_request_start = time.time()
+            
+            llm_stream = self._stream_clawdbot(message)
+            
+            # Wait for first token before opening WebSocket
+            logger.info("Waiting for first LLM token...")
+            first_token = None
+            async for token in llm_stream:
+                first_token = token
+                full_response.append(token)
+                if timing:
+                    timing.llm_first_token = time.time()
+                logger.debug(f"First token received: {token[:50] if len(token) > 50 else token}")
+                break
+            
+            if first_token is None:
+                logger.warning("No tokens received from LLM")
+                return
+            
+            # Now open WebSocket - we have tokens to send
+            logger.info("Opening TTS WebSocket...")
+            ws = await websockets.connect(ws_url)
+            
+            if timing:
+                timing.tts_websocket_open = time.time()
+            
+            # Initialize the WebSocket connection
+            init_message = {
+                "text": " ",  # Initial space to start the stream
+                "voice_settings": {
+                    "stability": 0.5,
+                    "similarity_boost": 0.75,
+                },
+                "xi_api_key": self.elevenlabs_api_key,
+                "auto_mode": True,  # Let ElevenLabs handle chunk timing
+            }
+            await ws.send(json.dumps(init_message))
+            logger.debug("ElevenLabs WebSocket initialized")
+            
+            # Task to receive audio from WebSocket and queue for playback
+            async def receive_audio():
+                nonlocal first_audio_received
+                try:
+                    async for msg in ws:
+                        try:
+                            data = json.loads(msg)
+                            audio_b64 = data.get("audio")
+                            if audio_b64:
+                                # Track first audio timing
+                                if timing and not first_audio_received:
+                                    timing.tts_first_audio = time.time()
+                                    first_audio_received = True
+                                
+                                if timing:
+                                    timing.tts_audio_chunks += 1
+                                    timing.tts_last_audio = time.time()
+                                
+                                # Decode base64 PCM audio
+                                audio_bytes = base64.b64decode(audio_b64)
+                                audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
+                                audio_data = audio_int16.astype(np.float32) / 32768.0
+                                
+                                # Feed to head wobbler
+                                if self.head_wobbler is not None:
+                                    self.head_wobbler.feed(audio_b64)
+                                
+                                # Queue for playback
+                                await self.output_queue.put((tts_sample_rate, audio_data))
+                            
+                            # Check if stream is done
+                            if data.get("isFinal"):
+                                logger.debug("ElevenLabs stream complete")
+                                break
+                        except json.JSONDecodeError:
+                            continue
+                except websockets.exceptions.ConnectionClosed as e:
+                    logger.debug(f"WebSocket closed during receive: {e}")
+            
+            # Start receiving audio in background
+            receive_task = asyncio.create_task(receive_audio())
+            
+            # Send first token
+            logger.debug(f"Sending token 1 to TTS: {first_token[:50] if len(first_token) > 50 else first_token}")
+            await ws.send(json.dumps({"text": first_token}))
+            
+            # Continue streaming remaining tokens
+            token_count = 1
+            async for token in llm_stream:
+                full_response.append(token)
+                token_count += 1
+                if timing:
+                    timing.llm_last_token = time.time()
+                logger.debug(f"Sending token {token_count} to TTS: {token[:50] if len(token) > 50 else token}")
+                await ws.send(json.dumps({"text": token}))
+            
+            if timing:
+                timing.llm_token_count = token_count
+                if not timing.llm_last_token:
+                    timing.llm_last_token = time.time()
+            
+            logger.info(f"Sent {token_count} tokens to TTS")
+            
+            # Signal end of text
+            await ws.send(json.dumps({"text": ""}))
+            
+            # Wait for audio to finish with timeout
+            try:
+                await asyncio.wait_for(receive_task, timeout=60.0)
+            except asyncio.TimeoutError:
+                logger.warning("Timeout waiting for TTS audio, continuing")
+                receive_task.cancel()
+            
+            response_text = "".join(full_response)
+            if timing:
+                timing.assistant_text = response_text
+            logger.info(f"Clawdbot response: {response_text[:100]}...")
+            
+        except websockets.exceptions.ConnectionClosedError as e:
+            logger.warning(f"WebSocket closed: {e}")
+            # Fallback to HTTP streaming with accumulated response
+            if full_response:
+                if timing:
+                    timing.assistant_text = "".join(full_response)
+                logger.info("Falling back to HTTP streaming TTS")
+                await self._generate_tts_fallback("".join(full_response))
+        except Exception as e:
+            logger.error(f"LLM-to-TTS pipeline error: {e}", exc_info=True)
+            # Fallback: if WebSocket fails, try to use accumulated response with HTTP streaming
+            if full_response:
+                if timing:
+                    timing.assistant_text = "".join(full_response)
+                logger.info("Falling back to HTTP streaming TTS")
+                await self._generate_tts_fallback("".join(full_response))
+        finally:
+            if receive_task and not receive_task.done():
+                receive_task.cancel()
+            if ws:
+                await ws.close()
+    
+    async def _generate_tts_fallback(self, text: str) -> None:
+        """Fallback TTS using HTTP streaming (used if WebSocket fails)."""
+        if not self.elevenlabs_api_key or not text:
+            return
+        
+        tts_sample_rate = 22050
+        
+        async with httpx.AsyncClient() as client:
+            try:
+                async with client.stream(
+                    "POST",
+                    f"https://api.elevenlabs.io/v1/text-to-speech/{self.elevenlabs_voice_id}/stream",
+                    params={
+                        "output_format": "pcm_22050",
+                        "optimize_streaming_latency": "3",
+                    },
+                    json={
+                        "text": text,
+                        "model_id": "eleven_flash_v2_5",
+                        "voice_settings": {
+                            "stability": 0.5,
+                            "similarity_boost": 0.75,
+                        }
+                    },
+                    headers={
+                        "xi-api-key": self.elevenlabs_api_key,
+                        "Content-Type": "application/json",
+                    },
+                    timeout=60.0,
+                ) as response:
+                    response.raise_for_status()
+                    
+                    async for chunk in response.aiter_bytes(chunk_size=4096):
+                        if not chunk:
+                            continue
+                        
+                        audio_int16 = np.frombuffer(chunk, dtype=np.int16)
+                        audio_data = audio_int16.astype(np.float32) / 32768.0
+                        
+                        if self.head_wobbler is not None:
+                            audio_b64 = base64.b64encode(audio_int16.tobytes()).decode()
+                            self.head_wobbler.feed(audio_b64)
+                        
+                        await self.output_queue.put((tts_sample_rate, audio_data))
+                
+            except Exception as e:
+                logger.error(f"TTS fallback error: {e}")
+    
+    async def emit(self) -> Optional[Tuple[int, NDArray[np.float32]]]:
+        """Get the next audio chunk for playback."""
+        try:
+            return await asyncio.wait_for(self.output_queue.get(), timeout=0.1)
+        except asyncio.TimeoutError:
+            return None
+    
+    def stop(self) -> None:
+        """Stop the handler."""
+        self._stop_event.set()

moltbot_body/main.py

@@ -0,0 +1,322 @@
+"""Main entry point for Moltbot's body control."""
+
+import os
+import sys
+import time
+import asyncio
+import logging
+import argparse
+import threading
+from pathlib import Path
+from typing import Optional
+
+from dotenv import load_dotenv
+from reachy_mini import ReachyMini, ReachyMiniApp
+
+# Load environment from project root (.env next to pyproject.toml)
+_project_root = Path(__file__).parent.parent
+load_dotenv(_project_root / ".env")
+
+logger = logging.getLogger(__name__)
+
+
+def setup_logging(debug: bool = False) -> None:
+    """Configure logging."""
+    level = logging.DEBUG if debug else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description="Moltbot's body control")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    parser.add_argument("--robot-name", type=str, help="Robot name for connection")
+    parser.add_argument(
+        "--gateway-url",
+        type=str,
+        default="http://localhost:18789",
+        help="Clawdbot gateway URL",
+    )
+    parser.add_argument(
+        "--profile",
+        action="store_true",
+        help="Enable timing profiler - prints detailed timing after each turn",
+    )
+    parser.add_argument(
+        "--profile-once",
+        action="store_true", 
+        help="Profile one conversation turn then exit (implies --profile)",
+    )
+    return parser.parse_args()
+
+
+class MoltbotBodyCore:
+    """Main class controlling Moltbot's physical body."""
+
+    def __init__(
+        self,
+        gateway_url: str = "http://localhost:18789",
+        robot_name: Optional[str] = None,
+        profile_mode: bool = False,
+        profile_once: bool = False,
+        robot: Optional[ReachyMini] = None,
+        external_stop_event: Optional[threading.Event] = None,
+    ):
+        """Initialize Moltbot's body.
+        
+        Args:
+            gateway_url: Clawdbot gateway URL
+            robot_name: Optional robot name for connection
+            profile_mode: Enable timing profiler
+            profile_once: Exit after one conversation turn (implies profile_mode)
+            robot: Optional pre-initialized ReachyMini instance (for app framework)
+            external_stop_event: Optional external stop event (for app framework)
+        """
+        from moltbot_body.clawdbot_handler import ClawdbotHandler
+        from moltbot_body.moves import MovementManager
+        from moltbot_body.audio.head_wobbler import HeadWobbler
+        
+        self.gateway_url = gateway_url
+        self.profile_once = profile_once
+        self._external_stop_event = external_stop_event
+        self._owns_robot = robot is None  # Track if we created the robot
+        
+        # Use provided robot or create one
+        if robot is not None:
+            self.robot = robot
+            logger.info("Using provided Reachy Mini instance")
+        else:
+            # Connect to robot
+            logger.info("Connecting to Reachy Mini...")
+            robot_kwargs = {}
+            if robot_name:
+                robot_kwargs["robot_name"] = robot_name
+            
+            try:
+                self.robot = ReachyMini(**robot_kwargs)
+            except TimeoutError as e:
+                logger.error(f"Connection timeout: Failed to connect to Reachy Mini. Details: {e}")
+                logger.error("Check that the robot is powered on and reachable on the network.")
+                sys.exit(1)
+            except ConnectionError as e:
+                logger.error(f"Connection failed: Unable to establish connection. Details: {e}")
+                sys.exit(1)
+            except Exception as e:
+                logger.error(f"Unexpected error during robot initialization: {type(e).__name__}: {e}")
+                sys.exit(1)
+            
+            logger.info(f"Connected to robot: {self.robot.client.get_status()}")
+        
+        # Initialize movement system
+        logger.info("Initializing movement manager...")
+        self.movement_manager = MovementManager(current_robot=self.robot)
+        self.head_wobbler = HeadWobbler(set_speech_offsets=self.movement_manager.set_speech_offsets)
+        
+        # Initialize handler
+        gateway_token = os.getenv("CLAWDBOT_TOKEN")
+        if not gateway_token:
+            logger.warning("CLAWDBOT_TOKEN not found in environment - auth may fail")
+        else:
+            logger.debug(f"Gateway token loaded ({len(gateway_token)} chars)")
+        
+        # Callback to handle profile completion
+        def on_profile_complete(timing):
+            if self.profile_once:
+                logger.info("Profile complete - scheduling shutdown...")
+                self._stop_event.set()
+        
+        self.handler = ClawdbotHandler(
+            gateway_url=gateway_url,
+            gateway_token=gateway_token,
+            elevenlabs_api_key=os.getenv("ELEVENLABS_API_KEY"),
+            head_wobbler=self.head_wobbler,
+            on_listening=self._on_listening,
+            on_thinking=self._on_thinking,
+            on_speaking=self._on_speaking,
+            profile_mode=profile_mode or profile_once,
+            on_profile_complete=on_profile_complete if profile_once else None,
+        )
+        
+        # State
+        self._stop_event = asyncio.Event()
+        self._tasks: list[asyncio.Task] = []
+    
+    def _on_listening(self) -> None:
+        """Callback when listening starts."""
+        logger.info("Listening...")
+        self.movement_manager.set_listening(True)
+    
+    def _on_thinking(self) -> None:
+        """Callback when thinking/processing."""
+        logger.info("Thinking...")
+        self.movement_manager.set_listening(False)
+    
+    def _on_speaking(self) -> None:
+        """Callback when speaking starts."""
+        logger.info("Speaking...")
+        self.head_wobbler.reset()  # Clear any stale audio from previous utterance
+    
+    def _should_stop(self) -> bool:
+        """Check if we should stop (internal or external stop event)."""
+        if self._stop_event.is_set():
+            return True
+        if self._external_stop_event is not None and self._external_stop_event.is_set():
+            return True
+        return False
+    
+    async def record_loop(self) -> None:
+        """Read audio from robot microphone and send to handler."""
+        input_sample_rate = self.robot.media.get_input_audio_samplerate()
+        logger.info(f"Recording at {input_sample_rate} Hz")
+        
+        while not self._should_stop():
+            audio_frame = self.robot.media.get_audio_sample()
+            if audio_frame is not None:
+                await self.handler.receive((input_sample_rate, audio_frame))
+            await asyncio.sleep(0.01)  # ~100Hz polling
+    
+    async def play_loop(self) -> None:
+        """Play audio from handler through robot speakers."""
+        output_sample_rate = self.robot.media.get_output_audio_samplerate()
+        logger.info(f"Playing at {output_sample_rate} Hz")
+        
+        while not self._should_stop():
+            output = await self.handler.emit()
+            if output is not None:
+                input_sr, audio_data = output
+                
+                # Resample if needed
+                if input_sr != output_sample_rate:
+                    from scipy.signal import resample
+                    num_samples = int(len(audio_data) * output_sample_rate / input_sr)
+                    audio_data = resample(audio_data, num_samples).astype("float32")
+                
+                self.robot.media.push_audio_sample(audio_data)
+            
+            await asyncio.sleep(0.01)
+    
+    async def run(self) -> None:
+        """Run the main loop."""
+        # Start movement system
+        logger.info("Starting movement manager...")
+        self.movement_manager.start()
+        self.head_wobbler.start()
+        
+        # Start media
+        logger.info("Starting audio...")
+        self.robot.media.start_recording()
+        self.robot.media.start_playing()
+        time.sleep(1)  # Let pipelines initialize
+        
+        logger.info("Ready! Speak to me...")
+        
+        # Start tasks
+        self._tasks = [
+            asyncio.create_task(self.record_loop(), name="record-loop"),
+            asyncio.create_task(self.play_loop(), name="play-loop"),
+        ]
+        
+        try:
+            await asyncio.gather(*self._tasks)
+        except asyncio.CancelledError:
+            logger.info("Tasks cancelled")
+    
+    def stop(self) -> None:
+        """Stop everything."""
+        logger.info("Stopping...")
+        self._stop_event.set()
+        
+        # Cancel tasks
+        for task in self._tasks:
+            if not task.done():
+                task.cancel()
+        
+        # Stop movement system (MovementManager resets to neutral on stop)
+        self.head_wobbler.stop()
+        self.movement_manager.stop()
+        
+        # Only manage robot resources if we created it
+        if self._owns_robot:
+            # Close media
+            try:
+                self.robot.media.close()
+            except Exception as e:
+                logger.debug(f"Error closing media: {e}")
+            
+            # Disconnect
+            self.robot.client.disconnect()
+        
+        self.handler.stop()
+        
+        logger.info("Stopped")
+
+
+class MoltbotBody(ReachyMiniApp):
+    """Reachy Mini Apps entry point for Moltbot Body.
+    
+    This class allows Moltbot Body to be installed and run from the
+    Reachy Mini dashboard as a Reachy Mini App.
+    """
+    
+    # No custom settings UI for now
+    custom_app_url: str | None = None
+    
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
+        """Run Moltbot Body as a Reachy Mini App.
+        
+        Args:
+            reachy_mini: Pre-initialized ReachyMini instance from the framework
+            stop_event: Threading event to signal when the app should stop
+        """
+        # Create a new event loop for async operations
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        
+        # Get gateway URL from environment
+        gateway_url = os.getenv("CLAWDBOT_GATEWAY_URL", "http://localhost:18789")
+        
+        # Create the body controller with the provided robot instance
+        body = MoltbotBodyCore(
+            gateway_url=gateway_url,
+            robot=reachy_mini,
+            external_stop_event=stop_event,
+        )
+        
+        try:
+            loop.run_until_complete(body.run())
+        except Exception as e:
+            logger.error(f"Error running Moltbot Body: {e}")
+        finally:
+            body.stop()
+            loop.close()
+
+
+def main() -> None:
+    """Entry point."""
+    args = parse_args()
+    setup_logging(args.debug)
+    
+    if args.profile or args.profile_once:
+        logger.info("Profiling mode enabled")
+    
+    body = MoltbotBodyCore(
+        gateway_url=args.gateway_url,
+        robot_name=args.robot_name,
+        profile_mode=args.profile,
+        profile_once=args.profile_once,
+    )
+    
+    try:
+        asyncio.run(body.run())
+    except KeyboardInterrupt:
+        logger.info("Interrupted")
+    finally:
+        body.stop()
+
+
+if __name__ == "__main__":
+    main()

moltbot_body/moves.py

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

pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moltbot-body"
+version = "0.1.0"
+description = "Motlbot's physical body - Reachy Mini integration with Clawdbot"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    # Reachy Mini SDK
+    "reachy-mini>=1.2.13",
+    "reachy_mini_dances_library",
+    "reachy_mini_toolbox",
+    
+    # Audio
+    "numpy",
+    "scipy",
+    "soundfile",
+    
+    # Whisper STT (faster-whisper uses CTranslate2, no numba dependency)
+    "faster-whisper",
+    
+    # HTTP client for Clawdbot gateway
+    "httpx",
+    "httpx-sse>=0.4.0",
+    
+    # WebSocket for streaming TTS
+    "websockets>=12.0",
+    
+    # Environment
+    "python-dotenv",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+]
+
+[project.scripts]
+moltbot-body = "moltbot_body.main:main"
+
+[project.entry-points."reachy_mini_apps"]
+moltbot-body = "moltbot_body.main:MoltbotBody"
+
+[tool.setuptools.packages.find]
+where = ["."]

style.css

@@ -0,0 +1,395 @@
+:root {
+	--bg: #060c1d;
+	--panel: #0c172b;
+	--glass: rgba(17, 27, 48, 0.7);
+	--card: rgba(255, 255, 255, 0.04);
+	--accent: #7af5c4;
+	--accent-2: #f6c452;
+	--text: #e8edf7;
+	--muted: #9fb3ce;
+	--border: rgba(255, 255, 255, 0.08);
+	--shadow: 0 25px 70px rgba(0, 0, 0, 0.45);
+	font-family: "Space Grotesk", "Manrope", system-ui, -apple-system, sans-serif;
+}
+
+* {
+	margin: 0;
+	padding: 0;
+	box-sizing: border-box;
+}
+
+body {
+	background: radial-gradient(circle at 20% 20%, rgba(122, 245, 196, 0.12), transparent 30%),
+		radial-gradient(circle at 80% 0%, rgba(246, 196, 82, 0.14), transparent 32%),
+		radial-gradient(circle at 50% 70%, rgba(124, 142, 255, 0.1), transparent 30%),
+		var(--bg);
+	color: var(--text);
+	min-height: 100vh;
+	line-height: 1.6;
+	padding-bottom: 3rem;
+}
+
+a {
+	color: inherit;
+	text-decoration: none;
+}
+
+.hero {
+	padding: 3.5rem clamp(1.5rem, 3vw, 3rem) 2.5rem;
+	position: relative;
+	overflow: hidden;
+}
+
+.hero::after {
+	content: "";
+	position: absolute;
+	inset: 0;
+	background: linear-gradient(120deg, rgba(122, 245, 196, 0.12), rgba(246, 196, 82, 0.08), transparent);
+	pointer-events: none;
+}
+
+.topline {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	max-width: 1200px;
+	margin: 0 auto 2rem;
+	position: relative;
+	z-index: 2;
+}
+
+.brand {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	font-weight: 700;
+	letter-spacing: 0.5px;
+	color: var(--text);
+}
+
+.logo {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 2.2rem;
+	height: 2.2rem;
+	border-radius: 10px;
+	background: linear-gradient(145deg, rgba(122, 245, 196, 0.15), rgba(124, 142, 255, 0.15));
+	box-shadow: 0 10px 30px rgba(0, 0, 0, 0.25);
+}
+
+.brand-name {
+	font-size: 1.1rem;
+}
+
+.pill {
+	background: rgba(255, 255, 255, 0.06);
+	border: 1px solid var(--border);
+	padding: 0.6rem 1rem;
+	border-radius: 999px;
+	color: var(--muted);
+	font-size: 0.9rem;
+	box-shadow: 0 12px 30px rgba(0, 0, 0, 0.2);
+}
+
+.hero-grid {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+	gap: clamp(1.5rem, 2.5vw, 2.5rem);
+	max-width: 1200px;
+	margin: 0 auto;
+	position: relative;
+	z-index: 2;
+	align-items: center;
+}
+
+.hero-copy h1 {
+	font-size: clamp(2.6rem, 4vw, 3.6rem);
+	margin-bottom: 1rem;
+	line-height: 1.1;
+	letter-spacing: -0.5px;
+}
+
+.eyebrow {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+	text-transform: uppercase;
+	letter-spacing: 1px;
+	font-size: 0.8rem;
+	color: var(--muted);
+	margin-bottom: 0.75rem;
+}
+
+.eyebrow::before {
+	content: "";
+	display: inline-block;
+	width: 24px;
+	height: 2px;
+	background: linear-gradient(90deg, var(--accent), var(--accent-2));
+	border-radius: 999px;
+}
+
+.lede {
+	font-size: 1.1rem;
+	color: var(--muted);
+	max-width: 620px;
+}
+
+.hero-actions {
+	display: flex;
+	gap: 1rem;
+	align-items: center;
+	margin: 1.6rem 0 1.2rem;
+	flex-wrap: wrap;
+}
+
+.btn {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	gap: 0.6rem;
+	padding: 0.85rem 1.4rem;
+	border-radius: 12px;
+	font-weight: 700;
+	border: 1px solid transparent;
+	cursor: pointer;
+	transition: transform 0.2s ease, box-shadow 0.2s ease, background 0.2s ease, border-color 0.2s ease;
+}
+
+.btn.primary {
+	background: linear-gradient(135deg, #7af5c4, #7c8eff);
+	color: #0a0f1f;
+	box-shadow: 0 15px 30px rgba(122, 245, 196, 0.25);
+}
+
+.btn.primary:hover {
+	transform: translateY(-2px);
+	box-shadow: 0 25px 45px rgba(122, 245, 196, 0.35);
+}
+
+.btn.ghost {
+	background: rgba(255, 255, 255, 0.05);
+	border-color: var(--border);
+	color: var(--text);
+}
+
+.btn.ghost:hover {
+	border-color: rgba(255, 255, 255, 0.3);
+	transform: translateY(-2px);
+}
+
+.btn.wide {
+	width: 100%;
+	justify-content: center;
+}
+
+.hero-badges {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.6rem;
+	color: var(--muted);
+	font-size: 0.9rem;
+}
+
+.hero-badges span {
+	padding: 0.5rem 0.8rem;
+	border-radius: 10px;
+	border: 1px solid var(--border);
+	background: rgba(255, 255, 255, 0.04);
+}
+
+.hero-visual .glass-card {
+	background: rgba(255, 255, 255, 0.03);
+	border: 1px solid var(--border);
+	border-radius: 18px;
+	padding: 1.2rem;
+	box-shadow: var(--shadow);
+	backdrop-filter: blur(10px);
+}
+
+.architecture-preview {
+	background: rgba(0, 0, 0, 0.3);
+	border-radius: 14px;
+	border: 1px solid var(--border);
+	padding: 1.5rem;
+	overflow-x: auto;
+}
+
+.architecture-preview pre {
+	font-family: "SF Mono", "Fira Code", "Consolas", monospace;
+	font-size: 0.85rem;
+	color: var(--accent);
+	white-space: pre;
+	margin: 0;
+	line-height: 1.5;
+}
+
+.caption {
+	margin-top: 0.75rem;
+	color: var(--muted);
+	font-size: 0.95rem;
+}
+
+.section {
+	max-width: 1200px;
+	margin: 0 auto;
+	padding: clamp(2rem, 4vw, 3.5rem) clamp(1.5rem, 3vw, 3rem);
+}
+
+.section-header {
+	text-align: center;
+	max-width: 780px;
+	margin: 0 auto 2rem;
+}
+
+.section-header h2 {
+	font-size: clamp(2rem, 3vw, 2.6rem);
+	margin-bottom: 0.5rem;
+}
+
+.intro {
+	color: var(--muted);
+	font-size: 1.05rem;
+}
+
+.feature-grid {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+	gap: 1rem;
+}
+
+.feature-card {
+	background: rgba(255, 255, 255, 0.03);
+	border: 1px solid var(--border);
+	border-radius: 16px;
+	padding: 1.25rem;
+	box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
+	transition: transform 0.2s ease, border-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.feature-card:hover {
+	transform: translateY(-4px);
+	border-color: rgba(122, 245, 196, 0.3);
+	box-shadow: 0 18px 40px rgba(0, 0, 0, 0.3);
+}
+
+.feature-card .icon {
+	width: 48px;
+	height: 48px;
+	border-radius: 12px;
+	display: grid;
+	place-items: center;
+	background: rgba(122, 245, 196, 0.14);
+	margin-bottom: 0.8rem;
+	font-size: 1.4rem;
+}
+
+.feature-card h3 {
+	margin-bottom: 0.35rem;
+}
+
+.feature-card p {
+	color: var(--muted);
+}
+
+.story {
+	padding-top: 1rem;
+}
+
+.story-grid {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+	gap: 1rem;
+}
+
+.story-card {
+	background: rgba(255, 255, 255, 0.03);
+	border: 1px solid var(--border);
+	border-radius: 18px;
+	padding: 1.5rem;
+	box-shadow: var(--shadow);
+}
+
+.story-card.secondary {
+	background: linear-gradient(145deg, rgba(124, 142, 255, 0.08), rgba(122, 245, 196, 0.06));
+}
+
+.story-card h3 {
+	margin-bottom: 0.8rem;
+}
+
+.story-list {
+	list-style: none;
+	display: grid;
+	gap: 0.7rem;
+	color: var(--muted);
+	font-size: 0.98rem;
+}
+
+.story-list li {
+	display: flex;
+	gap: 0.7rem;
+	align-items: flex-start;
+}
+
+.story-text {
+	color: var(--muted);
+	line-height: 1.7;
+	margin-bottom: 1rem;
+}
+
+.chips {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.5rem;
+}
+
+.chip {
+	padding: 0.45rem 0.8rem;
+	border-radius: 12px;
+	background: rgba(0, 0, 0, 0.2);
+	border: 1px solid var(--border);
+	color: var(--text);
+	font-size: 0.9rem;
+}
+
+.footer {
+	text-align: center;
+	color: var(--muted);
+	padding: 2rem 1.5rem 0;
+}
+
+.footer a {
+	color: var(--text);
+	border-bottom: 1px solid transparent;
+}
+
+.footer a:hover {
+	border-color: rgba(255, 255, 255, 0.5);
+}
+
+@media (max-width: 768px) {
+	.hero {
+		padding-top: 2.5rem;
+	}
+
+	.topline {
+		flex-direction: column;
+		gap: 0.8rem;
+		align-items: flex-start;
+	}
+
+	.hero-actions {
+		width: 100%;
+	}
+
+	.btn {
+		width: 100%;
+		justify-content: center;
+	}
+
+	.hero-badges {
+		gap: 0.4rem;
+	}
+}