feat: Audio-Eingang über WebSocket (/ws/voice) - Sprach-zu-Sprach (#4 Ausbau)

- /ws/voice: binaere Audio-Frames puffern, {"type":"end"} -> STT-Transkription
  -> transcript-Event -> bestehende Antwort-Pipeline (ack/token/audio/semantic/done)
- ws.py refaktoriert: gemeinsame _resolve + _run_turn fuer /ws/chat und /ws/voice
- stream/audio_stream auch fuer Sprach-Turns nutzbar; mehrere Utterances pro Verbindung
- Tests: 47 gruen (+2: Transkript->Antwort, leerer Puffer)
- Doku aktualisiert (README, BEDIENUNGSANLEITUNG, Architektur)

Hinweis: STT pro Aeusserung (gepuffert); partielle Live-Transkripte (Streaming-STT
mit VAD) bleiben naechster Increment.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

BEDIENUNGSANLEITUNG.md

@@ -278,6 +278,10 @@ als `token`-Events (geringere wahrgenommene Latenz). Mit `"audio_stream": true`
 kommt zusätzlich das Audio satzweise (`audio`-Event + binärer Frame), sobald ein
 Satz fertig ist.
 
+**Sprach-Eingang** (`/ws/voice`): Mikrofon-Audio als binäre Frames senden, dann
+`{"type":"end"}`. Der Server schickt ein `transcript`-Event und danach die Antwort
+wie bei `/ws/chat` (`stream`/`audio_stream` im `end`-Frame möglich).
+
 > **Für lokale Entwicklung** ist in der mitgelieferten `.env` `AUTH_ENABLED=false`
 > gesetzt — dann ist kein Token nötig (anonymer Nutzer).
 

Docs/voice-assistant-architecture.md

@@ -171,7 +171,8 @@ ein No-op; `LoopbackOutput` sammelt die Chunks (testbar ohne Hardware).
 | `POST /api/admin/users`              | Nutzer anlegen (Admin-Key) → Token einmalig |
 | `GET  /api/me` · `PUT /api/me/prefs` | aktueller Nutzer + dauerhafte Präferenzen |
 | `GET/POST/DELETE /api/me/memories`   | Langzeit-Erinnerungen des Nutzers |
-| `WS   /ws/chat`                       | Echtzeit-Chat (Streaming-Events über WebSocket) |
+| `WS   /ws/chat`                       | Echtzeit-Chat (Text rein, Streaming-Events) |
+| `WS   /ws/voice`                      | Echtzeit-Sprache (Audio rein → STT → Antwort) |
 
 Endpunkt-/Provider-Auswahl ist über **Request-Body** (pro Aufruf), **Session**
 (`?session_id=…`) und **Defaults/Profil** steuerbar. Verwendete Route erscheint als
@@ -187,8 +188,8 @@ Device Router (strikt, Singleton); Output-Lifecycle; **Authentifizierung
 + dauerhafte Nutzer-Präferenzen**; **Gesprächsgedächtnis pro Session (Verlauf im
 Store, fließt ins LLM)**; **Langzeit-Erinnerungen pro Nutzer (als LLM-Kontext)**;
 **WebSocket-Streaming-Chat (`/ws/chat`) inkl. Token-Level-LLM-Streaming (SSE,
-`stream:true`) und satzweisem Audio-Streaming (chunked TTS, `audio_stream:true`)**;
+`stream:true`) und satzweisem Audio-Streaming (chunked TTS, `audio_stream:true`)**; **Sprach-Eingang
-automatisierte Tests.
+über WebSocket (`/ws/voice`: Audio rein → STT → Antwort-Pipeline)**; automatisierte Tests.
 
 **Platzhalter (Gerüst):** Audio-Endpunkte (`local-default`, `bluetooth`,
 `mobile-ws`, `mobile-webrtc`) liefern leere Chunks — nur Auswahl/Lifecycle sind
