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>
84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# 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)
|
||
|
||
```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-... # 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`).
|
||
|
||
```bash
|
||
curl http://localhost:8080/health # {"status":"ok"}
|
||
curl http://localhost:8080/api/config # aktives Profil + aufgelöste Provider
|
||
```
|
||
|
||
Sprechen → Antwort hören (CLI-Loop):
|
||
```bash
|
||
python scripts/voice_loop.py --session mein-gespraech
|
||
```
|
||
|
||
Web-Interface: Browser → `http://localhost:8080/`
|
||
|
||
---
|
||
|
||
## Dokumentation
|
||
|
||
| Dokument | Zielgruppe | Inhalt |
|
||
|----------|-----------|--------|
|
||
| **[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md)** | alle | Installation, Betriebsprofile, Bedienung, Konfiguration, Admin, Deployment, Fehlerbehebung, Referenz |
|
||
| **[Docs/voice-assistant-architecture.md](Docs/voice-assistant-architecture.md)** | Entwickler | Architekturprinzipien, Interfaces, Pipeline, Roadmap, Verzeichnisstruktur |
|
||
| **[deploy/README.md](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)
|
||
|
||
```text
|
||
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](LICENSE.md).
|