my_voice_assistant_v3_jamulix/README.md

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. Praktische Bedienung: 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

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:

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):

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):

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

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

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)

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).