5b9b9bbdcf
README.md auf kompakte Landing Page reduziert (~84 Zeilen): Kurzbeschreibung, Features, 30-Sekunden-Quickstart, Dokumentenübersicht mit Zielgruppen-Einstiegspunkten, Projektstruktur. BEDIENUNGSANLEITUNG.md von Grund auf neu geschrieben (~1530 Zeilen): - Klickbares Inhaltsverzeichnis (14 Abschnitte + 4 Anhänge) - Zielgruppen-Labels je Abschnitt (👤 Endnutzer / 🔧 Admin / 💻 Entwickler) - Konsolidierte Profilbeschreibungen (cloud/hybrid/local-dev) mit Hardware, Software, Kosten, Latenz, Qualität, Einrichtungsbefehlen — alles an einer Stelle - Vollständige Querverweise zwischen Abschnitten - Anhang A: alle Umgebungsvariablen als vollständige Referenz - Anhang B: alle API-Endpunkte (REST + WebSocket) mit Event-Typen - Anhang C: Provider-Übersicht - Anhang D: Sachregister mit >40 Einträgen Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.4 KiB
3.4 KiB
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.