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/providers/llm/base.py

@@ -0,0 +1,5 @@
+from abc import ABC, abstractmethod
+
+class LLMProvider(ABC):
+    @abstractmethod
+    async def complete(self, text: str, session_id: str | None = None) -> str: ...

app/providers/llm/local_openai_compatible.py

@@ -0,0 +1,24 @@
+import httpx
+from app.providers.llm.base import LLMProvider
+
+class LocalOpenAICompatibleLLM(LLMProvider):
+    def __init__(self, base_url: str, api_key: str, model: str):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+
+    async def complete(self, text: str, session_id: str | None = None) -> str:
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": text}],
+            "temperature": 0.3,
+        }
+        async with httpx.AsyncClient(timeout=120) as client:
+            response = await client.post(
+                f"{self.base_url}/chat/completions",
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                json=payload,
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data["choices"][0]["message"]["content"]

app/providers/llm/openrouter.py

@@ -0,0 +1,101 @@
+import httpx
+
+from app.providers.llm.base import LLMProvider
+
+
+SYSTEM_PROMPT = """
+You are a voice assistant for spoken conversations with older adults.
+
+Speak naturally, clearly, and calmly.
+Use short, simple sentences.
+Prefer plain everyday language over technical wording.
+Answer in the same language as the user, unless the user asks to switch languages.
+
+Important response rules:
+- Output plain text only.
+- No markdown.
+- No bullet points.
+- No numbered lists.
+- No tables.
+- No code.
+- No emojis.
+- No URLs unless the user explicitly asks for one.
+- Do not use asterisks, hashtags, or formatting symbols.
+- Do not write headings.
+- Do not use long disclaimers.
+
+Voice style rules:
+- Sound helpful, warm, and patient.
+- Keep answers brief by default: 1 to 3 short sentences.
+- If more detail is needed, explain step by step in natural spoken sentences.
+- Ask at most one follow-up question at a time.
+- If the answer contains several items, present them as natural speech, not as a list.
+- Use wording that sounds good when spoken aloud.
+- Avoid abbreviations when possible.
+- Avoid symbols when words are better.
+- Prefer complete spoken forms for dates, times, and numbers when useful.
+
+Safety and honesty rules:
+- If you are unsure, say so briefly and clearly.
+- Do not invent facts.
+- If current real-world information is needed and unavailable, say that clearly.
+
+Always optimize your answer for listening, not for reading.
+""".strip()
+
+
+class OpenRouterLLMProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str):
+        self.api_key = (api_key or "").strip()
+        self.model = (model or "").strip()
+
+    async def complete(self, text: str, session_id: str | None = None) -> str:
+        if not self.api_key:
+            raise ValueError("OPENROUTER_API_KEY is empty")
+        if not self.model:
+            raise ValueError("OPENROUTER_LLM_MODEL is empty")
+        if not text or not text.strip():
+            raise ValueError("LLM input text is empty")
+
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": text.strip()},
+            ],
+        }
+
+        timeout = httpx.Timeout(connect=10.0, read=120.0, write=30.0, pool=10.0)
+
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            try:
+                response = await client.post(
+                    "https://openrouter.ai/api/v1/chat/completions",
+                    headers={
+                        "Authorization": f"Bearer {self.api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json=payload,
+                )
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise RuntimeError(
+                    f"OpenRouter LLM error {exc.response.status_code}: {exc.response.text}"
+                ) from exc
+            except httpx.TimeoutException as exc:
+                raise RuntimeError("OpenRouter LLM timeout") from exc
+            except httpx.HTTPError as exc:
+                raise RuntimeError(f"OpenRouter LLM transport error: {exc}") from exc
+
+        data = response.json()
+
+        try:
+            content = data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise RuntimeError(f"Unexpected OpenRouter LLM response: {data}") from exc
+
+        if not content or not str(content).strip():
+            raise RuntimeError("OpenRouter LLM returned empty content")
+
+        return str(content).strip()
+

app/providers/stt/base.py

@@ -0,0 +1,5 @@
+from abc import ABC, abstractmethod
+
+class STTProvider(ABC):
+    @abstractmethod
+    async def transcribe(self, audio_bytes: bytes, fmt: str, language: str | None = None) -> str: ...

app/providers/stt/faster_whisper.py

@@ -0,0 +1,5 @@
+from app.providers.stt.base import STTProvider
+
+class FasterWhisperProvider(STTProvider):
+    async def transcribe(self, audio_bytes: bytes, fmt: str, language: str | None = None) -> str:
+        return "[local transcription placeholder]"

app/providers/stt/openrouter.py

@@ -0,0 +1,46 @@
+import httpx
+
+from app.providers.stt.base import STTProvider
+
+
+class OpenRouterSTTProvider(STTProvider):
+    def __init__(self, api_key: str, model: str):
+        self.api_key = (api_key or "").strip()
+        self.model = (model or "").strip()
+
+    async def transcribe(self, audio_bytes: bytes, fmt: str, language: str | None = None) -> str:
+        if not self.api_key:
+            raise ValueError("OPENROUTER_API_KEY is empty")
+        if not self.model:
+            raise ValueError("OPENROUTER_STT_MODEL is empty")
+        if not audio_bytes:
+            raise ValueError("STT input audio is empty")
+
+        # OpenAI-kompatibler /audio/transcriptions-Endpunkt erwartet multipart/form-data
+        # mit binärem file-Feld, nicht JSON mit base64.
+        files = {"file": (f"audio.{fmt}", audio_bytes, f"audio/{fmt}")}
+        data: dict[str, str] = {"model": self.model}
+        if language:
+            data["language"] = language
+
+        timeout = httpx.Timeout(connect=10.0, read=120.0, write=30.0, pool=10.0)
+
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            try:
+                response = await client.post(
+                    "https://openrouter.ai/api/v1/audio/transcriptions",
+                    headers={"Authorization": f"Bearer {self.api_key}"},
+                    files=files,
+                    data=data,
+                )
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise RuntimeError(
+                    f"OpenRouter STT error {exc.response.status_code}: {exc.response.text}"
+                ) from exc
+            except httpx.TimeoutException as exc:
+                raise RuntimeError("OpenRouter STT timeout") from exc
+            except httpx.HTTPError as exc:
+                raise RuntimeError(f"OpenRouter STT transport error: {exc}") from exc
+
+        return response.json().get("text", "")

app/providers/tts/base.py

@@ -0,0 +1,5 @@
+from abc import ABC, abstractmethod
+
+class TTSProvider(ABC):
+    @abstractmethod
+    async def synthesize(self, text: str, voice: str | None = None, audio_format: str = "pcm") -> bytes: ...

app/providers/tts/chatterbox.py

@@ -0,0 +1,5 @@
+from app.providers.tts.base import TTSProvider
+
+class ChatterboxTTSProvider(TTSProvider):
+    async def synthesize(self, text: str, voice: str | None = None, audio_format: str = "pcm") -> bytes:
+        return b""

app/providers/tts/openrouter.py

@@ -0,0 +1,62 @@
+import httpx
+
+from app.providers.tts.base import TTSProvider
+
+
+class OpenRouterTTSProvider(TTSProvider):
+    def __init__(self, api_key: str, model: str, voice: str):
+        self.api_key = (api_key or "").strip()
+        self.model = (model or "").strip()
+        self.voice = (voice or "").strip()
+
+    async def synthesize(
+        self,
+        text: str,
+        voice: str | None = None,
+        audio_format: str = "pcm",
+    ) -> bytes:
+        if not self.api_key:
+            raise ValueError("OPENROUTER_API_KEY is empty")
+        if not self.model:
+            raise ValueError("OPENROUTER_TTS_MODEL is empty")
+        if not text or not text.strip():
+            raise ValueError("TTS input text is empty")
+
+        effective_voice = (voice or self.voice).strip()
+        if not effective_voice:
+            raise ValueError("TTS voice is required for OpenRouter TTS")
+
+        payload = {
+            "model": self.model,
+            "input": text.strip(),
+            "voice": effective_voice,
+            "response_format": audio_format,
+        }
+
+        timeout = httpx.Timeout(connect=10.0, read=120.0, write=30.0, pool=10.0)
+
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            try:
+                response = await client.post(
+                    "https://openrouter.ai/api/v1/audio/speech",
+                    headers={
+                        "Authorization": f"Bearer {self.api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json=payload,
+                )
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise RuntimeError(
+                    f"OpenRouter TTS error {exc.response.status_code}: {exc.response.text}"
+                ) from exc
+            except httpx.TimeoutException as exc:
+                raise RuntimeError("OpenRouter TTS timeout") from exc
+            except httpx.HTTPError as exc:
+                raise RuntimeError(f"OpenRouter TTS transport error: {exc}") from exc
+
+        if not response.content:
+            raise RuntimeError("OpenRouter TTS returned empty audio content")
+
+        return response.content
+

app/providers/tts/piper.py

@@ -0,0 +1,5 @@
+from app.providers.tts.base import TTSProvider
+
+class PiperTTSProvider(TTSProvider):
+    async def synthesize(self, text: str, voice: str | None = None, audio_format: str = "pcm") -> bytes:
+        return b""