@@ -203,7 +204,7 @@ Reihenfolge der Weiterentwicklung:
 1. **(erledigt)** Konfig- & Routing-Fundament: Profile, Device Router, Registry, Pro-Request-Override.
 2. **(erledigt)** Cloud-Fundament: Bearer-Token-Auth, Mehrbenutzer, persistenter SQLite-Store, Mandanten-Trennung, dauerhafte Nutzer-Präferenzen. Offen: Skalierung auf gemeinsamen Store (Postgres/Redis) für mehrere Instanzen.
 3. **(erledigt)** Konversationsgedächtnis: Kurzzeit-Gesprächsverlauf pro Session + Langzeit-Erinnerungen pro Nutzer (manuell gepflegt, als LLM-Kontext). Offen: **automatische** Extraktion/Zusammenfassung von Erinnerungen aus Gesprächen.
-4. **(teilweise erledigt)** Echtzeit: WebSocket-Streaming-Chat (`/ws/chat`), **Token-Level-LLM-Streaming (SSE, `stream:true`)** und **Audio-Streaming (chunked TTS satzweise, `audio_stream:true`)** sind umgesetzt. Offen: **Audio-Eingang/Streaming-STT**, **Barge-in/Turn-Manager**, **WebRTC**.
+4. **(teilweise erledigt)** Echtzeit: WebSocket-Streaming-Chat (`/ws/chat`), **Token-Level-LLM-Streaming (SSE, `stream:true`)**, **Audio-Streaming (chunked TTS satzweise, `audio_stream:true`)** und **Audio-Eingang (`/ws/voice`: binaere Chunks -> STT -> Antwort-Pipeline)** sind umgesetzt. Offen: **partielle Live-Transkripte (Streaming-STT mit VAD)**, **Barge-in/Turn-Manager**, **WebRTC**.
 5. **Resilienz:** Fallback-Policy (remote KI fällt aus → lokaler/alternativer Provider), Metriken/Tracing.
 6. **Betrieb:** Kosten-/Quota-Kontrolle pro Nutzer; Notfall-/Eskalationskonzept (Senioren-Kontext).
 7. **TransportRouter** als eigene lokal/remote-Achse aktivieren.

README.md

@@ -88,7 +88,8 @@ Aktive Konfiguration prüfen: `curl http://localhost:8080/api/config`.
 | `GET  /api/me`                  | aktueller Nutzer + Präferenzen |
 | `PUT  /api/me/prefs`            | dauerhafte Routing-Präferenzen des Nutzers setzen |
 | `GET/POST/DELETE /api/me/memories` | Langzeit-Erinnerungen des Nutzers verwalten |
-| `WS   /ws/chat`                 | Echtzeit-Chat über WebSocket (Streaming-Events) |
+| `WS   /ws/chat`                 | Echtzeit-Chat über WebSocket (Text rein, Streaming-Events) |
+| `WS   /ws/voice`                | Echtzeit-Sprache (Audio rein → Transkript → Antwort) |
 
 Beispiel (Sprachausgabe an den Test-Loopback, lokaler TTS-Stub):
 
@@ -142,8 +143,14 @@ via SSE; Provider ohne Streaming liefern die komplette Antwort als ein `token`-E
 mit `seq` + binärer Frame) gesendet — die Ausgabe beginnt, bevor die Antwort fertig
 ist. `stream` und `audio_stream` lassen sich kombinieren.
 
-> Audio-Eingang/Streaming-STT, Barge-in/Turn-Manager und WebRTC sind als nächste
+**Sprach-Eingang (`/ws/voice`):** Der Client streamt Mikrofon-Audio als binäre
-> Increments vorgesehen (siehe Architektur-Dokument).
+Frames; ein `{"type":"end"}`-Control-Frame schließt die Äußerung ab. Der Server
+transkribiert (STT), sendet ein `transcript`-Event und durchläuft dann dieselbe
+Antwort-Pipeline wie `/ws/chat` (inkl. `stream`/`audio_stream`). Damit ist
+Sprach-zu-Sprach-Konversation über einen Kanal möglich.
+
+> Partielle Live-Transkripte (Streaming-STT mit VAD), Barge-in/Turn-Manager und
+> WebRTC sind als nächste Increments vorgesehen (siehe Architektur-Dokument).
 
 ## Authentifizierung
 

