293ed257db
- 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>
130 lines
4.6 KiB
Markdown
130 lines
4.6 KiB
Markdown
# 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).
|