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>
2026-06-17 01:48:56 +02:00 · 2026-06-17 01:48:56 +02:00 · 293ed257db
commit 293ed257db
72 changed files with 2612 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,130 @@
+# Voice Assistant Gateway
+
+Modulares FastAPI-Gateway für einen **seniorengerechten Sprachassistenten** —
+cloud-first, aber hybrid/lokal betreibbar, mit austauschbaren Audio-Endpunkten und
+STT-/LLM-/TTS-Providern.
+
+Jede Achse — **Hardware** (Audio In/Out), **Betrieb** (lokal/cloud) und **Software**
+(lokale/remote KI) — ist frei konfigurierbar, ohne Code zu ändern. Konzept und
+Details: [`Docs/voice-assistant-architecture.md`](Docs/voice-assistant-architecture.md).
+Praktische Bedienung: [`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md).
+
+## Features
+
+- **Pipeline mit getrennter Semantik/Sprache:** STT → Input-Cleaner → LLM → Spoken-Adapter → TTS-Normalizer → TTS
+- **Provider austauschbar** über Registry (OpenRouter remote; faster-whisper/piper/chatterbox als lokale Stubs)
+- **Geschichtete Konfiguration** mit Profilen (`local-dev` / `hybrid` / `cloud`)
+- **Routing auf jeder Ebene:** Default → Profil → ENV → Session → Request
+- **REST-API** für Chat, Transkription, Sprachausgabe, Geräte, Sessions, Config
+- **Ohne Secrets im Code** — API-Keys nur über die Umgebung
+
+## Schnellstart
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e .[test]
+
+cp config/voice-assistant.example.toml config/voice-assistant.toml
+export OPENROUTER_API_KEY=sk-or-v1-...   # nur für Cloud-/Hybrid-Profile nötig
+make run
+```
+
+Fehlt `.env`, wird sie beim ersten `make run` aus `.env.example` erzeugt.
+Die App läuft dann auf `http://localhost:8080` (bzw. dem in `.env` gesetzten `PORT`).
+
+Kurztest:
+
+```bash
+curl http://localhost:8080/health
+curl http://localhost:8080/api/config
+```
+
+## Konfiguration & Profile
+
+Höhere Ebene gewinnt:
+
+```
+eingebaute Defaults  <  config/voice-assistant.toml (inkl. aktivem Profil)
+                     <  ENV / .env  <  Session-Route  <  Request
+```
+
+**Profile** umschalten per Umgebungsvariable (oder dauerhaft in `.env`):
+
+```bash
+VA_PROFILE=local-dev make run   # alles lokal (faster-whisper / lokales LLM / piper)
+VA_PROFILE=hybrid    make run   # STT/TTS remote, LLM lokal
+VA_PROFILE=cloud     make run   # alles über OpenRouter
+```
+
+> Secrets gehören **nicht** in `config/*.toml` — nur in die Umgebung
+> (`export OPENROUTER_API_KEY=…`). Gesetzte `DEFAULT_*_PROVIDER`-Werte in `.env`
+> überschreiben ein `VA_PROFILE`.
+
+**Pro Session:** `POST /api/sessions/{id}/route` (`input_endpoint`, `output_endpoint`,
+`stt_provider`, `llm_provider`, `tts_provider`, `language`), dann Aufrufe mit `?session_id=…`.
+
+**Pro Request:** dieselben Felder im Body von `/api/chat` bzw. `/api/speak`.
+
+Aktive Konfiguration prüfen: `curl http://localhost:8080/api/config`.
+
+## API-Überblick
+
+| Methode & Pfad                  | Zweck |
+|---------------------------------|-------|
+| `GET  /health`                  | Liveness-Check |
+| `POST /api/chat`                | Text rein → Audio raus (`?debug=true` → JSON-Trace) |
+| `POST /api/speak`               | Text rein → TTS-Audio raus |
+| `POST /api/transcribe`          | Audio-Upload → Transkript |
+| `GET  /api/devices`             | verfügbare Audio-Endpunkte + Capabilities |
+| `POST /api/sessions/{id}/route` | Geräte/Provider/Sprache je Session setzen |
+| `GET  /api/config`              | aktives Profil + aufgelöste Route (ohne Secrets) |
+
+Beispiel (Sprachausgabe an den Test-Loopback, lokaler TTS-Stub):
+
+```bash
+curl -X POST http://localhost:8080/api/speak \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Guten Morgen!","tts_provider":"piper","output_endpoint":"loopback"}'
+```
+
+Unbekannter Endpunkt/Provider → `HTTP 422` mit Klartext-Hinweis.
+
+## Tests
+
+```bash
+make test           # oder: pytest -q
+```
+
+Abgedeckt: Config-Profile & Präzedenz, Route-Auflösung, Device Router,
+End-to-End (Loopback, 422-Fälle, Session-/Request-Override, `/api/config`).
+
+## Port ändern
+
+```bash
+PORT=8003 make run                 # einmalig
+sed -i 's/^PORT=.*/PORT=8003/' .env  # dauerhaft
+PORT=8003 docker compose up         # mit Docker
+```
+
+## Deployment
+
+- **Docker:** `docker compose up --build` (reicht `OPENROUTER_API_KEY` aus der Shell durch)
+- **systemd:** Vorlagen unter `deploy/` (`voice-assistant.service`, `voice-assistant.env.example`)
+
+## Projektstruktur (Kurzform)
+
+```text
+app/        Gateway: config, dependencies, api/, core/, audio/, pipeline/, providers/
+config/     voice-assistant.example.toml (lokale .toml ist gitignored)
+deploy/     systemd-Unit + env-Beispiel
+tests/      Pytest-Suite
+Docs/       Architektur-Dokument
+```
+
+## Lizenz / Status
+
+Frühes, aktiv entwickeltes Projektgerüst. Audio-Hardware-/Streaming-Anbindung,
+Authentifizierung, Persistenz und Gedächtnis sind als nächste Schritte vorgesehen
+(siehe Roadmap im Architektur-Dokument).