Voice Assistant Gateway --- Modulares FastAPI-Gateway für einen **seniorengerechten Sprachassistenten** —
cloud-first, aber hybrid/lokal betreibbar, mit austauschbaren STT-/LLM-/TTS-Providern.
Jede Achse — Hardware, Betrieb, Software — ist frei konfigurierbar, ohne Code zu ändern.
- Python 73.7%
- JavaScript 19.1%
- HTML 4.7%
- Shell 1.9%
- Makefile 0.5%
8e48ab6d66
Barge-in im Sprech-Loop (voice_loop.py) war nur während der LLM-Phase zuverlässig. Während der Audio-Wiedergabe (nach done-Event) war der _stdin_watcher bereits gecancelt, sodass Enter ignoriert wurde oder als Spurious-Input in record_utterance() landete. Lösung: - _stdin_watcher läuft jetzt durch beide Phasen (LLM + Audio) - Phase 2: _close_player wird als asyncio-Task gegen den Watcher geract; Enter während der Wiedergabe killt den Player sofort - termios.tcflush nach jedem Turn verhindert Rest-Enters im stdin-Buffer Außerdem: OPENROUTER_API_KEY in .env ergänzt (systemd sourct kein .bashrc); Dokumentation entsprechend aktualisiert. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|---|---|---|
| app | ||
| config | ||
| deploy | ||
| Docs | ||
| scripts | ||
| tests | ||
| .env.example | ||
| .gitignore | ||
| BEDIENUNGSANLEITUNG.md | ||
| chat_client.py | ||
| docker-compose.yml | ||
| Dockerfile | ||
| LICENSE.md | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
Voice Assistant Gateway
Modulares FastAPI-Gateway für einen seniorengerechten Sprachassistenten — cloud-first, aber hybrid/lokal betreibbar, mit austauschbaren STT-/LLM-/TTS-Providern. Jede Achse — Hardware, Betrieb, Software — ist frei konfigurierbar, ohne Code zu ändern.
Features
- Sprach-Pipeline: STT → Input-Cleaner → LLM → Spoken-Adapter → TTS-Normalizer → TTS
- Provider austauschbar über Registry: OpenRouter (Cloud), faster-whisper (STT lokal), piper (TTS lokal, schnell), chatterbox (TTS lokal, hohe Qualität + Voice-Cloning)
- Geschichtete Konfiguration mit Profilen (
cloud/hybrid/local-dev) - Routing auf jeder Ebene: Global → Profil → Nutzer → Session → Request
- Authentifizierung (Bearer-Token) + persistente Nutzer/Sessions (SQLite)
- Resilienz: Fallback-Ketten je Modul + In-Memory-Metriken (JSON + Prometheus)
- Gesprächsgedächtnis pro Session (Verlauf) + Langzeit-Erinnerungen pro Nutzer (manuell + automatisch)
- WebSocket-Streaming: Token-Streaming (LLM), Audio-Streaming (satzweises TTS), Sprach-Eingang, VAD, Barge-in
- Notfall-Eskalation: zweistufig (Stichwörter + LLM-Klassifikation im Hintergrund)
- Web-Interface unter
/(Tailwind, kein Build, mobiltauglich) - Keine Secrets im Code — API-Keys nur über die Umgebung
Schnellstart (30 Sekunden)
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-... # für Cloud/Hybrid; bei local-dev nicht nötig
make run
Fehlt .env, wird sie aus .env.example erzeugt. Gateway läuft auf http://localhost:8080
(oder dem in .env gesetzten PORT).
curl http://localhost:8080/health # {"status":"ok"}
curl http://localhost:8080/api/config # aktives Profil + aufgelöste Provider
Sprechen → Antwort hören (CLI-Loop):
python scripts/voice_loop.py --session mein-gespraech
Web-Interface: Browser → http://localhost:8080/
Dokumentation
| Dokument | Zielgruppe | Inhalt |
|---|---|---|
| BEDIENUNGSANLEITUNG.md | alle | Installation, Betriebsprofile, Bedienung, Konfiguration, Admin, Deployment, Fehlerbehebung, Referenz |
| Docs/voice-assistant-architecture.md | Entwickler | Architekturprinzipien, Interfaces, Pipeline, Roadmap, Verzeichnisstruktur |
| deploy/README.md | Admin | Remote-Betrieb: nginx, YunoHost-SSO, systemd, Firewall, Chatterbox |
Einstiegspunkte je Zielgruppe:
- 👤 Endnutzer → BEDIENUNGSANLEITUNG § 5 (Bedienung)
- 🔧 Admin/Betreiber → BEDIENUNGSANLEITUNG § 2–4 (Installation + Profile), § 7–11 (Betrieb)
- 💻 Entwickler → BEDIENUNGSANLEITUNG § 2 + Architektur-Dokument
Projektstruktur (Kurzform)
app/ Gateway: config, api/, core/, audio/, pipeline/, providers/
config/ voice-assistant.example.toml (lokale .toml ist gitignored)
deploy/ systemd-Unit, nginx-Vorlage, env-Beispiel
scripts/ voice_loop.py, chat_client.py, smoke_e2e.py, add_pronunciation.py
scripts/llm-server/ start/stop/status-llm-server.sh (llama.cpp-Docker)
tests/ Pytest-Suite (offline + smoke)
Docs/ Architektur-Dokument
Lizenz
Proprietär — alle Rechte vorbehalten. Siehe LICENSE.md.