v1.2.0: optional ElevenLabs cloud voice (onboarding key box, local Piper fallback)

chittios/main.py

@@ -1,706 +1,790 @@
-"""ChittiOS — the Reachy Mini app shell (Phase 7: the composed OS).
-
-Phase 1 proved the publish → install → run pipeline with a greeting and idle
-breathing. This is the real app: a thin shell that constructs the *concrete*,
-hardware- and model-backed engines and hands them to ``chittios_core``'s
-:class:`~chittios_core.orchestrator.ChittiOS`, which owns every line of composition
-logic. Nothing here decides *what* ChittiOS does — it only supplies the real body,
-the real camera and microphone, and the real STT/LLM/TTS to the seams the
-orchestrator drives, exactly where a test supplies stubs.
-
-Thin, and gracefully degrading
-------------------------------
-Every heavy engine is optional: a fresh SBC may lack a Piper voice, a Whisper
-model, or a reachable LLM, and the household should still get a robot that
-recognises them and says hello rather than one that refuses to boot. So each
-engine is built behind a small guarded factory that returns ``None`` (or a stub
-fallback for the one engine — TTS — the greeting cannot do without) when its
-dependency or device is absent. A missing LLM costs conversation and nothing
-else; perception, greeting, and idle motion run regardless.
-
-Idle breathing stays a raw-SDK control loop
---------------------------------------------
-The "alive" breathing is the one thing that cannot go through the HAL motion
-primitives: it needs ``set_target`` at a fixed 60 Hz (repeated ``goto_target``
-each restart the interpolation — the judder Phase 1 diagnosed). So it stays here,
-against the raw SDK, wrapped as an :class:`IdleMotion` the orchestrator runs on
-its own thread — the reference control loop, unchanged, just handed to the
-composition instead of being ``run``'s only body.
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-import threading
-import time
-from collections.abc import Callable
-from contextlib import ExitStack
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import TypeVar
-
-import numpy as np
-from fastapi import FastAPI
-from numpy.typing import NDArray
-from pydantic import BaseModel
-from reachy_mini import ReachyMini, ReachyMiniApp
-from reachy_mini.utils import create_head_pose
-
-from chittios_core.context import ContextManager
-from chittios_core.conversation.config import LlmConfig, load_llm_config, write_llm_config
-from chittios_core.conversation.llm import OpenAICompatibleLlm
-from chittios_core.conversation.stt import WhisperStt
-from chittios_core.conversation.vad import OnnxVadSegmenter
-from chittios_core.expression.tts import PiperTtsEngine, StubTtsEngine, TtsEngine
-from chittios_core.identity import roster
-from chittios_core.identity.face.detector import FaceDetectorProtocol, YuNetDetector
-from chittios_core.identity.face.embedder import SFaceEmbedder
-from chittios_core.identity.face.provider import FaceIdentityProvider
-from chittios_core.identity.onboarding.adapters import (
-    AntennaHoldSignal,
-    MicNameRecorder,
-    ModelEnrollerFactory,
-    PassphraseCustody,
-    PullFaceSource,
-    PullVoiceSource,
-    SyncSpeechOut,
-    WhisperSpeechIn,
-)
-from chittios_core.identity.onboarding.authority import AuthorityGate
-from chittios_core.identity.onboarding.conductor import CaptureConductor
-from chittios_core.identity.onboarding.dialog import (
-    DialogOutcome,
-    DialogResult,
-    EnrollmentDialog,
-)
-from chittios_core.identity.onboarding.ports import SessionRecognizer, SpeechOut
-from chittios_core.identity.session import Session
-from chittios_core.identity.store.enrollments import EnrollmentStore
-from chittios_core.identity.store.keys import (
-    FileKeyStore,
-    KeyCustodyError,
-    KeyringKeyStore,
-    get_or_create_key,
-)
-from chittios_core.identity.types import IdentityClaim, IdentityProvider, Modality
-from chittios_core.identity.voice.embedder import ECAPAEmbedder
-from chittios_core.identity.voice.provider import VoiceIdentityProvider
-from chittios_core.identity.voice.segmenter import SegmenterProtocol, SpeechSegment
-from chittios_core.orchestrator import (
-    ChittiOS,
-    ConversationSeams,
-    OwnerEnrollment,
-    PerceptionSeams,
-)
-from chittios_core.perception.loop import FacePipeline
-from chittios_core.perception.sources import (
-    CameraSource,
-    MicSource,
-    ReachyMiniCameraSource,
-    SoundDeviceMicSource,
-)
-from hal.reachy_mini.adapter import ReachyMiniAdapter
-
-logger = logging.getLogger(__name__)
-
-_T = TypeVar("_T")
-
-#: Where the enrolled household lives on the robot. The store creates its parent.
-STORE_PATH = Path.home() / ".local" / "share" / "chittios" / "enrollments.db"
-
-#: Where the recoverable passphrase custody vault lives — the Argon2id-wrapped
-#: data key the recovery flow re-derives. Beside the store because a wrapped key
-#: is ciphertext, useless without the household passphrase (see vault.py).
-VAULT_PATH = Path.home() / ".local" / "share" / "chittios" / "passphrase.vault"
-
-#: Piper voice model. Prefer the one bundled with the app so a fresh robot speaks
-#: real words out of the box; fall back to a user-supplied model in the data dir.
-_BUNDLED_VOICE = Path(__file__).parent / "assets" / "voice.onnx"
-_USER_VOICE = Path.home() / ".local" / "share" / "chittios" / "voice.onnx"
-
-#: Spoken by the empty-store fallback when the robot cannot run onboarding —
-#: honest and warm rather than silent. The robot then idles (breathing) rather
-#: than exiting, so a household that unboxes it into a half-provisioned state
-#: still meets something alive.
-ONBOARDING_UNAVAILABLE_GREETING = (
-    "Hello. I'm not quite ready to set up your household yet, but I'm here with you."
-)
-
-# ── idle breathing (the reference 60 Hz control loop) ──────────────────────
-
-#: Control-loop rate. The fleet app uses 60 Hz; the docs floor smoothness at
-#: 30 Hz. One ``set_target`` per tick, period held by adaptive sleep.
-CONTROL_FREQUENCY_HZ = 60.0
-CONTROL_PERIOD_S = 1.0 / CONTROL_FREQUENCY_HZ
-
-#: Idle "breathing": the target pose is a smooth sine of time (not discrete
-#: commands). Amplitudes kept small and slow, matching the reference breathing.
-BREATHING_PITCH_DEG = 3.0
-BREATHING_PITCH_HZ = 0.2
-LOOK_YAW_DEG = 8.0
-LOOK_YAW_HZ = 0.05
-
-
-class BreathingMotion:
-    """The idle "alive" motion, as an :class:`IdleMotion` the orchestrator runs.
-
-    The Phase 1 control loop, unchanged in substance: one ``set_target`` per tick
-    at a monotonic-aligned 60 Hz, the pose a smooth sine of time. It lives against
-    the raw SDK rather than the HAL because it needs ``set_target``'s immediacy —
-    the HAL's queued ``goto_target`` would restart interpolation every tick and
-    judder. The orchestrator runs this on its own thread and stops it with the same
-    event that stops everything else.
-
-    Args:
-        mini: The connected robot to drive.
-    """
-
-    def __init__(self, mini: ReachyMini) -> None:
-        self._mini = mini
-
-    def run(self, stop: threading.Event) -> None:
-        """Breathe until ``stop`` is set, then return."""
-        start = time.monotonic()
-        while not stop.is_set():
-            tick_start = time.monotonic()
-            elapsed = tick_start - start
-
-            pitch_deg = BREATHING_PITCH_DEG * np.sin(2.0 * np.pi * BREATHING_PITCH_HZ * elapsed)
-            yaw_deg = LOOK_YAW_DEG * np.sin(2.0 * np.pi * LOOK_YAW_HZ * elapsed)
-            self._mini.set_target(head=create_head_pose(pitch=pitch_deg, yaw=yaw_deg, degrees=True))
-
-            # Adaptive sleep holds the period regardless of per-tick cost; the
-            # event doubles as an interruptible sleep, so a stop returns at once.
-            sleep_s = max(0.0, CONTROL_PERIOD_S - (time.monotonic() - tick_start))
-            if stop.wait(sleep_s):
-                break
-
-
-class _GreetAndIdleFallback:
-    """The empty-store path when onboarding genuinely cannot be assembled.
-
-    An unboxed robot has an empty store and, normally, runs the spoken owner
-    enrollment. But if the pieces that ritual needs — a working microphone, the
-    voice models, the vault — cannot be built, the honest failure is not to exit
-    silently (a robot that does nothing looks broken) but to *say so* and stay
-    alive. Staying alive is the orchestrator's job now: it breathes on its own
-    thread and offers ``enroll_owner`` again on a cadence for the whole empty-store
-    lifetime, so this only owes a single greeting. It says its line the first time
-    it is offered and returns ``FAILED``; subsequent offers return ``FAILED``
-    silently, so the robot breathes on quietly rather than repeating itself.
-
-    It satisfies :class:`OwnerEnrollment` structurally, so the orchestrator drives
-    it through exactly the same ``enroll_owner`` seam it drives the real dialog
-    through — the orchestrator's own empty-store semantics are untouched; only
-    *what* is wired into that seam differs when the dialog could not be built.
-
-    Args:
-        speech_out: How the greeting is spoken (the same sync TTS seam the dialog
-            would have used).
-        greeting: The single line spoken on the first offer.
-    """
-
-    def __init__(
-        self,
-        speech_out: SpeechOut,
-        *,
-        greeting: str = ONBOARDING_UNAVAILABLE_GREETING,
-    ) -> None:
-        self._speech_out = speech_out
-        self._greeting = greeting
-        self._greeted = False
-
-    def enroll_owner(self) -> DialogResult:
-        """Greet on the first offer, then stay quiet. Nothing is ever enrolled."""
-        if not self._greeted:
-            self._greeted = True
-            try:
-                self._speech_out.speak(self._greeting)
-            except Exception:
-                logger.warning("the fallback greeting could not be spoken", exc_info=True)
-        return DialogResult(DialogOutcome.FAILED)
-
-
-# ── null sources (degrade when a device is absent) ─────────────────────────
-
-
-class _NullCamera:
-    """A :class:`CameraSource` that always sees nothing.
-
-    Used when no camera can be opened: perception then runs on voice alone rather
-    than failing to start. A returned ``None`` is the source contract's ordinary
-    "nothing right now", so the loop simply never gets a face.
-    """
-
-    def read(self) -> None:
-        return None
-
-
-class _NullMic:
-    """A :class:`MicSource` that always hears nothing — the audio counterpart."""
-
-    def read(self) -> None:
-        return None
-
-
-class _NullVoiceProvider:
-    """A voice :class:`IdentityProvider` that recognises no one — face-only builds.
-
-    The speaker encoder (ECAPA) is torch- and speechbrain-backed, ~2 GB that does
-    not fit on the Reachy Mini, so voice **identification** is dropped on the
-    robot (the owner's call). Perception still segments audio — the conversation
-    loop needs those utterances for STT — but the voice *provider* it drives is
-    this: every utterance returns an unknown claim, exactly as the real provider
-    does for anyone unenrolled, so the fusion and authorization paths downstream
-    are unchanged and simply never receive a voice match. Recognition runs on the
-    face alone.
-
-    It satisfies :class:`~chittios_core.identity.types.IdentityProvider`\\
-    ``[SpeechSegment]`` structurally, so it drops into the same perception seam
-    the real provider fills, and it constructs nothing torch-backed.
-    """
-
-    @property
-    def modality(self) -> Modality:
-        return Modality.VOICE
-
-    def identify(
-        self, observation: SpeechSegment, /, *, observed_at: datetime | None = None
-    ) -> IdentityClaim:
-        """Return an unknown voice claim for any utterance — no one is identified."""
-        return IdentityClaim.unknown(
-            modality=Modality.VOICE, observed_at=observed_at or datetime.now(UTC)
-        )
-
-
-class _NullVoiceEmbedder:
-    """A voice embedder that is never called — the placeholder for face-only sittings.
-
-    ``ModelEnrollerFactory`` holds a voice embedder so it can mint voice enrollers,
-    but a face-only enrollment (``enroll_voice=False``) never asks it for one, so
-    this stand-in is only ever *held*, never *invoked*. It exists so the factory's
-    wiring is uniform whether or not a speaker encoder is present, without
-    constructing the torch-backed ECAPA on a robot that cannot run it. Being
-    called would mean a face-only sitting tried to embed voice after all, which is
-    a wiring bug worth failing loudly on rather than papering over with a vector.
-    """
-
-    def embed(self, canonical_audio: NDArray[np.float32], /) -> NDArray[np.float32]:
-        raise NotImplementedError(
-            "voice enrollment is disabled on this build; _NullVoiceEmbedder must never be called"
-        )
-
-
-def _guard(what: str, build: Callable[[], _T]) -> _T | None:
-    """Build an optional engine, degrading to ``None`` if its runtime is absent.
-
-    The one place the "a missing model must not stop the robot booting" rule is
-    enforced: any failure to construct — a missing package, an absent model file,
-    an unopenable device — is logged and turned into ``None`` rather than raised.
-    """
-    try:
-        return build()
-    except Exception:
-        logger.warning("%s is unavailable; ChittiOS will run without it", what, exc_info=True)
-        return None
-
-
-def _resolve_store_key() -> bytes:
-    """The enrollment store's encryption key: OS keychain where one exists, else a
-    mode-0600 key file on a headless Linux host.
-
-    The robot is headless Linux with no login keyring, so ``KeyringKeyStore``
-    raises there. ``FileKeyStore`` keeps the key in a 0600 file beside the store —
-    weaker than a keychain (the key sits near the data it protects), but on a box
-    with no keychain it is that or no at-rest encryption at all. Windows and macOS
-    keep the keychain; ``FileKeyStore`` is POSIX-only, so this only falls back on
-    a POSIX host.
-    """
-    try:
-        return get_or_create_key(KeyringKeyStore())
-    except KeyCustodyError:
-        if os.name != "posix":
-            raise
-        key_dir = STORE_PATH.parent
-        key_dir.mkdir(parents=True, exist_ok=True)
-        logger.warning("no OS keychain available; using a 0600 key file in %s", key_dir)
-        return get_or_create_key(FileKeyStore(key_dir))
-
-
-class LlmSettingsUpdate(BaseModel):
-    """The dashboard's ``POST /llm-config`` body — the three settings, plus key semantics.
-
-    ``api_key`` distinguishes three intents a single password field cannot
-    otherwise express: ``None`` (field left blank) leaves the stored key
-    untouched, an empty string clears it, and any other string sets it — so
-    changing the URL never silently drops a previously saved key.
-
-    Defined at module scope, not inside :meth:`Chittios._register_settings_routes`,
-    on purpose: this module uses ``from __future__ import annotations`` (PEP 563),
-    so the route handler's ``update: LlmSettingsUpdate`` annotation is a *string*
-    that FastAPI resolves with :func:`typing.get_type_hints` against the module's
-    globals. A method-local class is not in those globals, so the annotation
-    fails to resolve to this Pydantic model and FastAPI falls back to treating
-    ``update`` as a required *query* parameter — which no JSON body can satisfy,
-    yielding ``422 Unprocessable Entity`` on every save. Keeping the model here,
-    where ``get_type_hints`` can find it, is what makes the body bind.
-    """
-
-    base_url: str
-    model: str
-    api_key: str | None = None
-
-
-class Chittios(ReachyMiniApp):  # type: ignore[misc]  # reachy_mini ships no stubs; base resolves to Any
-    # A small settings web UI, served by the daemon on this URL, lets a household
-    # point ChittiOS at their own LLM endpoint from the robot dashboard. The base
-    # class builds ``self.settings_app`` (a FastAPI app) from this URL; we add the
-    # config routes in ``run``. ``0.0.0.0`` so the dashboard reaches it over the LAN.
-    custom_app_url: str | None = "http://0.0.0.0:8042"
-    request_media_backend: str | None = None
-
-    def __init__(self, running_on_wireless: bool = False) -> None:
-        """Build the app and register the settings routes before the server serves.
-
-        The base class builds ``self.settings_app`` here and ``wrapped_run`` starts
-        its web-server thread *before* it calls :meth:`run`. Registering the config
-        routes inside ``run`` (as this once did) therefore leaves a window — the
-        whole time the robot spends connecting to the daemon before ``run`` begins —
-        during which the server is already accepting requests but ``/llm-config``
-        does not exist yet, so the dashboard's on-load fetch races ahead of the
-        route and gets a 404. Registering them now, at construction, closes that
-        window: the routes are on the app before the first request can arrive.
-        """
-        super().__init__(running_on_wireless)
-        self._register_settings_routes()
-
-    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
-        """Construct the real engines and hand them to the orchestrator.
-
-        Opens the camera and microphone for the app's lifetime (released on
-        return), builds whatever recognition, conversation, and speech engines the
-        machine can provide, and lets :class:`ChittiOS` compose and run them until
-        the daemon sets ``stop_event``.
-        """
-        logging.basicConfig(level=logging.INFO)
-        body = ReachyMiniAdapter(reachy_mini)
-        store = EnrollmentStore(STORE_PATH, _resolve_store_key())
-        tts = self._build_tts()
-
-        with ExitStack() as sources:
-            # The camera and microphone are shared: on an empty store only
-            # onboarding reads them, on a populated one only perception does, and
-            # the two paths never run together — so one source each, not two
-            # fighting over an exclusive device.
-            #
-            # The camera comes from the SDK, not OpenCV: on the robot the daemon
-            # owns the Orbbec and streams frames over a GStreamer IPC endpoint, so
-            # a direct ``cv2.VideoCapture(0)`` fails ("could not open camera 0").
-            # ``reachy_mini.media.get_frame()`` is how an app gets frames while the
-            # daemon holds the device, and it already returns exactly the BGR
-            # frames the perception loop expects.
-            camera: CameraSource = (
-                _guard("camera", lambda: ReachyMiniCameraSource(reachy_mini.media)) or _NullCamera()
-            )
-            mic: MicSource = (
-                _guard("microphone", lambda: sources.enter_context(SoundDeviceMicSource()))
-                or _NullMic()
-            )
-            # The heavy recognition models, built once and shared by perception and
-            # onboarding so neither boot path pays to load them twice.
-            detector = YuNetDetector()
-            segmenter = OnnxVadSegmenter()
-            face_embedder = SFaceEmbedder()
-            # Voice identification is the one torch-backed engine left on this
-            # path: ECAPA pulls speechbrain and torch (~2 GB), which do not fit the
-            # Reachy Mini. Behind _guard it degrades to None when they are absent —
-            # recognition then runs on the face alone (_NullVoiceProvider) and the
-            # first-boot sitting enrols face-only. On a dev box with the `voice`
-            # extra installed it builds as before and voice-ID is fully live.
-            voice_embedder = _guard("voice identification (ECAPA)", ECAPAEmbedder)
-            # ``tiny.en`` rather than ``base``: on this SBC's CPU, ``base`` spends
-            # ~12 s decoding a 2 s turn, so utterances queue faster than they clear
-            # and a reply lands a minute late — unusable. The English-only ``tiny``
-            # is several times faster for a modest accuracy cost that short
-            # household turns tolerate well, keeping time-to-answer conversational.
-            #
-            # The ``.en`` build also *is* the language lock: forcing English keeps
-            # faster-whisper from auto-detecting per utterance, which on short,
-            # quiet turns — a name, a yes — has mis-fired to Italian on the robot
-            # and garbled every transcript. ``language="en"`` is kept as belt and
-            # braces. The core WhisperStt default stays language-agnostic; only the
-            # app pins the model and the language ChittiOS speaks.
-            stt = _guard("Whisper STT", lambda: WhisperStt("tiny.en", language="en"))
-
-            perception = self._build_perception(
-                store, camera, mic, detector, segmenter, face_embedder, voice_embedder
-            )
-            conversation = ConversationSeams(stt=stt, llm=_guard("LLM", self._build_llm))
-            onboarding = self._build_onboarding(
-                store=store,
-                body=body,
-                tts=tts,
-                reachy_mini=reachy_mini,
-                camera=camera,
-                mic=mic,
-                detector=detector,
-                segmenter=segmenter,
-                face_embedder=face_embedder,
-                voice_embedder=voice_embedder,
-                stt=stt,
-                stop_event=stop_event,
-            )
-
-            orchestrator = ChittiOS(
-                store=store,
-                perception=perception,
-                conversation=conversation,
-                tts=tts,
-                context=ContextManager(),
-                idle_motion=BreathingMotion(reachy_mini),
-                onboarding=onboarding,
-            )
-            orchestrator.run(body, stop_event=stop_event)
-
-        body.close()
-
-    def _build_llm(self) -> OpenAICompatibleLlm:
-        """Construct the conversation LLM from the household's resolved config.
-
-        The endpoint is not hardcoded: :func:`load_llm_config` resolves it from
-        the environment, then the config file the settings UI writes, then the
-        built-in default (the Spark's Gemma). Whatever comes back is where this
-        robot sends conversation transcripts — local by default, or wherever the
-        household pointed it. Built behind ``_guard`` in :meth:`run`, so a
-        malformed config or missing HTTP stack costs conversation and nothing else.
-        """
-        config = load_llm_config()
-        logger.info("LLM endpoint: %s (model %s)", config.base_url, config.model)
-        return OpenAICompatibleLlm(
-            base_url=config.base_url,
-            model=config.model,
-            api_key=config.api_key,
-        )
-
-    def _register_settings_routes(self) -> None:
-        """Add the LLM-endpoint settings routes to the dashboard's settings app.
-
-        The base class builds ``self.settings_app`` from ``custom_app_url`` and
-        serves ``static/index.html`` as the dashboard page; here we give that page
-        an API. ``GET /llm-config`` reports the resolved endpoint and whether a key
-        is set (never the key itself — a secret is not echoed back over HTTP);
-        ``POST /llm-config`` writes the household's choice to the config file.
-
-        Writes take effect on the next app start — there is no live client swap, by
-        design: rebuilding the conversation engine mid-turn is far more surface
-        area than the feature needs, so the contract is simply "restart to apply".
-        """
-        # The base class exposes ``settings_app`` untyped (reachy_mini ships no
-        # stubs); bind it to a concrete ``FastAPI`` local so its route decorators
-        # are typed rather than ``Any`` (which mypy rejects as an untyped decorator).
-        settings_app: FastAPI | None = self.settings_app
-        if settings_app is None:  # webserver disabled; nothing to wire.
-            return
-
-        @settings_app.get("/llm-config")
-        def get_llm_config() -> dict[str, object]:
-            """Report the resolved endpoint for the dashboard to display."""
-            config = load_llm_config()
-            return {
-                "base_url": config.base_url,
-                "model": config.model,
-                "has_api_key": config.api_key is not None,
-            }
-
-        @settings_app.post("/llm-config")
-        def set_llm_config(update: LlmSettingsUpdate) -> dict[str, object]:
-            """Persist the household's endpoint choice; applied on next start."""
-            current = load_llm_config()
-            if update.api_key is None:
-                api_key = current.api_key  # blank field: keep the stored key.
-            elif update.api_key == "":
-                api_key = None  # explicit clear.
-            else:
-                api_key = update.api_key  # a new key.
-            new_config = LlmConfig(
-                base_url=update.base_url.strip(),
-                model=update.model.strip(),
-                api_key=api_key,
-            )
-            write_llm_config(new_config)
-            logger.info("LLM settings saved; restart ChittiOS to apply")
-            return {
-                "base_url": new_config.base_url,
-                "model": new_config.model,
-                "has_api_key": new_config.api_key is not None,
-                "restart_required": True,
-            }
-
-    def _build_perception(
-        self,
-        store: EnrollmentStore,
-        camera: CameraSource,
-        mic: MicSource,
-        detector: FaceDetectorProtocol,
-        segmenter: SegmenterProtocol,
-        face_embedder: SFaceEmbedder,
-        voice_embedder: ECAPAEmbedder | None,
-    ) -> PerceptionSeams:
-        """Assemble the perception seams from the shared devices and models.
-
-        The recognition providers are built from the roster loaded out of the
-        store, so the household the robot recognises is exactly the one enrolled.
-        The camera and microphone arrive already opened (or as silent null
-        sources when a device could not be opened), so this only wires the
-        pipelines around them. When no speaker embedder is present (the robot,
-        where ECAPA does not fit) the voice provider degrades to a
-        :class:`_NullVoiceProvider` so recognition runs on the face alone.
-        """
-        face_provider = FaceIdentityProvider(face_embedder, roster.face_roster(store))
-        voice_provider: IdentityProvider[SpeechSegment] = (
-            VoiceIdentityProvider(voice_embedder, roster.voice_roster(store))
-            if voice_embedder is not None
-            else _NullVoiceProvider()
-        )
-
-        return PerceptionSeams(
-            face=FacePipeline(source=camera, detector=detector, provider=face_provider),
-            mic=mic,
-            segmenter=segmenter,
-            voice_provider=voice_provider,
-        )
-
-    def _build_onboarding(
-        self,
-        *,
-        store: EnrollmentStore,
-        body: ReachyMiniAdapter,
-        tts: TtsEngine,
-        reachy_mini: ReachyMini,
-        camera: CameraSource,
-        mic: MicSource,
-        detector: FaceDetectorProtocol,
-        segmenter: SegmenterProtocol,
-        face_embedder: SFaceEmbedder,
-        voice_embedder: ECAPAEmbedder | None,
-        stt: WhisperStt | None,
-        stop_event: threading.Event,
-    ) -> OwnerEnrollment:
-        """The first-boot ritual, wired from the shared seams — or a friendly fallback.
-
-        The whole spoken :class:`EnrollmentDialog` is assembled behind ``_guard``:
-        if any of its concrete ports cannot be built — no STT model, no keychain,
-        an unreadable device — the assembly degrades to :class:`_GreetAndIdleFallback`
-        rather than raising, so an empty store never leaves the robot exiting in
-        silence. The orchestrator drives whichever object comes back through the
-        same ``enroll_owner`` seam.
-        """
-        speech_out = SyncSpeechOut(body, tts)
-        dialog = _guard(
-            "voice onboarding",
-            lambda: self._assemble_dialog(
-                store=store,
-                speech_out=speech_out,
-                reachy_mini=reachy_mini,
-                camera=camera,
-                mic=mic,
-                detector=detector,
-                segmenter=segmenter,
-                face_embedder=face_embedder,
-                voice_embedder=voice_embedder,
-                stt=stt,
-                stop_event=stop_event,
-            ),
-        )
-        if dialog is not None:
-            return dialog
-
-        logger.info("voice onboarding is unavailable; the empty-store path will greet and idle")
-        return _GreetAndIdleFallback(speech_out)
-
-    def _assemble_dialog(
-        self,
-        *,
-        store: EnrollmentStore,
-        speech_out: SpeechOut,
-        reachy_mini: ReachyMini,
-        camera: CameraSource,
-        mic: MicSource,
-        detector: FaceDetectorProtocol,
-        segmenter: SegmenterProtocol,
-        face_embedder: SFaceEmbedder,
-        voice_embedder: ECAPAEmbedder | None,
-        stt: WhisperStt | None,
-        stop_event: threading.Event,
-    ) -> EnrollmentDialog:
-        """Wire the concrete ports into the spoken enrollment dialog.
-
-        Raises if any hard requirement is missing (STT is the one that can be
-        absent on a fresh install); the caller guards this, turning that raise
-        into the greet-and-idle fallback.
-
-        Voice *enrollment* follows voice identification: with no speaker embedder
-        (the robot) the sitting runs face-only — ``enroll_voice=False``, and the
-        factory holds a never-called :class:`_NullVoiceEmbedder` so its wiring is
-        uniform. Name and face capture, the antenna gate, and the passphrase
-        custody are unchanged, so a household is still fully enrolled by voice on
-        the robot; only the biometric *voice print* is omitted.
-
-        The owner-hold wait is wired to ``stop_event`` (``should_abort``) so a
-        daemon shutdown while the robot is waiting for the antenna hold is honoured
-        promptly rather than only after the wait's timeout elapses.
-        """
-        if stt is None:
-            raise RuntimeError("voice onboarding needs Whisper STT to hear names and answers")
-
-        # On first boot the identity runtime does not exist yet, so recognition
-        # reports a guest (no one recognised) — correct for the owner bootstrap,
-        # which is gated on the antenna hold, not on a vouch.
-        recognizer = SessionRecognizer(Session.guest)
-        enroll_voice = voice_embedder is not None
-        return EnrollmentDialog(
-            speech_out=speech_out,
-            speech_in=WhisperSpeechIn(mic, segmenter, stt),
-            name_recorder=MicNameRecorder(mic, segmenter),
-            recognizer=recognizer,
-            gate=AuthorityGate(AntennaHoldSignal(reachy_mini), recognizer),
-            conductor=CaptureConductor(speech_out),
-            custody=PassphraseCustody(VAULT_PATH),
-            store=store,
-            face_source=PullFaceSource(camera, detector),
-            voice_source=PullVoiceSource(mic, segmenter),
-            enrollers=ModelEnrollerFactory(face_embedder, voice_embedder or _NullVoiceEmbedder()),
-            should_abort=stop_event.is_set,
-            enroll_voice=enroll_voice,
-            # No spoken setup passphrase: it only fed the (fragile, STT-based)
-            # recovery vault; the store is keyed by the on-device FileKeyStore.
-            # Setup is antenna hold -> face + name -> done.
-            require_passphrase=False,
-        )
-
-    def _build_tts(self) -> TtsEngine:
-        """The speech engine — Piper when a voice model is present, else the stub.
-
-        TTS is the one engine the orchestrator cannot do without: greeting has to
-        have a voice. So a missing Piper model degrades to the deterministic tone
-        rather than to ``None`` — a plain-spoken robot instead of a mute one.
-        """
-        model = next((p for p in (_BUNDLED_VOICE, _USER_VOICE) if p.exists()), None)
-        if model is not None:
-            engine = _guard(
-                "Piper TTS",
-                lambda: PiperTtsEngine(str(model), config_path=f"{model}.json"),
-            )
-            if engine is not None:
-                return engine
-        logger.info("no Piper voice model available; using the stub tone voice")
-        return StubTtsEngine()
-
-
-if __name__ == "__main__":
-    app = Chittios()
-    try:
-        app.wrapped_run()
-    except KeyboardInterrupt:
-        app.stop()
+"""ChittiOS — the Reachy Mini app shell (Phase 7: the composed OS).
+
+Phase 1 proved the publish → install → run pipeline with a greeting and idle
+breathing. This is the real app: a thin shell that constructs the *concrete*,
+hardware- and model-backed engines and hands them to ``chittios_core``'s
+:class:`~chittios_core.orchestrator.ChittiOS`, which owns every line of composition
+logic. Nothing here decides *what* ChittiOS does — it only supplies the real body,
+the real camera and microphone, and the real STT/LLM/TTS to the seams the
+orchestrator drives, exactly where a test supplies stubs.
+
+Thin, and gracefully degrading
+------------------------------
+Every heavy engine is optional: a fresh SBC may lack a Piper voice, a Whisper
+model, or a reachable LLM, and the household should still get a robot that
+recognises them and says hello rather than one that refuses to boot. So each
+engine is built behind a small guarded factory that returns ``None`` (or a stub
+fallback for the one engine — TTS — the greeting cannot do without) when its
+dependency or device is absent. A missing LLM costs conversation and nothing
+else; perception, greeting, and idle motion run regardless.
+
+Idle breathing stays a raw-SDK control loop
+--------------------------------------------
+The "alive" breathing is the one thing that cannot go through the HAL motion
+primitives: it needs ``set_target`` at a fixed 60 Hz (repeated ``goto_target``
+each restart the interpolation — the judder Phase 1 diagnosed). So it stays here,
+against the raw SDK, wrapped as an :class:`IdleMotion` the orchestrator runs on
+its own thread — the reference control loop, unchanged, just handed to the
+composition instead of being ``run``'s only body.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from collections.abc import Callable
+from contextlib import ExitStack
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TypeVar
+
+import numpy as np
+from fastapi import FastAPI
+from numpy.typing import NDArray
+from pydantic import BaseModel
+from reachy_mini import ReachyMini, ReachyMiniApp
+from reachy_mini.utils import create_head_pose
+
+from chittios_core.context import ContextManager
+from chittios_core.conversation.config import LlmConfig, load_llm_config, write_llm_config
+from chittios_core.conversation.llm import OpenAICompatibleLlm
+from chittios_core.conversation.stt import WhisperStt
+from chittios_core.conversation.vad import OnnxVadSegmenter
+from chittios_core.expression.config import VoiceConfig, load_voice_config, write_voice_config
+from chittios_core.expression.elevenlabs import ElevenLabsTtsEngine
+from chittios_core.expression.tts import (
+    FallbackTtsEngine,
+    PiperTtsEngine,
+    StubTtsEngine,
+    TtsEngine,
+)
+from chittios_core.identity import roster
+from chittios_core.identity.face.detector import FaceDetectorProtocol, YuNetDetector
+from chittios_core.identity.face.embedder import SFaceEmbedder
+from chittios_core.identity.face.provider import FaceIdentityProvider
+from chittios_core.identity.onboarding.adapters import (
+    AntennaHoldSignal,
+    MicNameRecorder,
+    ModelEnrollerFactory,
+    PassphraseCustody,
+    PullFaceSource,
+    PullVoiceSource,
+    SyncSpeechOut,
+    WhisperSpeechIn,
+)
+from chittios_core.identity.onboarding.authority import AuthorityGate
+from chittios_core.identity.onboarding.conductor import CaptureConductor
+from chittios_core.identity.onboarding.dialog import (
+    DialogOutcome,
+    DialogResult,
+    EnrollmentDialog,
+)
+from chittios_core.identity.onboarding.ports import SessionRecognizer, SpeechOut
+from chittios_core.identity.session import Session
+from chittios_core.identity.store.enrollments import EnrollmentStore
+from chittios_core.identity.store.keys import (
+    FileKeyStore,
+    KeyCustodyError,
+    KeyringKeyStore,
+    get_or_create_key,
+)
+from chittios_core.identity.types import IdentityClaim, IdentityProvider, Modality
+from chittios_core.identity.voice.embedder import ECAPAEmbedder
+from chittios_core.identity.voice.provider import VoiceIdentityProvider
+from chittios_core.identity.voice.segmenter import SegmenterProtocol, SpeechSegment
+from chittios_core.orchestrator import (
+    ChittiOS,
+    ConversationSeams,
+    OwnerEnrollment,
+    PerceptionSeams,
+)
+from chittios_core.perception.loop import FacePipeline
+from chittios_core.perception.sources import (
+    CameraSource,
+    MicSource,
+    ReachyMiniCameraSource,
+    SoundDeviceMicSource,
+)
+from hal.reachy_mini.adapter import ReachyMiniAdapter
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T")
+
+#: Where the enrolled household lives on the robot. The store creates its parent.
+STORE_PATH = Path.home() / ".local" / "share" / "chittios" / "enrollments.db"
+
+#: Where the recoverable passphrase custody vault lives — the Argon2id-wrapped
+#: data key the recovery flow re-derives. Beside the store because a wrapped key
+#: is ciphertext, useless without the household passphrase (see vault.py).
+VAULT_PATH = Path.home() / ".local" / "share" / "chittios" / "passphrase.vault"
+
+#: Piper voice model. Prefer the one bundled with the app so a fresh robot speaks
+#: real words out of the box; fall back to a user-supplied model in the data dir.
+_BUNDLED_VOICE = Path(__file__).parent / "assets" / "voice.onnx"
+_USER_VOICE = Path.home() / ".local" / "share" / "chittios" / "voice.onnx"
+
+#: Spoken by the empty-store fallback when the robot cannot run onboarding —
+#: honest and warm rather than silent. The robot then idles (breathing) rather
+#: than exiting, so a household that unboxes it into a half-provisioned state
+#: still meets something alive.
+ONBOARDING_UNAVAILABLE_GREETING = (
+    "Hello. I'm not quite ready to set up your household yet, but I'm here with you."
+)
+
+# ── idle breathing (the reference 60 Hz control loop) ──────────────────────
+
+#: Control-loop rate. The fleet app uses 60 Hz; the docs floor smoothness at
+#: 30 Hz. One ``set_target`` per tick, period held by adaptive sleep.
+CONTROL_FREQUENCY_HZ = 60.0
+CONTROL_PERIOD_S = 1.0 / CONTROL_FREQUENCY_HZ
+
+#: Idle "breathing": the target pose is a smooth sine of time (not discrete
+#: commands). Amplitudes kept small and slow, matching the reference breathing.
+BREATHING_PITCH_DEG = 3.0
+BREATHING_PITCH_HZ = 0.2
+LOOK_YAW_DEG = 8.0
+LOOK_YAW_HZ = 0.05
+
+
+class BreathingMotion:
+    """The idle "alive" motion, as an :class:`IdleMotion` the orchestrator runs.
+
+    The Phase 1 control loop, unchanged in substance: one ``set_target`` per tick
+    at a monotonic-aligned 60 Hz, the pose a smooth sine of time. It lives against
+    the raw SDK rather than the HAL because it needs ``set_target``'s immediacy —
+    the HAL's queued ``goto_target`` would restart interpolation every tick and
+    judder. The orchestrator runs this on its own thread and stops it with the same
+    event that stops everything else.
+
+    Args:
+        mini: The connected robot to drive.
+    """
+
+    def __init__(self, mini: ReachyMini) -> None:
+        self._mini = mini
+
+    def run(self, stop: threading.Event) -> None:
+        """Breathe until ``stop`` is set, then return."""
+        start = time.monotonic()
+        while not stop.is_set():
+            tick_start = time.monotonic()
+            elapsed = tick_start - start
+
+            pitch_deg = BREATHING_PITCH_DEG * np.sin(2.0 * np.pi * BREATHING_PITCH_HZ * elapsed)
+            yaw_deg = LOOK_YAW_DEG * np.sin(2.0 * np.pi * LOOK_YAW_HZ * elapsed)
+            self._mini.set_target(head=create_head_pose(pitch=pitch_deg, yaw=yaw_deg, degrees=True))
+
+            # Adaptive sleep holds the period regardless of per-tick cost; the
+            # event doubles as an interruptible sleep, so a stop returns at once.
+            sleep_s = max(0.0, CONTROL_PERIOD_S - (time.monotonic() - tick_start))
+            if stop.wait(sleep_s):
+                break
+
+
+class _GreetAndIdleFallback:
+    """The empty-store path when onboarding genuinely cannot be assembled.
+
+    An unboxed robot has an empty store and, normally, runs the spoken owner
+    enrollment. But if the pieces that ritual needs — a working microphone, the
+    voice models, the vault — cannot be built, the honest failure is not to exit
+    silently (a robot that does nothing looks broken) but to *say so* and stay
+    alive. Staying alive is the orchestrator's job now: it breathes on its own
+    thread and offers ``enroll_owner`` again on a cadence for the whole empty-store
+    lifetime, so this only owes a single greeting. It says its line the first time
+    it is offered and returns ``FAILED``; subsequent offers return ``FAILED``
+    silently, so the robot breathes on quietly rather than repeating itself.
+
+    It satisfies :class:`OwnerEnrollment` structurally, so the orchestrator drives
+    it through exactly the same ``enroll_owner`` seam it drives the real dialog
+    through — the orchestrator's own empty-store semantics are untouched; only
+    *what* is wired into that seam differs when the dialog could not be built.
+
+    Args:
+        speech_out: How the greeting is spoken (the same sync TTS seam the dialog
+            would have used).
+        greeting: The single line spoken on the first offer.
+    """
+
+    def __init__(
+        self,
+        speech_out: SpeechOut,
+        *,
+        greeting: str = ONBOARDING_UNAVAILABLE_GREETING,
+    ) -> None:
+        self._speech_out = speech_out
+        self._greeting = greeting
+        self._greeted = False
+
+    def enroll_owner(self) -> DialogResult:
+        """Greet on the first offer, then stay quiet. Nothing is ever enrolled."""
+        if not self._greeted:
+            self._greeted = True
+            try:
+                self._speech_out.speak(self._greeting)
+            except Exception:
+                logger.warning("the fallback greeting could not be spoken", exc_info=True)
+        return DialogResult(DialogOutcome.FAILED)
+
+
+# ── null sources (degrade when a device is absent) ─────────────────────────
+
+
+class _NullCamera:
+    """A :class:`CameraSource` that always sees nothing.
+
+    Used when no camera can be opened: perception then runs on voice alone rather
+    than failing to start. A returned ``None`` is the source contract's ordinary
+    "nothing right now", so the loop simply never gets a face.
+    """
+
+    def read(self) -> None:
+        return None
+
+
+class _NullMic:
+    """A :class:`MicSource` that always hears nothing — the audio counterpart."""
+
+    def read(self) -> None:
+        return None
+
+
+class _NullVoiceProvider:
+    """A voice :class:`IdentityProvider` that recognises no one — face-only builds.
+
+    The speaker encoder (ECAPA) is torch- and speechbrain-backed, ~2 GB that does
+    not fit on the Reachy Mini, so voice **identification** is dropped on the
+    robot (the owner's call). Perception still segments audio — the conversation
+    loop needs those utterances for STT — but the voice *provider* it drives is
+    this: every utterance returns an unknown claim, exactly as the real provider
+    does for anyone unenrolled, so the fusion and authorization paths downstream
+    are unchanged and simply never receive a voice match. Recognition runs on the
+    face alone.
+
+    It satisfies :class:`~chittios_core.identity.types.IdentityProvider`\\
+    ``[SpeechSegment]`` structurally, so it drops into the same perception seam
+    the real provider fills, and it constructs nothing torch-backed.
+    """
+
+    @property
+    def modality(self) -> Modality:
+        return Modality.VOICE
+
+    def identify(
+        self, observation: SpeechSegment, /, *, observed_at: datetime | None = None
+    ) -> IdentityClaim:
+        """Return an unknown voice claim for any utterance — no one is identified."""
+        return IdentityClaim.unknown(
+            modality=Modality.VOICE, observed_at=observed_at or datetime.now(UTC)
+        )
+
+
+class _NullVoiceEmbedder:
+    """A voice embedder that is never called — the placeholder for face-only sittings.
+
+    ``ModelEnrollerFactory`` holds a voice embedder so it can mint voice enrollers,
+    but a face-only enrollment (``enroll_voice=False``) never asks it for one, so
+    this stand-in is only ever *held*, never *invoked*. It exists so the factory's
+    wiring is uniform whether or not a speaker encoder is present, without
+    constructing the torch-backed ECAPA on a robot that cannot run it. Being
+    called would mean a face-only sitting tried to embed voice after all, which is
+    a wiring bug worth failing loudly on rather than papering over with a vector.
+    """
+
+    def embed(self, canonical_audio: NDArray[np.float32], /) -> NDArray[np.float32]:
+        raise NotImplementedError(
+            "voice enrollment is disabled on this build; _NullVoiceEmbedder must never be called"
+        )
+
+
+def _guard(what: str, build: Callable[[], _T]) -> _T | None:
+    """Build an optional engine, degrading to ``None`` if its runtime is absent.
+
+    The one place the "a missing model must not stop the robot booting" rule is
+    enforced: any failure to construct — a missing package, an absent model file,
+    an unopenable device — is logged and turned into ``None`` rather than raised.
+    """
+    try:
+        return build()
+    except Exception:
+        logger.warning("%s is unavailable; ChittiOS will run without it", what, exc_info=True)
+        return None
+
+
+def _resolve_store_key() -> bytes:
+    """The enrollment store's encryption key: OS keychain where one exists, else a
+    mode-0600 key file on a headless Linux host.
+
+    The robot is headless Linux with no login keyring, so ``KeyringKeyStore``
+    raises there. ``FileKeyStore`` keeps the key in a 0600 file beside the store —
+    weaker than a keychain (the key sits near the data it protects), but on a box
+    with no keychain it is that or no at-rest encryption at all. Windows and macOS
+    keep the keychain; ``FileKeyStore`` is POSIX-only, so this only falls back on
+    a POSIX host.
+    """
+    try:
+        return get_or_create_key(KeyringKeyStore())
+    except KeyCustodyError:
+        if os.name != "posix":
+            raise
+        key_dir = STORE_PATH.parent
+        key_dir.mkdir(parents=True, exist_ok=True)
+        logger.warning("no OS keychain available; using a 0600 key file in %s", key_dir)
+        return get_or_create_key(FileKeyStore(key_dir))
+
+
+class LlmSettingsUpdate(BaseModel):
+    """The dashboard's ``POST /llm-config`` body — the three settings, plus key semantics.
+
+    ``api_key`` distinguishes three intents a single password field cannot
+    otherwise express: ``None`` (field left blank) leaves the stored key
+    untouched, an empty string clears it, and any other string sets it — so
+    changing the URL never silently drops a previously saved key.
+
+    Defined at module scope, not inside :meth:`Chittios._register_settings_routes`,
+    on purpose: this module uses ``from __future__ import annotations`` (PEP 563),
+    so the route handler's ``update: LlmSettingsUpdate`` annotation is a *string*
+    that FastAPI resolves with :func:`typing.get_type_hints` against the module's
+    globals. A method-local class is not in those globals, so the annotation
+    fails to resolve to this Pydantic model and FastAPI falls back to treating
+    ``update`` as a required *query* parameter — which no JSON body can satisfy,
+    yielding ``422 Unprocessable Entity`` on every save. Keeping the model here,
+    where ``get_type_hints`` can find it, is what makes the body bind.
+    """
+
+    base_url: str
+    model: str
+    api_key: str | None = None
+
+
+class VoiceSettingsUpdate(BaseModel):
+    """The dashboard's ``POST /voice-config`` body — just the ElevenLabs key.
+
+    The same three-way ``api_key`` contract as :class:`LlmSettingsUpdate`: ``None``
+    (a blank field) keeps the stored key, ``""`` clears it, and any other string
+    sets it — so a household never loses a saved key by revisiting the page. The
+    voice and model are not surfaced in the UI (a warm premade voice is the
+    default), so they are not part of this body. Defined at module scope for the
+    same PEP 563 reason spelled out on :class:`LlmSettingsUpdate`: FastAPI must be
+    able to resolve the annotation against the module globals for the JSON body to
+    bind instead of degrading to a 422.
+    """
+
+    api_key: str | None = None
+
+
+class Chittios(ReachyMiniApp):  # type: ignore[misc]  # reachy_mini ships no stubs; base resolves to Any
+    # A small settings web UI, served by the daemon on this URL, lets a household
+    # point ChittiOS at their own LLM endpoint from the robot dashboard. The base
+    # class builds ``self.settings_app`` (a FastAPI app) from this URL; we add the
+    # config routes in ``run``. ``0.0.0.0`` so the dashboard reaches it over the LAN.
+    custom_app_url: str | None = "http://0.0.0.0:8042"
+    request_media_backend: str | None = None
+
+    def __init__(self, running_on_wireless: bool = False) -> None:
+        """Build the app and register the settings routes before the server serves.
+
+        The base class builds ``self.settings_app`` here and ``wrapped_run`` starts
+        its web-server thread *before* it calls :meth:`run`. Registering the config
+        routes inside ``run`` (as this once did) therefore leaves a window — the
+        whole time the robot spends connecting to the daemon before ``run`` begins —
+        during which the server is already accepting requests but ``/llm-config``
+        does not exist yet, so the dashboard's on-load fetch races ahead of the
+        route and gets a 404. Registering them now, at construction, closes that
+        window: the routes are on the app before the first request can arrive.
+        """
+        super().__init__(running_on_wireless)
+        self._register_settings_routes()
+
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
+        """Construct the real engines and hand them to the orchestrator.
+
+        Opens the camera and microphone for the app's lifetime (released on
+        return), builds whatever recognition, conversation, and speech engines the
+        machine can provide, and lets :class:`ChittiOS` compose and run them until
+        the daemon sets ``stop_event``.
+        """
+        logging.basicConfig(level=logging.INFO)
+        body = ReachyMiniAdapter(reachy_mini)
+        store = EnrollmentStore(STORE_PATH, _resolve_store_key())
+        tts = self._build_tts()
+
+        with ExitStack() as sources:
+            # The camera and microphone are shared: on an empty store only
+            # onboarding reads them, on a populated one only perception does, and
+            # the two paths never run together — so one source each, not two
+            # fighting over an exclusive device.
+            #
+            # The camera comes from the SDK, not OpenCV: on the robot the daemon
+            # owns the Orbbec and streams frames over a GStreamer IPC endpoint, so
+            # a direct ``cv2.VideoCapture(0)`` fails ("could not open camera 0").
+            # ``reachy_mini.media.get_frame()`` is how an app gets frames while the
+            # daemon holds the device, and it already returns exactly the BGR
+            # frames the perception loop expects.
+            camera: CameraSource = (
+                _guard("camera", lambda: ReachyMiniCameraSource(reachy_mini.media)) or _NullCamera()
+            )
+            mic: MicSource = (
+                _guard("microphone", lambda: sources.enter_context(SoundDeviceMicSource()))
+                or _NullMic()
+            )
+            # The heavy recognition models, built once and shared by perception and
+            # onboarding so neither boot path pays to load them twice.
+            detector = YuNetDetector()
+            segmenter = OnnxVadSegmenter()
+            face_embedder = SFaceEmbedder()
+            # Voice identification is the one torch-backed engine left on this
+            # path: ECAPA pulls speechbrain and torch (~2 GB), which do not fit the
+            # Reachy Mini. Behind _guard it degrades to None when they are absent —
+            # recognition then runs on the face alone (_NullVoiceProvider) and the
+            # first-boot sitting enrols face-only. On a dev box with the `voice`
+            # extra installed it builds as before and voice-ID is fully live.
+            voice_embedder = _guard("voice identification (ECAPA)", ECAPAEmbedder)
+            # ``tiny.en`` rather than ``base``: on this SBC's CPU, ``base`` spends
+            # ~12 s decoding a 2 s turn, so utterances queue faster than they clear
+            # and a reply lands a minute late — unusable. The English-only ``tiny``
+            # is several times faster for a modest accuracy cost that short
+            # household turns tolerate well, keeping time-to-answer conversational.
+            #
+            # The ``.en`` build also *is* the language lock: forcing English keeps
+            # faster-whisper from auto-detecting per utterance, which on short,
+            # quiet turns — a name, a yes — has mis-fired to Italian on the robot
+            # and garbled every transcript. ``language="en"`` is kept as belt and
+            # braces. The core WhisperStt default stays language-agnostic; only the
+            # app pins the model and the language ChittiOS speaks.
+            stt = _guard("Whisper STT", lambda: WhisperStt("tiny.en", language="en"))
+
+            perception = self._build_perception(
+                store, camera, mic, detector, segmenter, face_embedder, voice_embedder
+            )
+            conversation = ConversationSeams(stt=stt, llm=_guard("LLM", self._build_llm))
+            onboarding = self._build_onboarding(
+                store=store,
+                body=body,
+                tts=tts,
+                reachy_mini=reachy_mini,
+                camera=camera,
+                mic=mic,
+                detector=detector,
+                segmenter=segmenter,
+                face_embedder=face_embedder,
+                voice_embedder=voice_embedder,
+                stt=stt,
+                stop_event=stop_event,
+            )
+
+            orchestrator = ChittiOS(
+                store=store,
+                perception=perception,
+                conversation=conversation,
+                tts=tts,
+                context=ContextManager(),
+                idle_motion=BreathingMotion(reachy_mini),
+                onboarding=onboarding,
+            )
+            orchestrator.run(body, stop_event=stop_event)
+
+        body.close()
+
+    def _build_llm(self) -> OpenAICompatibleLlm:
+        """Construct the conversation LLM from the household's resolved config.
+
+        The endpoint is not hardcoded: :func:`load_llm_config` resolves it from
+        the environment, then the config file the settings UI writes, then the
+        built-in default (the Spark's Gemma). Whatever comes back is where this
+        robot sends conversation transcripts — local by default, or wherever the
+        household pointed it. Built behind ``_guard`` in :meth:`run`, so a
+        malformed config or missing HTTP stack costs conversation and nothing else.
+        """
+        config = load_llm_config()
+        logger.info("LLM endpoint: %s (model %s)", config.base_url, config.model)
+        return OpenAICompatibleLlm(
+            base_url=config.base_url,
+            model=config.model,
+            api_key=config.api_key,
+        )
+
+    def _register_settings_routes(self) -> None:
+        """Add the LLM-endpoint settings routes to the dashboard's settings app.
+
+        The base class builds ``self.settings_app`` from ``custom_app_url`` and
+        serves ``static/index.html`` as the dashboard page; here we give that page
+        an API. ``GET /llm-config`` reports the resolved endpoint and whether a key
+        is set (never the key itself — a secret is not echoed back over HTTP);
+        ``POST /llm-config`` writes the household's choice to the config file.
+
+        Writes take effect on the next app start — there is no live client swap, by
+        design: rebuilding the conversation engine mid-turn is far more surface
+        area than the feature needs, so the contract is simply "restart to apply".
+        """
+        # The base class exposes ``settings_app`` untyped (reachy_mini ships no
+        # stubs); bind it to a concrete ``FastAPI`` local so its route decorators
+        # are typed rather than ``Any`` (which mypy rejects as an untyped decorator).
+        settings_app: FastAPI | None = self.settings_app
+        if settings_app is None:  # webserver disabled; nothing to wire.
+            return
+
+        @settings_app.get("/llm-config")
+        def get_llm_config() -> dict[str, object]:
+            """Report the resolved endpoint for the dashboard to display."""
+            config = load_llm_config()
+            return {
+                "base_url": config.base_url,
+                "model": config.model,
+                "has_api_key": config.api_key is not None,
+            }
+
+        @settings_app.post("/llm-config")
+        def set_llm_config(update: LlmSettingsUpdate) -> dict[str, object]:
+            """Persist the household's endpoint choice; applied on next start."""
+            current = load_llm_config()
+            if update.api_key is None:
+                api_key = current.api_key  # blank field: keep the stored key.
+            elif update.api_key == "":
+                api_key = None  # explicit clear.
+            else:
+                api_key = update.api_key  # a new key.
+            new_config = LlmConfig(
+                base_url=update.base_url.strip(),
+                model=update.model.strip(),
+                api_key=api_key,
+            )
+            write_llm_config(new_config)
+            logger.info("LLM settings saved; restart ChittiOS to apply")
+            return {
+                "base_url": new_config.base_url,
+                "model": new_config.model,
+                "has_api_key": new_config.api_key is not None,
+                "restart_required": True,
+            }
+
+        @settings_app.get("/voice-config")
+        def get_voice_config() -> dict[str, object]:
+            """Report whether a cloud voice is configured — never the key itself.
+
+            The dashboard uses this to decide whether to show the key box at all:
+            once a key is stored it hides the field, so onboarding asks once and
+            never again.
+            """
+            config = load_voice_config()
+            return {"has_api_key": config.api_key is not None}
+
+        @settings_app.post("/voice-config")
+        def set_voice_config(update: VoiceSettingsUpdate) -> dict[str, object]:
+            """Persist the household's ElevenLabs key; applied on next start."""
+            current = load_voice_config()
+            if update.api_key is None:
+                api_key = current.api_key  # blank field: keep the stored key.
+            elif update.api_key.strip() == "":
+                api_key = None  # explicit clear (empty, or whitespace only).
+            else:
+                api_key = update.api_key.strip()  # a new key.
+            new_config = VoiceConfig(
+                api_key=api_key,
+                voice_id=current.voice_id,
+                model_id=current.model_id,
+            )
+            write_voice_config(new_config)
+            logger.info("voice settings saved; restart ChittiOS to apply")
+            return {"has_api_key": new_config.api_key is not None, "restart_required": True}
+
+    def _build_perception(
+        self,
+        store: EnrollmentStore,
+        camera: CameraSource,
+        mic: MicSource,
+        detector: FaceDetectorProtocol,
+        segmenter: SegmenterProtocol,
+        face_embedder: SFaceEmbedder,
+        voice_embedder: ECAPAEmbedder | None,
+    ) -> PerceptionSeams:
+        """Assemble the perception seams from the shared devices and models.
+
+        The recognition providers are built from the roster loaded out of the
+        store, so the household the robot recognises is exactly the one enrolled.
+        The camera and microphone arrive already opened (or as silent null
+        sources when a device could not be opened), so this only wires the
+        pipelines around them. When no speaker embedder is present (the robot,
+        where ECAPA does not fit) the voice provider degrades to a
+        :class:`_NullVoiceProvider` so recognition runs on the face alone.
+        """
+        face_provider = FaceIdentityProvider(face_embedder, roster.face_roster(store))
+        voice_provider: IdentityProvider[SpeechSegment] = (
+            VoiceIdentityProvider(voice_embedder, roster.voice_roster(store))
+            if voice_embedder is not None
+            else _NullVoiceProvider()
+        )
+
+        return PerceptionSeams(
+            face=FacePipeline(source=camera, detector=detector, provider=face_provider),
+            mic=mic,
+            segmenter=segmenter,
+            voice_provider=voice_provider,
+        )
+
+    def _build_onboarding(
+        self,
+        *,
+        store: EnrollmentStore,
+        body: ReachyMiniAdapter,
+        tts: TtsEngine,
+        reachy_mini: ReachyMini,
+        camera: CameraSource,
+        mic: MicSource,
+        detector: FaceDetectorProtocol,
+        segmenter: SegmenterProtocol,
+        face_embedder: SFaceEmbedder,
+        voice_embedder: ECAPAEmbedder | None,
+        stt: WhisperStt | None,
+        stop_event: threading.Event,
+    ) -> OwnerEnrollment:
+        """The first-boot ritual, wired from the shared seams — or a friendly fallback.
+
+        The whole spoken :class:`EnrollmentDialog` is assembled behind ``_guard``:
+        if any of its concrete ports cannot be built — no STT model, no keychain,
+        an unreadable device — the assembly degrades to :class:`_GreetAndIdleFallback`
+        rather than raising, so an empty store never leaves the robot exiting in
+        silence. The orchestrator drives whichever object comes back through the
+        same ``enroll_owner`` seam.
+        """
+        speech_out = SyncSpeechOut(body, tts)
+        dialog = _guard(
+            "voice onboarding",
+            lambda: self._assemble_dialog(
+                store=store,
+                speech_out=speech_out,
+                reachy_mini=reachy_mini,
+                camera=camera,
+                mic=mic,
+                detector=detector,
+                segmenter=segmenter,
+                face_embedder=face_embedder,
+                voice_embedder=voice_embedder,
+                stt=stt,
+                stop_event=stop_event,
+            ),
+        )
+        if dialog is not None:
+            return dialog
+
+        logger.info("voice onboarding is unavailable; the empty-store path will greet and idle")
+        return _GreetAndIdleFallback(speech_out)
+
+    def _assemble_dialog(
+        self,
+        *,
+        store: EnrollmentStore,
+        speech_out: SpeechOut,
+        reachy_mini: ReachyMini,
+        camera: CameraSource,
+        mic: MicSource,
+        detector: FaceDetectorProtocol,
+        segmenter: SegmenterProtocol,
+        face_embedder: SFaceEmbedder,
+        voice_embedder: ECAPAEmbedder | None,
+        stt: WhisperStt | None,
+        stop_event: threading.Event,
+    ) -> EnrollmentDialog:
+        """Wire the concrete ports into the spoken enrollment dialog.
+
+        Raises if any hard requirement is missing (STT is the one that can be
+        absent on a fresh install); the caller guards this, turning that raise
+        into the greet-and-idle fallback.
+
+        Voice *enrollment* follows voice identification: with no speaker embedder
+        (the robot) the sitting runs face-only — ``enroll_voice=False``, and the
+        factory holds a never-called :class:`_NullVoiceEmbedder` so its wiring is
+        uniform. Name and face capture, the antenna gate, and the passphrase
+        custody are unchanged, so a household is still fully enrolled by voice on
+        the robot; only the biometric *voice print* is omitted.
+
+        The owner-hold wait is wired to ``stop_event`` (``should_abort``) so a
+        daemon shutdown while the robot is waiting for the antenna hold is honoured
+        promptly rather than only after the wait's timeout elapses.
+        """
+        if stt is None:
+            raise RuntimeError("voice onboarding needs Whisper STT to hear names and answers")
+
+        # On first boot the identity runtime does not exist yet, so recognition
+        # reports a guest (no one recognised) — correct for the owner bootstrap,
+        # which is gated on the antenna hold, not on a vouch.
+        recognizer = SessionRecognizer(Session.guest)
+        enroll_voice = voice_embedder is not None
+        return EnrollmentDialog(
+            speech_out=speech_out,
+            speech_in=WhisperSpeechIn(mic, segmenter, stt),
+            name_recorder=MicNameRecorder(mic, segmenter),
+            recognizer=recognizer,
+            gate=AuthorityGate(AntennaHoldSignal(reachy_mini), recognizer),
+            conductor=CaptureConductor(speech_out),
+            custody=PassphraseCustody(VAULT_PATH),
+            store=store,
+            face_source=PullFaceSource(camera, detector),
+            voice_source=PullVoiceSource(mic, segmenter),
+            enrollers=ModelEnrollerFactory(face_embedder, voice_embedder or _NullVoiceEmbedder()),
+            should_abort=stop_event.is_set,
+            enroll_voice=enroll_voice,
+            # No spoken setup passphrase: it only fed the (fragile, STT-based)
+            # recovery vault; the store is keyed by the on-device FileKeyStore.
+            # Setup is antenna hold -> face + name -> done.
+            require_passphrase=False,
+        )
+
+    def _build_tts(self) -> TtsEngine:
+        """The speech engine: the household's cloud voice when configured, else local.
+
+        A configured ElevenLabs key (from ``ELEVENLABS_API_KEY`` or the settings
+        file the onboarding box writes) builds the cloud engine, wrapped so a
+        failure — a bad key, an exhausted quota, a dropped connection — falls back
+        to the local voice rather than muting the robot. No key means the local
+        voice outright. The local engine is always built first, precisely so it is
+        there to be the fallback.
+        """
+        local = self._build_local_tts()
+        voice = load_voice_config()
+        key = voice.api_key
+        if key is not None:
+            cloud = _guard(
+                "ElevenLabs TTS",
+                lambda: ElevenLabsTtsEngine(
+                    key, voice_id=voice.voice_id, model_id=voice.model_id
+                ),
+            )
+            if cloud is not None:
+                logger.info(
+                    "ElevenLabs voice enabled (voice %s, model %s); local voice is the fallback",
+                    voice.voice_id,
+                    voice.model_id,
+                )
+                return FallbackTtsEngine(cloud, fallback=local)
+        return local
+
+    def _build_local_tts(self) -> TtsEngine:
+        """The local speech engine — Piper when a voice model is present, else the stub.
+
+        TTS is the one engine the orchestrator cannot do without: greeting has to
+        have a voice. So a missing Piper model degrades to the deterministic tone
+        rather than to ``None`` — a plain-spoken robot instead of a mute one. This
+        is also the fallback the cloud voice degrades to, so it must never itself
+        return ``None``.
+        """
+        model = next((p for p in (_BUNDLED_VOICE, _USER_VOICE) if p.exists()), None)
+        if model is not None:
+            engine = _guard(
+                "Piper TTS",
+                lambda: PiperTtsEngine(str(model), config_path=f"{model}.json"),
+            )
+            if engine is not None:
+                return engine
+        logger.info("no Piper voice model available; using the stub tone voice")
+        return StubTtsEngine()
+
+
+if __name__ == "__main__":
+    app = Chittios()
+    try:
+        app.wrapped_run()
+    except KeyboardInterrupt:
+        app.stop()

chittios/static/index.html

@@ -46,6 +46,22 @@
                 </label>
             </label>
 
+            <div class="voice" id="voice-section">
+                <span class="label">Premium voice <span class="opt">optional</span></span>
+                <div id="voice-input-wrap">
+                    <input id="eleven-key" name="eleven_key" type="password" autocomplete="off"
+                        placeholder="Paste your ElevenLabs API key">
+                    <span class="hint">Gives ChittiOS a natural cloud voice (ElevenLabs) instead of the
+                        built-in one. Only the robot's <em>spoken reply</em> is sent for synthesis —
+                        never your family's microphone audio, which always stays on the device. Leave
+                        blank to keep the local voice.</span>
+                </div>
+                <p class="voice-on" id="voice-enabled" hidden>
+                    ✓ ElevenLabs voice enabled.
+                    <button type="button" id="replace-voice" class="linkish">Replace key</button>
+                </p>
+            </div>
+
             <div class="actions">
                 <button id="save-btn" type="submit">Save settings</button>
                 <span id="status" class="status" role="status" aria-live="polite"></span>

chittios/static/main.js

@@ -1,10 +1,13 @@
-// The ChittiOS settings page: read the current LLM endpoint, let the household
-// change it, and write it back. The API-key field is never pre-filled — the
-// server reports only whether a key is set, and a blank field leaves it as-is
-// (an explicit "Remove" checkbox clears it), so editing the URL can never
-// silently drop a saved key.
+// The ChittiOS settings page: read the current LLM endpoint and (optionally) an
+// ElevenLabs voice key, let the household change them, and write them back.
+//
+// Neither secret is ever pre-filled. The server reports only *whether* each key
+// is set. The LLM key field stays visible so it can be changed; the ElevenLabs
+// key box, by contrast, is shown until a key is stored and then hidden — onboard
+// once, don't ask again — with a "Replace key" link for the rare rotation.
 
 const CONFIG_ENDPOINT = "/llm-config";
+const VOICE_ENDPOINT = "/voice-config";
 
 const els = {
     form: document.getElementById("llm-form"),
@@ -15,6 +18,10 @@ const els = {
     keyHint: document.getElementById("key-hint"),
     saveBtn: document.getElementById("save-btn"),
     status: document.getElementById("status"),
+    elevenKey: document.getElementById("eleven-key"),
+    voiceInputWrap: document.getElementById("voice-input-wrap"),
+    voiceEnabled: document.getElementById("voice-enabled"),
+    replaceVoice: document.getElementById("replace-voice"),
 };
 
 function setStatus(message, kind) {
@@ -22,6 +29,8 @@ function setStatus(message, kind) {
     els.status.className = kind ? `status ${kind}` : "status";
 }
 
+// ── LLM endpoint ─────────────────────────────────────────────────────────
+
 // Reflect whether a key is currently stored, without ever revealing it.
 function reflectKeyState(hasApiKey) {
     els.apiKey.placeholder = hasApiKey
@@ -56,6 +65,48 @@ function resolveApiKey() {
     return typed.length > 0 ? typed : null;
 }
 
+// ── ElevenLabs voice ─────────────────────────────────────────────────────
+
+// Show the key box only until a key is stored; after that, show the confirmation
+// and hide the field — the "onboard once, don't ask again" behaviour.
+function reflectVoiceState(hasKey) {
+    els.voiceInputWrap.hidden = hasKey;
+    els.voiceEnabled.hidden = !hasKey;
+    if (hasKey) els.elevenKey.value = "";
+}
+
+async function loadVoiceConfig() {
+    try {
+        const resp = await fetch(VOICE_ENDPOINT);
+        if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+        const data = await resp.json();
+        reflectVoiceState(Boolean(data.has_api_key));
+    } catch (e) {
+        // A missing voice route (older build) just means no cloud voice — leave
+        // the box shown rather than blocking the page on it.
+        console.error("Failed to load voice config:", e);
+    }
+}
+
+// Save the ElevenLabs key only when the box is showing (onboarding or replace)
+// and something was actually typed; otherwise there is nothing to do.
+async function saveVoiceKey() {
+    if (els.voiceInputWrap.hidden) return;
+    const typed = els.elevenKey.value.trim();
+    if (!typed) return;
+
+    const resp = await fetch(VOICE_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ api_key: typed }),
+    });
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    const data = await resp.json();
+    reflectVoiceState(Boolean(data.has_api_key));
+}
+
+// ── save ─────────────────────────────────────────────────────────────────
+
 async function saveConfig(event) {
     event.preventDefault();
 
@@ -79,14 +130,23 @@ async function saveConfig(event) {
         reflectKeyState(Boolean(data.has_api_key));
         els.apiKey.value = "";
         els.clearKey.checked = false;
+
+        await saveVoiceKey();
+
         setStatus("Saved. Restart ChittiOS to apply.", "ok");
     } catch (e) {
         setStatus("Could not save settings.", "err");
-        console.error("Failed to save LLM config:", e);
+        console.error("Failed to save settings:", e);
     } finally {
         els.saveBtn.disabled = false;
     }
 }
 
 els.form.addEventListener("submit", saveConfig);
+els.replaceVoice.addEventListener("click", () => {
+    reflectVoiceState(false);
+    els.elevenKey.focus();
+});
+
 loadConfig();
+loadVoiceConfig();

chittios/static/style.css

@@ -200,6 +200,41 @@ input[type="password"]:focus {
     color: var(--err);
 }
 
+.voice {
+    margin-bottom: 1.4rem;
+    padding-top: 1.1rem;
+    border-top: 1px solid var(--line);
+}
+
+.voice .label {
+    margin-bottom: 0.6rem;
+}
+
+.voice-on {
+    display: flex;
+    align-items: baseline;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+    font-size: 0.9rem;
+    color: var(--ok);
+    font-weight: 600;
+}
+
+.linkish {
+    font: inherit;
+    font-size: 0.85rem;
+    color: var(--muted);
+    background: none;
+    border: none;
+    padding: 0;
+    text-decoration: underline;
+    cursor: pointer;
+}
+
+.linkish:hover {
+    color: var(--accent);
+}
+
 .restart-note {
     margin-top: 1.4rem;
     padding-top: 1.1rem;

chittios_core/expression/config.py

@@ -0,0 +1,200 @@
+"""Where the ElevenLabs voice credentials come from — env, then file, then off.
+
+The local Piper voice needs no configuration and always works. This resolves the
+*optional* upgrade: an ElevenLabs key (and which voice to speak in), so a
+household that wants the premium cloud voice provides a key once and every later
+start picks it up. No key anywhere means ``enabled`` is false and the robot keeps
+its local voice — the safe default, chosen by absence.
+
+Precedence: env var > config file > default, per field
+------------------------------------------------------
+Mirrors the LLM config exactly, so the two behave the same to an operator:
+
+1. an environment variable (``ELEVENLABS_API_KEY`` for the key — the name the
+   ElevenLabs ecosystem already uses — and ``CHITTIOS_TTS_VOICE_ID`` /
+   ``CHITTIOS_TTS_MODEL`` for the rest);
+2. the on-disk config file (``~/.config/chittios/voice.json``) the settings UI
+   writes when a household pastes a key at onboarding;
+3. the built-in default — no key (so, off), a warm premade voice, the flash model.
+
+The key is the one secret here, and it is treated like the LLM key: written to
+the file, never echoed back over HTTP (the settings route reports only *whether*
+one is set).
+
+Why JSON, not TOML
+------------------
+The settings UI writes this file, and the standard library reads and writes JSON
+losslessly with no third-party dependency — the same reasoning, and the same
+install floor, as the LLM config beside it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from chittios_core.expression.elevenlabs import (
+    DEFAULT_ELEVENLABS_MODEL,
+    DEFAULT_ELEVENLABS_VOICE_ID,
+)
+
+#: The config file the settings UI writes and this module reads. Beside the LLM
+#: config under ``~/.config/chittios`` by the XDG convention.
+DEFAULT_CONFIG_PATH: Final = Path.home() / ".config" / "chittios" / "voice.json"
+
+#: Environment overrides, highest precedence. The key uses the ElevenLabs-standard
+#: name so an operator who already exports it needs no ChittiOS-specific lookup.
+ENV_API_KEY: Final = "ELEVENLABS_API_KEY"
+ENV_VOICE_ID: Final = "CHITTIOS_TTS_VOICE_ID"
+ENV_MODEL: Final = "CHITTIOS_TTS_MODEL"
+
+#: The JSON object keys, shared by reader and writer so the two never drift.
+_KEY_API_KEY: Final = "api_key"
+_KEY_VOICE_ID: Final = "voice_id"
+_KEY_MODEL: Final = "model_id"
+
+
+class VoiceConfigError(ValueError):
+    """Raised when the on-disk voice config exists but cannot be used.
+
+    A present-but-malformed file is an operator error worth surfacing rather than
+    papering over: silently ignoring it would drop a household's chosen voice
+    without a word. Construction of the engine is guarded upstream, so this
+    degrades TTS to the local voice rather than stopping the robot from booting.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class VoiceConfig:
+    """The resolved cloud-voice settings: an optional key, a voice, a model.
+
+    Frozen because it is a startup snapshot, read once and handed to the engine
+    factory. A change to the file or the environment takes effect on the next app
+    start, never by mutating a live config.
+
+    Attributes:
+        api_key: The ElevenLabs key, or ``None`` when none is configured — the
+            single fact that decides whether the cloud voice is used at all.
+        voice_id: The voice to speak in.
+        model_id: The synthesis model to request.
+    """
+
+    api_key: str | None
+    voice_id: str
+    model_id: str
+
+    @property
+    def enabled(self) -> bool:
+        """Whether the cloud voice should be used — i.e. a key is configured."""
+        return self.api_key is not None
+
+
+def load_voice_config(
+    *,
+    path: Path = DEFAULT_CONFIG_PATH,
+    env: Mapping[str, str] | None = None,
+) -> VoiceConfig:
+    """Resolve the voice config: env var > file > default, per field.
+
+    Args:
+        path: The config file to read. A missing file is not an error — it means
+            "no key configured", and the cloud voice stays off.
+        env: The environment to read overrides from. Defaults to ``os.environ``;
+            injectable so a test can drive precedence without touching the
+            process environment.
+
+    Returns:
+        The resolved :class:`VoiceConfig`.
+
+    Raises:
+        VoiceConfigError: if the file exists but is not a JSON object, or a value
+            is present with the wrong type.
+    """
+    environ = os.environ if env is None else env
+    file_values = _read_config_file(path)
+
+    api_key = _resolve(ENV_API_KEY, _KEY_API_KEY, environ, file_values, None)
+    voice_id = (
+        _resolve(ENV_VOICE_ID, _KEY_VOICE_ID, environ, file_values, DEFAULT_ELEVENLABS_VOICE_ID)
+        or DEFAULT_ELEVENLABS_VOICE_ID
+    )
+    model_id = (
+        _resolve(ENV_MODEL, _KEY_MODEL, environ, file_values, DEFAULT_ELEVENLABS_MODEL)
+        or DEFAULT_ELEVENLABS_MODEL
+    )
+    return VoiceConfig(api_key=api_key, voice_id=voice_id, model_id=model_id)
+
+
+def write_voice_config(config: VoiceConfig, *, path: Path = DEFAULT_CONFIG_PATH) -> None:
+    """Write ``config`` to ``path`` as JSON, creating the directory if needed.
+
+    The settings UI's writer: it persists what a household pastes at onboarding so
+    the next start resolves it. ``api_key`` is written as JSON ``null`` when
+    unset, keeping the file a faithful, complete snapshot of all three settings.
+
+    Args:
+        config: The settings to persist.
+        path: Where to write them. The parent directory is created if absent.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    document = {
+        _KEY_API_KEY: config.api_key,
+        _KEY_VOICE_ID: config.voice_id,
+        _KEY_MODEL: config.model_id,
+    }
+    path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+
+
+def _read_config_file(path: Path) -> Mapping[str, object]:
+    """Read the config file into a mapping; an empty mapping if it does not exist.
+
+    Raises:
+        VoiceConfigError: if the file exists but does not hold a JSON object.
+    """
+    if not path.exists():
+        return {}
+    try:
+        parsed: object = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise VoiceConfigError(f"could not read the voice config at {path}: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise VoiceConfigError(
+            f"the voice config at {path} must be a JSON object, got {type(parsed).__name__}"
+        )
+    return parsed
+
+
+def _resolve(
+    env_key: str,
+    file_key: str,
+    env: Mapping[str, str],
+    file_values: Mapping[str, object],
+    default: str | None,
+) -> str | None:
+    """Return one field's value: env var > file entry > default.
+
+    A blank or whitespace-only environment variable counts as unset, so an
+    exported-but-empty ``ELEVENLABS_API_KEY`` falls through to the file rather
+    than pinning the key to the empty string. A file entry present as JSON
+    ``null`` likewise means "unset" and falls through to the default.
+    """
+    env_value = env.get(env_key)
+    if env_value is not None and env_value.strip():
+        return env_value
+
+    if file_key in file_values:
+        file_value = file_values[file_key]
+        if file_value is None:
+            return default
+        if not isinstance(file_value, str):
+            raise VoiceConfigError(
+                f"the voice config value for {file_key!r} must be a string or null, "
+                f"got {type(file_value).__name__}"
+            )
+        return file_value
+
+    return default

chittios_core/expression/elevenlabs.py

@@ -0,0 +1,164 @@
+"""ElevenLabs cloud text-to-speech — an optional, premium voice (CHT-TTS-cloud).
+
+The local Piper voice is the default and the privacy floor: it never leaves the
+box. This is the opposite trade a household can *opt into* — the robot's reply
+text is sent to ElevenLabs and natural, expressive speech comes back — chosen by
+pasting an API key at onboarding. It is deliberately not the default: a key must
+be present for this engine to be built at all, and when it is absent, or fails,
+the local voice speaks instead (see :class:`~chittios_core.expression.tts.FallbackTtsEngine`).
+
+What crosses the wire, and what does not
+----------------------------------------
+Only the *reply* — text ChittiOS generated — goes to ElevenLabs. The family's
+microphone audio never does; speech-to-text stays local by construction (that is
+the line the project does not cross). Sending the robot's own words out for
+synthesis is the same shape of trade the household already made when they pointed
+conversation at a chosen LLM endpoint.
+
+PCM straight onto the audio spine
+---------------------------------
+The request asks for ``pcm_16000`` — signed 16-bit little-endian mono at 16 kHz,
+which *is* the rate the whole audio path standardises on. So the response decodes
+with a single ``frombuffer`` and an int16→float32 scale: no MP3 decoder
+dependency, and ``speak`` resamples nothing because the rate already matches.
+
+Failures name themselves, and never mute the robot
+--------------------------------------------------
+A 4xx — a bad or unauthorised key, a plan that does not permit PCM, an exhausted
+quota — is a standing condition, raised as :class:`TtsUnavailableError` so the
+fallback engine latches to the local voice for the session. A 5xx or a network
+blip is transient, raised as :class:`TtsTransientError` so the fallback covers
+just that one line and the next line tries the cloud again.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+import httpx
+import numpy as np
+from numpy.typing import NDArray
+
+from chittios_core.expression.tts import TtsTransientError, TtsUnavailableError
+from hal.reference_hal import AUDIO_DTYPE
+
+#: ElevenLabs' low-latency model — fast and inexpensive per character, the right
+#: default for a robot that speaks in short conversational turns rather than
+#: narrating essays. Overridable per household via config.
+DEFAULT_ELEVENLABS_MODEL: Final = "eleven_flash_v2_5"
+
+#: "George" — a warm, premade storyteller voice. Premade voice ids are shared
+#: across every ElevenLabs account, so this default resolves for any customer's
+#: key, not just the developer's. Overridable per household via config.
+DEFAULT_ELEVENLABS_VOICE_ID: Final = "JBFqnCBsd6RMkjVDRZzb"
+
+#: The API host. A constant, not a config field: unlike the LLM endpoint there is
+#: one ElevenLabs, and a household chooses the voice, not the server.
+DEFAULT_ELEVENLABS_BASE_URL: Final = "https://api.elevenlabs.io"
+
+#: The one output format requested, and the rate it carries. Both are fixed
+#: together: ``pcm_16000`` is signed 16-bit LE mono at exactly this rate, so the
+#: decode is a ``frombuffer`` and no resample is ever needed downstream.
+_OUTPUT_FORMAT: Final = "pcm_16000"
+_SAMPLE_RATE_HZ: Final = 16_000
+
+#: How long to wait on one synthesis before calling it a transient failure. Long
+#: enough for a sentence on a slow link, short enough that a hung request falls
+#: back to the local voice rather than stalling the turn.
+_DEFAULT_TIMEOUT_S: Final = 30.0
+
+
+class ElevenLabsTtsEngine:
+    """Synthesizes text through the ElevenLabs cloud API, returning 16 kHz mono.
+
+    Satisfies the :class:`~chittios_core.expression.tts.TtsEngine` protocol, so it
+    drops into ``speak`` exactly where Piper or the stub would. Build it only when
+    a key is configured; wrap it in a ``FallbackTtsEngine`` so a cloud failure is
+    covered by the local voice rather than heard as silence.
+
+    Args:
+        api_key: The household's ElevenLabs API key. Required and non-empty.
+        voice_id: The voice to speak in. Defaults to a warm premade voice.
+        model_id: The synthesis model. Defaults to the low-latency flash model.
+        base_url: The API host. Defaults to ElevenLabs.
+        timeout_s: Per-request timeout in seconds.
+        client: An injected HTTP client, for tests. Defaults to a pooled
+            :class:`httpx.Client`, so successive turns reuse one TLS connection
+            rather than paying a fresh handshake each time.
+
+    Raises:
+        TtsUnavailableError: if ``api_key`` is empty — the one failure knowable at
+            construction, kept here so a blank key never yields a live-but-useless
+            engine.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        voice_id: str = DEFAULT_ELEVENLABS_VOICE_ID,
+        model_id: str = DEFAULT_ELEVENLABS_MODEL,
+        base_url: str = DEFAULT_ELEVENLABS_BASE_URL,
+        timeout_s: float = _DEFAULT_TIMEOUT_S,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise TtsUnavailableError("ElevenLabsTtsEngine needs a non-empty API key.")
+        self._api_key = api_key
+        self._model_id = model_id
+        self._url = f"{base_url.rstrip('/')}/v1/text-to-speech/{voice_id}"
+        self._client = client if client is not None else httpx.Client(timeout=timeout_s)
+
+    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
+        """Synthesize ``text`` and return ``(mono float32 samples, 16000)``.
+
+        Whitespace-only or empty text short-circuits to empty audio — there is
+        nothing to say and no reason to spend a request or a character of quota.
+
+        Raises:
+            TtsUnavailableError: on a 4xx — a standing condition (bad key, a plan
+                without PCM, exhausted quota) the caller should stop retrying.
+            TtsTransientError: on a 5xx or a network error — worth trying again on
+                the next line.
+        """
+        if not text.strip():
+            return np.zeros(0, dtype=AUDIO_DTYPE), _SAMPLE_RATE_HZ
+
+        try:
+            response = self._client.post(
+                self._url,
+                params={"output_format": _OUTPUT_FORMAT},
+                headers={"xi-api-key": self._api_key, "content-type": "application/json"},
+                json={"text": text, "model_id": self._model_id},
+            )
+        except httpx.HTTPError as exc:
+            raise TtsTransientError(f"could not reach ElevenLabs: {exc}") from exc
+
+        if response.status_code != 200:
+            detail = _short_detail(response)
+            if 400 <= response.status_code < 500:
+                raise TtsUnavailableError(
+                    f"ElevenLabs rejected the request (HTTP {response.status_code}): {detail}"
+                )
+            raise TtsTransientError(
+                f"ElevenLabs is unavailable (HTTP {response.status_code}): {detail}"
+            )
+
+        pcm = np.frombuffer(response.content, dtype="<i2")
+        # int16 → float32 in [-1, 1). Dividing by 32768 (not 32767) keeps a
+        # full-scale negative sample exactly at -1.0, matching the convention the
+        # rest of the audio spine uses.
+        samples = (pcm.astype(np.float32) / 32768.0).astype(AUDIO_DTYPE)
+        return samples, _SAMPLE_RATE_HZ
+
+
+def _short_detail(response: httpx.Response) -> str:
+    """A brief, safe description of a failed response for a log line.
+
+    The body is truncated because ElevenLabs' error JSON can be long, and this
+    lands in a warning the household may read — the status and a hint, not a wall.
+    """
+    try:
+        return response.text[:200]
+    except Exception:  # pragma: no cover - a body that will not decode is still a failure
+        return "<unreadable response body>"

chittios_core/expression/tts.py

@@ -1,305 +1,373 @@
-"""Local text-to-speech for the expression subsystem (CHT-019, Phase 2).
-
-Layer 2's voice. Core turns a line of text into audio and streams it to the
-body through the HAL contract's ``audio_out``. Everything here runs on the
-machine — no cloud, no network — which is the whole promise of the project:
-*"With the local setup, audio never leaves your machine."* (spec §9).
-
-Three deliberate shapes
------------------------
-**A ``TtsEngine`` seam.** Synthesis is the one part that wants a heavy,
-optional runtime (an ONNX voice model). Putting it behind a Protocol keeps the
-streaming, resampling, and chunking logic — the part Core actually depends on —
-testable without that runtime, the same way ``identity.voice`` keeps its
-matching policy testable without torch. A ``StubTtsEngine`` satisfies the seam
-with deterministic synthetic audio; ``PiperTtsEngine`` is the real backend and
-is imported lazily so this module stays importable on a machine with no Piper.
-
-**Everything lands at 16 kHz float32 mono.** The Reachy Mini push path
-(``media.push_audio_sample``) wants float32 at 16 kHz, and the HAL contract
-fixes float32 as the processing format end to end (``AUDIO_DTYPE``). A voice
-model that speaks at 22.05 kHz is normal, so ``speak`` resamples whatever the
-engine produces onto the target rate rather than trusting engines to agree.
-Resampling once, here, means no downstream stage has to.
-
-**Chunked, not buffered.** ``speak`` emits ~100 ms ``AudioChunk``s as it goes
-so the body can begin speaking before the whole utterance is synthesized and
-resampled. That streaming is what the narration-latency budget in spec §7.2
-(time-to-first-audio) is built on; buffering the full clip first would spend
-the entire budget before the first sample reached the speaker.
-"""
-
-from __future__ import annotations
-
-from collections.abc import AsyncIterator
-from math import gcd
-from typing import Final, Protocol, runtime_checkable
-
-import numpy as np
-from numpy.typing import NDArray
-
-from hal.reference_hal import AUDIO_DTYPE, AudioChunk
-
-#: The rate every utterance is delivered at. The Reachy Mini push path expects
-#: float32 @ 16 kHz, and 16 kHz is already the rate the perception and voice
-#: paths standardize on, so one constant governs the whole audio spine.
-TARGET_SAMPLE_RATE_HZ: Final = 16_000
-
-#: Chunk granularity for streaming playback. ~100 ms is small enough that
-#: time-to-first-audio stays inside the budget yet large enough that the
-#: per-chunk overhead (an ``AudioChunk`` allocation and an ``await``) is noise.
-DEFAULT_CHUNK_MS: Final = 100
-
-#: Piper's default voices speak at 22.05 kHz. Used by ``StubTtsEngine`` so the
-#: default test path exercises the resampler rather than the pass-through.
-DEFAULT_STUB_SAMPLE_RATE_HZ: Final = 22_050
-
-
-class TtsUnavailableError(RuntimeError):
-    """Raised when a TTS backend's runtime dependency is not installed.
-
-    Constructing a backend is where the missing dependency surfaces, so the
-    failure names the extra to install rather than letting an ``ImportError``
-    escape from deep inside synthesis with no remedy attached.
-    """
-
-
-@runtime_checkable
-class TtsEngine(Protocol):
-    """Turns text into a single block of mono audio at the engine's own rate.
-
-    The engine owns synthesis and nothing else: it does not resample, chunk, or
-    touch the body. Returning the rate alongside the samples — rather than
-    assuming a fixed one — is what lets ``speak`` accept any voice model and
-    still guarantee 16 kHz downstream.
-    """
-
-    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
-        """Return ``(mono float32 samples in [-1, 1], sample_rate_hz)``."""
-        ...
-
-
-class StubTtsEngine:
-    """Deterministic synthetic speech for tests — no external dependency.
-
-    Emits a fixed-frequency tone whose length grows with the text, so callers
-    get non-empty, chunk-able audio without a voice model. Deterministic by
-    construction: the same text always yields identical samples, which is what
-    lets tests assert on exact behaviour instead of tolerating model jitter.
-
-    Args:
-        sample_rate_hz: Rate of the produced audio. Defaults to Piper's
-            22.05 kHz so the default path deliberately differs from the 16 kHz
-            target and exercises the resampler.
-        tone_hz: Frequency of the synthesized tone.
-        seconds_per_char: Audio duration contributed by each character.
-        amplitude: Peak amplitude, comfortably inside [-1, 1].
-    """
-
-    def __init__(
-        self,
-        *,
-        sample_rate_hz: int = DEFAULT_STUB_SAMPLE_RATE_HZ,
-        tone_hz: float = 220.0,
-        seconds_per_char: float = 0.08,
-        amplitude: float = 0.25,
-    ) -> None:
-        if sample_rate_hz <= 0:
-            raise ValueError(f"sample_rate_hz must be positive, got {sample_rate_hz}")
-        if tone_hz <= 0:
-            raise ValueError(f"tone_hz must be positive, got {tone_hz}")
-        if seconds_per_char <= 0:
-            raise ValueError(f"seconds_per_char must be positive, got {seconds_per_char}")
-        if not 0.0 < amplitude <= 1.0:
-            raise ValueError(f"amplitude must lie in (0, 1], got {amplitude}")
-        self._sample_rate_hz = sample_rate_hz
-        self._tone_hz = tone_hz
-        self._seconds_per_char = seconds_per_char
-        self._amplitude = amplitude
-
-    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
-        """Return a tone whose duration scales with ``len(text)``.
-
-        Whitespace-only or empty text yields an empty array — the honest
-        representation of "nothing to say" — which ``speak`` streams as zero
-        chunks rather than a silent blip.
-        """
-        char_count = len(text.strip())
-        if char_count == 0:
-            return np.zeros(0, dtype=AUDIO_DTYPE), self._sample_rate_hz
-
-        duration_s = char_count * self._seconds_per_char
-        sample_count = int(self._sample_rate_hz * duration_s)
-        t = np.arange(sample_count, dtype=np.float64) / self._sample_rate_hz
-        samples = self._amplitude * np.sin(2.0 * np.pi * self._tone_hz * t)
-        return samples.astype(AUDIO_DTYPE), self._sample_rate_hz
-
-
-class PiperTtsEngine:
-    """Piper-backed synthesis, behind the optional ``voice-tts`` extra.
-
-    Piper is a local, ONNX-based neural TTS: no cloud, fast on CPU, which is
-    exactly the constraint a household robot's voice lives under. It is an
-    optional dependency — importing this module never requires it — so the
-    import is deferred to construction and a clear ``TtsUnavailableError`` is
-    raised when it is absent, naming the extra to install.
-
-    Args:
-        model_path: Path to a Piper ``.onnx`` voice model.
-        config_path: Path to the model's ``.onnx.json`` config. Piper defaults
-            to ``<model_path>.json`` when omitted, so this is only needed when
-            the config sits elsewhere.
-        use_cuda: Run inference on GPU. Off by default — the target is a CPU
-            SBC, and CUDA is the exception, not the rule.
-
-    Raises:
-        TtsUnavailableError: if ``piper-tts`` is not installed.
-    """
-
-    def __init__(
-        self,
-        model_path: str,
-        *,
-        config_path: str | None = None,
-        use_cuda: bool = False,
-    ) -> None:
-        try:
-            from piper import PiperVoice
-        except ImportError as exc:  # pragma: no cover - exercised only without piper
-            raise TtsUnavailableError(
-                "PiperTtsEngine needs the 'piper-tts' package, which is not installed. "
-                "Install the optional extra: pip install 'chittios[voice-tts]'."
-            ) from exc
-
-        self._voice = PiperVoice.load(model_path, config_path=config_path, use_cuda=use_cuda)
-
-    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
-        """Synthesize ``text`` and return ``(mono float32 samples, rate)``.
-
-        Piper streams int16 chunks; they are concatenated and converted to the
-        float32 the rest of the pipeline speaks in. ``speak`` re-chunks the
-        result for playback, so gathering Piper's chunks here keeps this method
-        a plain ``TtsEngine`` — text in, one waveform out — and leaves streaming
-        policy in one place.
-
-        Raises:
-            TtsUnavailableError: if Piper yields no audio for the text.
-        """
-        blocks: list[NDArray[np.int16]] = []
-        sample_rate: int | None = None
-        for chunk in self._voice.synthesize(text):
-            sample_rate = chunk.sample_rate
-            blocks.append(np.frombuffer(chunk.audio_int16_bytes, dtype=np.int16))
-
-        if sample_rate is None:
-            raise TtsUnavailableError(f"Piper produced no audio for text: {text!r}")
-
-        if blocks:
-            pcm = np.concatenate(blocks)
-        else:
-            pcm = np.zeros(0, dtype=np.int16)
-
-        # int16 -> float32 in [-1, 1). Dividing by 32768 (not 32767) is the
-        # standard convention: it keeps full-scale negative samples exactly at
-        # -1.0 and never overshoots the range the contract promises.
-        samples = (pcm.astype(np.float32) / 32768.0).astype(AUDIO_DTYPE)
-        return samples, sample_rate
-
-
-def _resample_to_target(samples: NDArray[np.float32], source_rate_hz: int) -> NDArray[np.float32]:
-    """Resample mono audio onto ``TARGET_SAMPLE_RATE_HZ`` float32.
-
-    A pass-through when the rates already match, so the common Piper-at-16 kHz
-    case pays nothing. Otherwise polyphase resampling via ``scipy.signal`` —
-    imported lazily, matching the HAL adapters, so this module stays importable
-    without SciPy installed. Reducing up/down by their GCD keeps the polyphase
-    filter small (16 kHz from 22.05 kHz is 320/441, not 16000/22050).
-
-    Args:
-        samples: Mono float32 at ``source_rate_hz``.
-        source_rate_hz: The rate ``samples`` were produced at.
-
-    Returns:
-        Contiguous float32 at ``TARGET_SAMPLE_RATE_HZ``, clipped to [-1, 1]
-        because polyphase filtering can ring a hair past full scale.
-    """
-    if samples.ndim != 1:
-        raise ValueError(f"expected mono (1-D) audio, got shape {samples.shape}")
-    if source_rate_hz <= 0:
-        raise ValueError(f"source_rate_hz must be positive, got {source_rate_hz}")
-    if source_rate_hz == TARGET_SAMPLE_RATE_HZ or samples.size == 0:
-        return np.ascontiguousarray(samples, dtype=AUDIO_DTYPE)
-
-    from scipy.signal import resample_poly
-
-    divisor = gcd(source_rate_hz, TARGET_SAMPLE_RATE_HZ)
-    up = TARGET_SAMPLE_RATE_HZ // divisor
-    down = source_rate_hz // divisor
-    resampled = resample_poly(samples.astype(np.float64), up, down)
-    return np.ascontiguousarray(np.clip(resampled, -1.0, 1.0), dtype=AUDIO_DTYPE)
-
-
-async def _stream_chunks(
-    samples: NDArray[np.float32], *, chunk_ms: int
-) -> AsyncIterator[AudioChunk]:
-    """Slice 16 kHz mono ``samples`` into ~``chunk_ms`` ``AudioChunk``s.
-
-    Timestamps advance by each chunk's own duration so the stream carries a
-    coherent playback clock. A short final chunk is yielded as-is rather than
-    padded — padding would inject silence the speaker would actually play.
-    """
-    samples_per_chunk = int(TARGET_SAMPLE_RATE_HZ * chunk_ms / 1000)
-    elapsed_s = 0.0
-    for start in range(0, len(samples), samples_per_chunk):
-        block = np.ascontiguousarray(samples[start : start + samples_per_chunk], dtype=AUDIO_DTYPE)
-        yield AudioChunk(
-            samples=block,
-            sample_rate_hz=TARGET_SAMPLE_RATE_HZ,
-            channels=1,
-            timestamp_s=elapsed_s,
-        )
-        elapsed_s += len(block) / TARGET_SAMPLE_RATE_HZ
-
-
-@runtime_checkable
-class SupportsAudioOut(Protocol):
-    """The slice of a HAL body that ``speak`` needs: a sink for an audio stream.
-
-    Typing ``speak`` to this narrow shape (not the full ``HALAdapter``) is what
-    lets the screen-avatar test double — which implements only ``audio_out`` —
-    stand in for the real Reachy body, and keeps ``speak`` honest about what it
-    actually touches.
-    """
-
-    async def audio_out(self, chunks: AsyncIterator[AudioChunk]) -> None:
-        """Play a stream of audio chunks, returning once they are consumed."""
-        ...
-
-
-async def speak(
-    text: str,
-    body: SupportsAudioOut,
-    engine: TtsEngine,
-    *,
-    chunk_ms: int = DEFAULT_CHUNK_MS,
-) -> None:
-    """Synthesize ``text`` and stream it to ``body`` as 16 kHz float32 mono.
-
-    The full expression path for one line: synthesize with ``engine``, resample
-    to the body's expected rate, and stream ~``chunk_ms`` chunks into
-    ``body.audio_out`` so playback can start before synthesis finishes. Empty
-    or whitespace-only text streams nothing — there is no audio to play, and an
-    empty stream is the correct representation of silence.
-
-    Args:
-        text: The line to speak.
-        body: The HAL adapter that will play the audio.
-        engine: The synthesis backend.
-        chunk_ms: Playback chunk duration. Must be positive.
-    """
-    if chunk_ms <= 0:
-        raise ValueError(f"chunk_ms must be positive, got {chunk_ms}")
-
-    raw_samples, source_rate_hz = engine.synthesize(text)
-    samples = _resample_to_target(raw_samples, source_rate_hz)
-    await body.audio_out(_stream_chunks(samples, chunk_ms=chunk_ms))
+"""Local text-to-speech for the expression subsystem (CHT-019, Phase 2).
+
+Layer 2's voice. Core turns a line of text into audio and streams it to the
+body through the HAL contract's ``audio_out``. Everything here runs on the
+machine — no cloud, no network — which is the whole promise of the project:
+*"With the local setup, audio never leaves your machine."* (spec §9).
+
+Three deliberate shapes
+-----------------------
+**A ``TtsEngine`` seam.** Synthesis is the one part that wants a heavy,
+optional runtime (an ONNX voice model). Putting it behind a Protocol keeps the
+streaming, resampling, and chunking logic — the part Core actually depends on —
+testable without that runtime, the same way ``identity.voice`` keeps its
+matching policy testable without torch. A ``StubTtsEngine`` satisfies the seam
+with deterministic synthetic audio; ``PiperTtsEngine`` is the real backend and
+is imported lazily so this module stays importable on a machine with no Piper.
+
+**Everything lands at 16 kHz float32 mono.** The Reachy Mini push path
+(``media.push_audio_sample``) wants float32 at 16 kHz, and the HAL contract
+fixes float32 as the processing format end to end (``AUDIO_DTYPE``). A voice
+model that speaks at 22.05 kHz is normal, so ``speak`` resamples whatever the
+engine produces onto the target rate rather than trusting engines to agree.
+Resampling once, here, means no downstream stage has to.
+
+**Chunked, not buffered.** ``speak`` emits ~100 ms ``AudioChunk``s as it goes
+so the body can begin speaking before the whole utterance is synthesized and
+resampled. That streaming is what the narration-latency budget in spec §7.2
+(time-to-first-audio) is built on; buffering the full clip first would spend
+the entire budget before the first sample reached the speaker.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from math import gcd
+from typing import Final, Protocol, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from hal.reference_hal import AUDIO_DTYPE, AudioChunk
+
+logger = logging.getLogger(__name__)
+
+#: The rate every utterance is delivered at. The Reachy Mini push path expects
+#: float32 @ 16 kHz, and 16 kHz is already the rate the perception and voice
+#: paths standardize on, so one constant governs the whole audio spine.
+TARGET_SAMPLE_RATE_HZ: Final = 16_000
+
+#: Chunk granularity for streaming playback. ~100 ms is small enough that
+#: time-to-first-audio stays inside the budget yet large enough that the
+#: per-chunk overhead (an ``AudioChunk`` allocation and an ``await``) is noise.
+DEFAULT_CHUNK_MS: Final = 100
+
+#: Piper's default voices speak at 22.05 kHz. Used by ``StubTtsEngine`` so the
+#: default test path exercises the resampler rather than the pass-through.
+DEFAULT_STUB_SAMPLE_RATE_HZ: Final = 22_050
+
+
+class TtsUnavailableError(RuntimeError):
+    """Raised when a TTS backend cannot be used, and the caller should stop trying.
+
+    Two shapes of standing failure: a backend's runtime dependency is not
+    installed (surfaced at construction, naming the extra to install), or a cloud
+    backend was refused for a durable reason — a bad key, a plan without the
+    requested format, an exhausted quota (a 4xx). Both mean "do not keep retrying
+    this backend"; :class:`FallbackTtsEngine` latches to its fallback on this.
+    """
+
+
+class TtsTransientError(RuntimeError):
+    """Raised when a TTS backend failed in a way that may succeed next time.
+
+    A network blip or a 5xx from a cloud backend — worth covering with the
+    fallback for just this one line, then trying the primary again on the next.
+    The counterpart to :class:`TtsUnavailableError`, which is durable.
+    """
+
+
+@runtime_checkable
+class TtsEngine(Protocol):
+    """Turns text into a single block of mono audio at the engine's own rate.
+
+    The engine owns synthesis and nothing else: it does not resample, chunk, or
+    touch the body. Returning the rate alongside the samples — rather than
+    assuming a fixed one — is what lets ``speak`` accept any voice model and
+    still guarantee 16 kHz downstream.
+    """
+
+    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
+        """Return ``(mono float32 samples in [-1, 1], sample_rate_hz)``."""
+        ...
+
+
+class StubTtsEngine:
+    """Deterministic synthetic speech for tests — no external dependency.
+
+    Emits a fixed-frequency tone whose length grows with the text, so callers
+    get non-empty, chunk-able audio without a voice model. Deterministic by
+    construction: the same text always yields identical samples, which is what
+    lets tests assert on exact behaviour instead of tolerating model jitter.
+
+    Args:
+        sample_rate_hz: Rate of the produced audio. Defaults to Piper's
+            22.05 kHz so the default path deliberately differs from the 16 kHz
+            target and exercises the resampler.
+        tone_hz: Frequency of the synthesized tone.
+        seconds_per_char: Audio duration contributed by each character.
+        amplitude: Peak amplitude, comfortably inside [-1, 1].
+    """
+
+    def __init__(
+        self,
+        *,
+        sample_rate_hz: int = DEFAULT_STUB_SAMPLE_RATE_HZ,
+        tone_hz: float = 220.0,
+        seconds_per_char: float = 0.08,
+        amplitude: float = 0.25,
+    ) -> None:
+        if sample_rate_hz <= 0:
+            raise ValueError(f"sample_rate_hz must be positive, got {sample_rate_hz}")
+        if tone_hz <= 0:
+            raise ValueError(f"tone_hz must be positive, got {tone_hz}")
+        if seconds_per_char <= 0:
+            raise ValueError(f"seconds_per_char must be positive, got {seconds_per_char}")
+        if not 0.0 < amplitude <= 1.0:
+            raise ValueError(f"amplitude must lie in (0, 1], got {amplitude}")
+        self._sample_rate_hz = sample_rate_hz
+        self._tone_hz = tone_hz
+        self._seconds_per_char = seconds_per_char
+        self._amplitude = amplitude
+
+    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
+        """Return a tone whose duration scales with ``len(text)``.
+
+        Whitespace-only or empty text yields an empty array — the honest
+        representation of "nothing to say" — which ``speak`` streams as zero
+        chunks rather than a silent blip.
+        """
+        char_count = len(text.strip())
+        if char_count == 0:
+            return np.zeros(0, dtype=AUDIO_DTYPE), self._sample_rate_hz
+
+        duration_s = char_count * self._seconds_per_char
+        sample_count = int(self._sample_rate_hz * duration_s)
+        t = np.arange(sample_count, dtype=np.float64) / self._sample_rate_hz
+        samples = self._amplitude * np.sin(2.0 * np.pi * self._tone_hz * t)
+        return samples.astype(AUDIO_DTYPE), self._sample_rate_hz
+
+
+class PiperTtsEngine:
+    """Piper-backed synthesis, behind the optional ``voice-tts`` extra.
+
+    Piper is a local, ONNX-based neural TTS: no cloud, fast on CPU, which is
+    exactly the constraint a household robot's voice lives under. It is an
+    optional dependency — importing this module never requires it — so the
+    import is deferred to construction and a clear ``TtsUnavailableError`` is
+    raised when it is absent, naming the extra to install.
+
+    Args:
+        model_path: Path to a Piper ``.onnx`` voice model.
+        config_path: Path to the model's ``.onnx.json`` config. Piper defaults
+            to ``<model_path>.json`` when omitted, so this is only needed when
+            the config sits elsewhere.
+        use_cuda: Run inference on GPU. Off by default — the target is a CPU
+            SBC, and CUDA is the exception, not the rule.
+
+    Raises:
+        TtsUnavailableError: if ``piper-tts`` is not installed.
+    """
+
+    def __init__(
+        self,
+        model_path: str,
+        *,
+        config_path: str | None = None,
+        use_cuda: bool = False,
+    ) -> None:
+        try:
+            from piper import PiperVoice
+        except ImportError as exc:  # pragma: no cover - exercised only without piper
+            raise TtsUnavailableError(
+                "PiperTtsEngine needs the 'piper-tts' package, which is not installed. "
+                "Install the optional extra: pip install 'chittios[voice-tts]'."
+            ) from exc
+
+        self._voice = PiperVoice.load(model_path, config_path=config_path, use_cuda=use_cuda)
+
+    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
+        """Synthesize ``text`` and return ``(mono float32 samples, rate)``.
+
+        Piper streams int16 chunks; they are concatenated and converted to the
+        float32 the rest of the pipeline speaks in. ``speak`` re-chunks the
+        result for playback, so gathering Piper's chunks here keeps this method
+        a plain ``TtsEngine`` — text in, one waveform out — and leaves streaming
+        policy in one place.
+
+        Raises:
+            TtsUnavailableError: if Piper yields no audio for the text.
+        """
+        blocks: list[NDArray[np.int16]] = []
+        sample_rate: int | None = None
+        for chunk in self._voice.synthesize(text):
+            sample_rate = chunk.sample_rate
+            blocks.append(np.frombuffer(chunk.audio_int16_bytes, dtype=np.int16))
+
+        if sample_rate is None:
+            raise TtsUnavailableError(f"Piper produced no audio for text: {text!r}")
+
+        if blocks:
+            pcm = np.concatenate(blocks)
+        else:
+            pcm = np.zeros(0, dtype=np.int16)
+
+        # int16 -> float32 in [-1, 1). Dividing by 32768 (not 32767) is the
+        # standard convention: it keeps full-scale negative samples exactly at
+        # -1.0 and never overshoots the range the contract promises.
+        samples = (pcm.astype(np.float32) / 32768.0).astype(AUDIO_DTYPE)
+        return samples, sample_rate
+
+
+class FallbackTtsEngine:
+    """Speaks through a primary engine, falling back to a local one on failure.
+
+    The one place the cloud/local trade is arbitrated: a household that has opted
+    into ElevenLabs gets it, but a bad key, an exhausted quota, or a dropped
+    connection is never heard as silence — the local voice covers the line
+    instead. This keeps every other layer unaware there is a choice at all; it
+    still holds one ``TtsEngine`` and calls ``synthesize``.
+
+    Durable vs transient, from the raised error:
+
+    - :class:`TtsUnavailableError` is a standing condition (bad key, plan without
+      PCM, quota gone). The primary is *disabled for the session* — retrying it
+      every sentence would add a doomed round-trip to each turn — and a restart is
+      what re-checks it, once the household has fixed the cause.
+    - :class:`TtsTransientError` (or any unexpected error) covers just this line;
+      the next line tries the primary again.
+
+    Args:
+        primary: The preferred engine (e.g. ElevenLabs).
+        fallback: The always-available local engine (Piper, or the stub tone).
+    """
+
+    def __init__(self, primary: TtsEngine, fallback: TtsEngine) -> None:
+        self._primary = primary
+        self._fallback = fallback
+        self._primary_disabled = False
+
+    def synthesize(self, text: str) -> tuple[NDArray[np.float32], int]:
+        """Synthesize with the primary engine, or the fallback if it cannot."""
+        if not self._primary_disabled:
+            try:
+                return self._primary.synthesize(text)
+            except TtsUnavailableError as exc:
+                logger.warning(
+                    "primary voice unavailable (%s); using the local voice for the rest "
+                    "of this session — restart once the cause is fixed to re-enable it",
+                    exc,
+                )
+                self._primary_disabled = True
+            except TtsTransientError as exc:
+                logger.warning(
+                    "primary voice hiccup (%s); using the local voice for this line", exc
+                )
+            except Exception:
+                logger.exception("primary voice raised unexpectedly; using the local voice")
+        return self._fallback.synthesize(text)
+
+
+def _resample_to_target(samples: NDArray[np.float32], source_rate_hz: int) -> NDArray[np.float32]:
+    """Resample mono audio onto ``TARGET_SAMPLE_RATE_HZ`` float32.
+
+    A pass-through when the rates already match, so the common Piper-at-16 kHz
+    case pays nothing. Otherwise polyphase resampling via ``scipy.signal`` —
+    imported lazily, matching the HAL adapters, so this module stays importable
+    without SciPy installed. Reducing up/down by their GCD keeps the polyphase
+    filter small (16 kHz from 22.05 kHz is 320/441, not 16000/22050).
+
+    Args:
+        samples: Mono float32 at ``source_rate_hz``.
+        source_rate_hz: The rate ``samples`` were produced at.
+
+    Returns:
+        Contiguous float32 at ``TARGET_SAMPLE_RATE_HZ``, clipped to [-1, 1]
+        because polyphase filtering can ring a hair past full scale.
+    """
+    if samples.ndim != 1:
+        raise ValueError(f"expected mono (1-D) audio, got shape {samples.shape}")
+    if source_rate_hz <= 0:
+        raise ValueError(f"source_rate_hz must be positive, got {source_rate_hz}")
+    if source_rate_hz == TARGET_SAMPLE_RATE_HZ or samples.size == 0:
+        return np.ascontiguousarray(samples, dtype=AUDIO_DTYPE)
+
+    from scipy.signal import resample_poly
+
+    divisor = gcd(source_rate_hz, TARGET_SAMPLE_RATE_HZ)
+    up = TARGET_SAMPLE_RATE_HZ // divisor
+    down = source_rate_hz // divisor
+    resampled = resample_poly(samples.astype(np.float64), up, down)
+    return np.ascontiguousarray(np.clip(resampled, -1.0, 1.0), dtype=AUDIO_DTYPE)
+
+
+async def _stream_chunks(
+    samples: NDArray[np.float32], *, chunk_ms: int
+) -> AsyncIterator[AudioChunk]:
+    """Slice 16 kHz mono ``samples`` into ~``chunk_ms`` ``AudioChunk``s.
+
+    Timestamps advance by each chunk's own duration so the stream carries a
+    coherent playback clock. A short final chunk is yielded as-is rather than
+    padded — padding would inject silence the speaker would actually play.
+    """
+    samples_per_chunk = int(TARGET_SAMPLE_RATE_HZ * chunk_ms / 1000)
+    elapsed_s = 0.0
+    for start in range(0, len(samples), samples_per_chunk):
+        block = np.ascontiguousarray(samples[start : start + samples_per_chunk], dtype=AUDIO_DTYPE)
+        yield AudioChunk(
+            samples=block,
+            sample_rate_hz=TARGET_SAMPLE_RATE_HZ,
+            channels=1,
+            timestamp_s=elapsed_s,
+        )
+        elapsed_s += len(block) / TARGET_SAMPLE_RATE_HZ
+
+
+@runtime_checkable
+class SupportsAudioOut(Protocol):
+    """The slice of a HAL body that ``speak`` needs: a sink for an audio stream.
+
+    Typing ``speak`` to this narrow shape (not the full ``HALAdapter``) is what
+    lets the screen-avatar test double — which implements only ``audio_out`` —
+    stand in for the real Reachy body, and keeps ``speak`` honest about what it
+    actually touches.
+    """
+
+    async def audio_out(self, chunks: AsyncIterator[AudioChunk]) -> None:
+        """Play a stream of audio chunks, returning once they are consumed."""
+        ...
+
+
+async def speak(
+    text: str,
+    body: SupportsAudioOut,
+    engine: TtsEngine,
+    *,
+    chunk_ms: int = DEFAULT_CHUNK_MS,
+) -> None:
+    """Synthesize ``text`` and stream it to ``body`` as 16 kHz float32 mono.
+
+    The full expression path for one line: synthesize with ``engine``, resample
+    to the body's expected rate, and stream ~``chunk_ms`` chunks into
+    ``body.audio_out`` so playback can start before synthesis finishes. Empty
+    or whitespace-only text streams nothing — there is no audio to play, and an
+    empty stream is the correct representation of silence.
+
+    Args:
+        text: The line to speak.
+        body: The HAL adapter that will play the audio.
+        engine: The synthesis backend.
+        chunk_ms: Playback chunk duration. Must be positive.
+    """
+    if chunk_ms <= 0:
+        raise ValueError(f"chunk_ms must be positive, got {chunk_ms}")
+
+    # Synthesis is a blocking call — a Piper decode on a slow CPU, or a network
+    # round-trip to a cloud engine — so it runs on a worker thread. On the event
+    # loop it would freeze everything (a still-speaking reply, motion, the stop
+    # check) for its whole duration; off it, the loop keeps serving them.
+    raw_samples, source_rate_hz = await asyncio.to_thread(engine.synthesize, text)
+    samples = _resample_to_target(raw_samples, source_rate_hz)
+    await body.audio_out(_stream_chunks(samples, chunk_ms=chunk_ms))

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chittios"
-version = "1.1.0"
+version = "1.2.0"
 description = "ChittiOS — a local-first household companion for Reachy Mini"
 readme = "README.md"
 requires-python = ">=3.10"