app/api/ws.py

@@ -1,14 +1,18 @@
-"""WebSocket-Streaming-Chat (Echtzeit-Transport, erster Increment).
+"""WebSocket-Echtzeit-Chat und -Sprache.
 
-Etabliert einen dauerhaften, bidirektionalen Kanal: der Client schickt pro Turn
+- /ws/chat : Text rein (JSON pro Turn), Antwort als Event-Folge zurueck.
-eine JSON-Nachricht, der Server streamt strukturierte Events zurueck
+- /ws/voice: Audio rein (binaere Chunks + Control), Transkription -> selbe Pipeline.
-(ack -> semantic -> audio (binaer) -> done). Auth, Session-Gedaechtnis und
-Langzeit-Erinnerungen gelten wie bei POST /api/chat.
 
-Bewusst spaeter (eigene Increments): Token-Level-LLM-Streaming, Audio-Eingang/
+Event-Folge der Antwort: ack -> [token*] -> [audio*] -> semantic -> done.
-Streaming-STT, Barge-in/Interrupt und WebRTC.
+Mit {"stream":true} kommen LLM-Token live, mit {"audio_stream":true} das Audio
+satzweise (chunked TTS). /ws/voice sendet zuvor ein transcript-Event.
+
+Spaeter (eigene Increments): partielle Live-Transkripte (Streaming-STT mit VAD),
+Barge-in/Turn-Manager und WebRTC.
 """
 
+import json
+
 from fastapi import APIRouter, WebSocket, WebSocketDisconnect
 
 from app.config import settings
@@ -23,6 +27,15 @@ from app.store import SessionOwnershipError
 
 router = APIRouter()
 
+_OVERRIDE_KEYS = (
+    "input_endpoint",
+    "output_endpoint",
+    "language",
+    "stt_provider",
+    "llm_provider",
+    "tts_provider",
+)
+
 
 def _authenticate(token: str | None):
     store = get_store()
@@ -33,58 +46,23 @@ def _authenticate(token: str | None):
     return store.get_user_by_token(token)
 
 
-@router.websocket("/ws/chat")
+async def _resolve(user, session_id, options):
-async def ws_chat(
+    """Loest Route + Orchestrator + Output-Endpunkt auf (kann RoutingError/Ownership werfen)."""
-    websocket: WebSocket,
+    overrides = {key: options.get(key) for key in _OVERRIDE_KEYS}
-    session_id: str | None = None,
-    token: str | None = None,
-):
-    user = _authenticate(token)
-    if user is None:
-        # Vor accept() schliessen -> Handshake wird mit 403 abgelehnt.
-        await websocket.close(code=1008)
-        return
-
-    await websocket.accept()
-    store = get_store()
-
-    try:
-        while True:
-            msg = await websocket.receive_json()
-            text = (msg.get("text") or "").strip()
-            if not text:
-                await websocket.send_json({"type": "error", "detail": "empty text"})
-                continue
-
-            overrides = {
-                key: msg.get(key)
-                for key in (
-                    "input_endpoint",
-                    "output_endpoint",
-                    "language",
-                    "stt_provider",
-                    "llm_provider",
-                    "tts_provider",
-                )
-            }
-
-            try:
     route = resolve_route(user, session_id, overrides)
     orchestrator = build_orchestrator(route)
     output = await resolve_output_endpoint(route)
+    return route, orchestrator, output
+
+
+async def _run_turn(websocket, store, user, session_id, route, orchestrator, output, text, options):
+    """Faehrt einen Antwort-Turn und streamt die Events an den Client."""
     conversation = (
         store.get_recent_messages(session_id, settings.history_max_messages)
         if session_id
         else []
     )
     memories = store.get_memories(user.id)
-            except SessionOwnershipError as exc:
-                await websocket.send_json({"type": "error", "status": 403, "detail": str(exc)})
-                continue
-            except RoutingError as exc:
-                await websocket.send_json({"type": "error", "status": 422, "detail": str(exc)})
-                continue
-
     llm_context = list(conversation)
     if memories:
         memory_text = "Was du ueber den Nutzer weisst:\n" + "\n".join(
@@ -94,9 +72,9 @@ async def ws_chat(
 
     await websocket.send_json({"type": "ack", "route": route.as_dict()})
 
-            voice = msg.get("voice") or settings.openrouter_tts_voice
+    voice = options.get("voice") or settings.openrouter_tts_voice
-            stream = bool(msg.get("stream"))
+    stream = bool(options.get("stream"))
-            audio_stream = bool(msg.get("audio_stream"))
+    audio_stream = bool(options.get("audio_stream"))
 
     on_token = None
     if stream:
@@ -134,24 +112,121 @@ async def ws_chat(
             )
     except Exception as exc:
         await websocket.send_json({"type": "error", "status": 502, "detail": str(exc)})
-                continue
+        return
 
     if session_id:
         store.append_message(session_id, user.id, "user", text)
         store.append_message(session_id, user.id, "assistant", trace.semantic_response)
 
     await websocket.send_json(
-                {
+        {"type": "semantic", "text": trace.semantic_response, "spoken": trace.spoken_response}
-                    "type": "semantic",
-                    "text": trace.semantic_response,
-                    "spoken": trace.spoken_response,
-                }
     )
-            # Bei audio_stream wurden die Audio-Chunks bereits live gesendet.
     if not audio_stream:
         await websocket.send_bytes(audio)
-            await websocket.send_json(
+    await websocket.send_json({"type": "done", "audio_format": "pcm", "sample_rate": 24000})
-                {"type": "done", "audio_format": "pcm", "sample_rate": 24000}
+
+
+@router.websocket("/ws/chat")
+async def ws_chat(websocket: WebSocket, session_id: str | None = None, token: str | None = None):
+    user = _authenticate(token)
+    if user is None:
+        await websocket.close(code=1008)
+        return
+    await websocket.accept()
+    store = get_store()
+
+    try:
+        while True:
+            msg = await websocket.receive_json()
+            text = (msg.get("text") or "").strip()
+            if not text:
+                await websocket.send_json({"type": "error", "detail": "empty text"})
+                continue
+            try:
+                route, orchestrator, output = await _resolve(user, session_id, msg)
+            except SessionOwnershipError as exc:
+                await websocket.send_json({"type": "error", "status": 403, "detail": str(exc)})
+                continue
+            except RoutingError as exc:
+                await websocket.send_json({"type": "error", "status": 422, "detail": str(exc)})
+                continue
+            await _run_turn(websocket, store, user, session_id, route, orchestrator, output, text, msg)
+    except WebSocketDisconnect:
+        return
+
+
+@router.websocket("/ws/voice")
+async def ws_voice(websocket: WebSocket, session_id: str | None = None, token: str | None = None):
+    user = _authenticate(token)
+    if user is None:
+        await websocket.close(code=1008)
+        return
+    await websocket.accept()
+    store = get_store()
+
+    audio_buffer = bytearray()
+    fmt = "wav"
+
+    try:
+        while True:
+            message = await websocket.receive()
+            if message["type"] == "websocket.disconnect":
+                return
+
+            if message.get("bytes") is not None:
+                audio_buffer.extend(message["bytes"])
+                continue
+
+            raw = message.get("text")
+            if raw is None:
+                continue
+            try:
+                control = json.loads(raw)
+            except ValueError:
+                await websocket.send_json({"type": "error", "detail": "invalid control frame"})
+                continue
+
+            ctype = control.get("type")
+            if ctype == "start":
+                audio_buffer.clear()
+                fmt = control.get("format", "wav")
+                continue
+            if ctype != "end":
+                continue
+
+            if not audio_buffer:
+                await websocket.send_json({"type": "error", "detail": "no audio received"})
+                continue
+
+            try:
+                route, orchestrator, output = await _resolve(user, session_id, control)
+            except SessionOwnershipError as exc:
+                await websocket.send_json({"type": "error", "status": 403, "detail": str(exc)})
+                audio_buffer.clear()
+                continue
+            except RoutingError as exc:
+                await websocket.send_json({"type": "error", "status": 422, "detail": str(exc)})
+                audio_buffer.clear()
+                continue
+
+            try:
+                transcript = await orchestrator.stt.transcribe(
+                    bytes(audio_buffer), fmt=fmt, language=route.language
+                )
+            except Exception as exc:
+                await websocket.send_json({"type": "error", "status": 502, "detail": str(exc)})
+                audio_buffer.clear()
+                continue
+            finally:
+                audio_buffer.clear()
+
+            await websocket.send_json({"type": "transcript", "text": transcript})
+            if not transcript or not transcript.strip():
+                await websocket.send_json({"type": "error", "detail": "empty transcript"})
+                continue
+
+            await _run_turn(
+                websocket, store, user, session_id, route, orchestrator, output, transcript, control
             )
     except WebSocketDisconnect:
         return

tests/test_ws.py

@@ -66,3 +66,51 @@ def test_ws_requires_token_when_auth_enabled(monkeypatch):
     with pytest.raises(WebSocketDisconnect):
         with client.websocket_connect("/ws/chat"):
             pass
+
+
+def _install_voice_stubs(monkeypatch):
+    class StubSTT:
+        async def transcribe(self, audio_bytes, fmt, language=None):
+            return f"erkannt({len(audio_bytes)})"
+
+    class StubLLM:
+        async def complete(self, text, history=None, session_id=None):
+            return f"Antwort zu {text}"
+
+    class StubTTS:
+        async def synthesize(self, text, voice=None, audio_format="pcm"):
+            return b"VOICEAUD"
+
+    monkeypatch.setitem(deps.STT_REGISTRY, "ss", lambda s: StubSTT())
+    monkeypatch.setitem(deps.LLM_REGISTRY, "ll", lambda s: StubLLM())
+    monkeypatch.setitem(deps.TTS_REGISTRY, "tt", lambda s: StubTTS())
+    return {
+        "stt_provider": "ss",
+        "llm_provider": "ll",
+        "tts_provider": "tt",
+        "output_endpoint": "loopback",
+    }
+
+
+def test_ws_voice_transcribes_and_answers(monkeypatch):
+    opts = _install_voice_stubs(monkeypatch)
+    with client.websocket_connect("/ws/voice?session_id=v1") as ws:
+        ws.send_bytes(b"PCMDATA")          # 7 Bytes
+        ws.send_bytes(b"MORE")             # 4 Bytes -> insgesamt 11
+        ws.send_json({"type": "end", **opts})
+
+        transcript = ws.receive_json()
+        assert transcript["type"] == "transcript" and transcript["text"] == "erkannt(11)"
+        assert ws.receive_json()["type"] == "ack"
+        semantic = ws.receive_json()
+        assert semantic["type"] == "semantic" and semantic["text"] == "Antwort zu erkannt(11)"
+        assert ws.receive_bytes() == b"VOICEAUD"
+        assert ws.receive_json()["type"] == "done"
+
+
+def test_ws_voice_empty_buffer_errors(monkeypatch):
+    opts = _install_voice_stubs(monkeypatch)
+    with client.websocket_connect("/ws/voice") as ws:
+        ws.send_json({"type": "end", **opts})  # kein Audio gesendet
+        err = ws.receive_json()
+        assert err["type"] == "error" and "no audio" in err["detail"]