Initial commit: Voice Assistant Gateway mit Konfig-/Routing-Fundament

- FastAPI-Gateway mit REST-Endpunkten (chat/speak/transcribe/devices/sessions/config)
- Geschichtete Konfiguration mit Profilen (local-dev/hybrid/cloud) via TOML + ENV
- Registry-Pattern + einheitliche Route-Aufloesung (Default->Profil->ENV->Session->Request)
- Device Router (strikt, Singleton) und Output-Lifecycle im Orchestrator
- OpenRouter-Adapter (STT multipart/LLM/TTS) + lokale Provider-Stubs
- Regelbasierte Pipeline (Cleaner/Spoken-Adapter/TTS-Normalizer)
- 22 automatisierte Tests; Doku: README, BEDIENUNGSANLEITUNG, Architektur
- Secrets ausschliesslich ueber Umgebung; .env und lokale config gitignored

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

app/audio/endpoints/input/base.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class AudioInputEndpoint(ABC):
+    endpoint_id: str
+
+    @abstractmethod
+    async def capabilities(self) -> EndpointCapabilities: ...
+
+    @abstractmethod
+    async def open(self) -> None: ...
+
+    @abstractmethod
+    async def read_chunk(self) -> AudioChunk: ...
+
+    @abstractmethod
+    async def close(self) -> None: ...

app/audio/endpoints/input/bluetooth.py

@@ -0,0 +1,23 @@
+from app.audio.endpoints.input.base import AudioInputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class BluetoothInput(AudioInputEndpoint):
+    endpoint_id = "bt-headset-01"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="bluetooth",
+            direction="input",
+            latency_class="medium",
+            bluetooth=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def read_chunk(self) -> AudioChunk:
+        return AudioChunk(data=b"", format="wav", timestamp_ms=0)
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/input/local_default.py

@@ -0,0 +1,24 @@
+from app.audio.endpoints.input.base import AudioInputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class LocalDefaultInput(AudioInputEndpoint):
+    endpoint_id = "local-default-mic"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="local-default",
+            direction="input",
+            latency_class="low",
+            supports_barge_in=True,
+            default=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def read_chunk(self) -> AudioChunk:
+        return AudioChunk(data=b"", format="wav", timestamp_ms=0)
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/input/mobile_webrtc.py

@@ -0,0 +1,25 @@
+from app.audio.endpoints.input.base import AudioInputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class MobileWebRTCInput(AudioInputEndpoint):
+    endpoint_id = "mobile-webrtc-client"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="mobile-webrtc",
+            direction="input",
+            latency_class="low",
+            networked=True,
+            mobile=True,
+            supports_barge_in=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def read_chunk(self) -> AudioChunk:
+        return AudioChunk(data=b"", format="wav", timestamp_ms=0)
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/input/mobile_ws.py

@@ -0,0 +1,24 @@
+from app.audio.endpoints.input.base import AudioInputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class MobileWebSocketInput(AudioInputEndpoint):
+    endpoint_id = "mobile-ws-client"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="mobile-ws",
+            direction="input",
+            latency_class="medium",
+            networked=True,
+            mobile=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def read_chunk(self) -> AudioChunk:
+        return AudioChunk(data=b"", format="wav", timestamp_ms=0)
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/output/base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class AudioOutputEndpoint(ABC):
+    endpoint_id: str
+
+    @abstractmethod
+    async def capabilities(self) -> EndpointCapabilities: ...
+
+    @abstractmethod
+    async def open(self) -> None: ...
+
+    @abstractmethod
+    async def write_chunk(self, chunk: AudioChunk) -> None: ...
+
+    @abstractmethod
+    async def flush(self) -> None: ...
+
+    @abstractmethod
+    async def close(self) -> None: ...

app/audio/endpoints/output/bluetooth.py

@@ -0,0 +1,26 @@
+from app.audio.endpoints.output.base import AudioOutputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class BluetoothOutput(AudioOutputEndpoint):
+    endpoint_id = "bt-speaker-01"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="bluetooth",
+            direction="output",
+            latency_class="medium",
+            bluetooth=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def write_chunk(self, chunk: AudioChunk) -> None:
+        return None
+
+    async def flush(self) -> None:
+        return None
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/output/local_default.py

@@ -0,0 +1,26 @@
+from app.audio.endpoints.output.base import AudioOutputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class LocalDefaultOutput(AudioOutputEndpoint):
+    endpoint_id = "local-default-speaker"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="local-default",
+            direction="output",
+            latency_class="low",
+            default=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def write_chunk(self, chunk: AudioChunk) -> None:
+        return None
+
+    async def flush(self) -> None:
+        return None
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/output/loopback.py

@@ -0,0 +1,28 @@
+from app.audio.endpoints.output.base import AudioOutputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class LoopbackOutput(AudioOutputEndpoint):
+    endpoint_id = "loopback-output"
+
+    def __init__(self):
+        self.chunks = []
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="loopback",
+            direction="output",
+            latency_class="low",
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def write_chunk(self, chunk: AudioChunk) -> None:
+        self.chunks.append(chunk)
+
+    async def flush(self) -> None:
+        return None
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/output/mobile_webrtc.py

@@ -0,0 +1,27 @@
+from app.audio.endpoints.output.base import AudioOutputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class MobileWebRTCOutput(AudioOutputEndpoint):
+    endpoint_id = "mobile-webrtc-client"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="mobile-webrtc",
+            direction="output",
+            latency_class="low",
+            networked=True,
+            mobile=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def write_chunk(self, chunk: AudioChunk) -> None:
+        return None
+
+    async def flush(self) -> None:
+        return None
+
+    async def close(self) -> None:
+        return None

app/audio/endpoints/output/mobile_ws.py

@@ -0,0 +1,27 @@
+from app.audio.endpoints.output.base import AudioOutputEndpoint
+from app.schemas import AudioChunk, EndpointCapabilities
+
+class MobileWebSocketOutput(AudioOutputEndpoint):
+    endpoint_id = "mobile-ws-client"
+
+    async def capabilities(self) -> EndpointCapabilities:
+        return EndpointCapabilities(
+            id=self.endpoint_id,
+            kind="mobile-ws",
+            direction="output",
+            latency_class="medium",
+            networked=True,
+            mobile=True,
+        )
+
+    async def open(self) -> None:
+        return None
+
+    async def write_chunk(self, chunk: AudioChunk) -> None:
+        return None
+
+    async def flush(self) -> None:
+        return None
+
+    async def close(self) -> None:
+        return None

app/audio/router.py

@@ -0,0 +1,38 @@
+from app.errors import UnknownEndpointError
+
+
+class AudioRouter:
+    def __init__(self, inputs, outputs):
+        self.inputs = inputs
+        self.outputs = outputs
+
+    async def list_inputs(self):
+        return [await endpoint.capabilities() for endpoint in self.inputs]
+
+    async def list_outputs(self):
+        return [await endpoint.capabilities() for endpoint in self.outputs]
+
+    async def select_input(self, preferred: str | None = None):
+        return await self._select(self.inputs, preferred, direction="input")
+
+    async def select_output(self, preferred: str | None = None):
+        return await self._select(self.outputs, preferred, direction="output")
+
+    async def _select(self, endpoints, preferred: str | None, direction: str):
+        # Capabilities einmal sammeln (Basis fuer spaetere capability-basierte Auswahl).
+        pairs = [(endpoint, await endpoint.capabilities()) for endpoint in endpoints]
+
+        if preferred:
+            for endpoint, caps in pairs:
+                if caps.id == preferred or caps.kind == preferred:
+                    return endpoint
+            # Angefragter Endpunkt existiert nicht -> KEIN stiller Default-Fallback.
+            available = sorted({caps.id for _, caps in pairs} | {caps.kind for _, caps in pairs})
+            raise UnknownEndpointError(
+                f"Unbekannter {direction}-Endpunkt {preferred!r}. Verfuegbar: {available}"
+            )
+
+        for endpoint, caps in pairs:
+            if caps.default:
+                return endpoint
+        raise RuntimeError(f"Kein {direction}-Standardendpunkt verfuegbar")

app/audio/transport_router.py

@@ -0,0 +1,11 @@
+class TransportRouter:
+    def __init__(self, local_registry: dict, remote_registry: dict):
+        self.local_registry = local_registry
+        self.remote_registry = remote_registry
+
+    def resolve(self, module_type: str, provider_name: str):
+        if provider_name in self.local_registry.get(module_type, {}):
+            return self.local_registry[module_type][provider_name]
+        if provider_name in self.remote_registry.get(module_type, {}):
+            return self.remote_registry[module_type][provider_name]
+        raise KeyError(f"Unknown provider: {module_type}/{provider_name}")