my_voice_assistant_v3/BEDIENUNGSANLEITUNG.md

Bedienungsanleitung — Voice Assistant Gateway

Diese Anleitung führt Schritt für Schritt durch Installation, Start, Konfiguration und Fehlerbehebung. Technische Hintergründe stehen im Architektur-Dokument, eine kompakte Übersicht im README.

---

1. Voraussetzungen

• Python 3.11 oder neuer (python3 --version)
• Ein OpenRouter-API-Key — nur nötig, wenn ein Profil entfernte KI nutzt (hybrid, cloud). Für rein lokalen Betrieb (local-dev) nicht erforderlich.
• Optional: Docker, falls im Container betrieben.

---

2. Installation

cd voice-assistant-scaffold
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .[test]

Danach die zentrale Konfigurationsdatei anlegen:

cp config/voice-assistant.example.toml config/voice-assistant.toml

---

3. API-Key hinterlegen (für Cloud/Hybrid)

Der Schlüssel wird aus der Umgebung gelesen und gehört nicht in eine Datei. Dauerhaft am besten in ~/.bashrc:

echo 'export OPENROUTER_API_KEY=sk-or-v1-DEIN_KEY' >> ~/.bashrc
chmod 600 ~/.bashrc
source ~/.bashrc

Prüfen, ob er ankommt:

echo ${OPENROUTER_API_KEY:0:8}    # zeigt nur den Anfang

Sicherheit: Den Key niemals in .env oder config/*.toml schreiben. Wird ein Key versehentlich öffentlich, im OpenRouter-Dashboard löschen (= widerrufen) und neu erzeugen.

---

4. Betriebsart (Profil) wählen

Profile bestimmen, welche KI-Module genutzt werden:

Profil	Bedeutung	Key nötig?
local-dev	alles lokal (eigene KI/Hardware)	nein
hybrid	STT/TTS über Cloud, Haupt-LLM lokal	ja
cloud	alles über OpenRouter (Standardbetrieb)	ja

Profil einmalig für einen Start:

VA_PROFILE=cloud make run

Profil dauerhaft — in .env eintragen:

VA_PROFILE=cloud

Hinweis: Stehen in .env noch DEFAULT_STT_PROVIDER / DEFAULT_LLM_PROVIDER / DEFAULT_TTS_PROVIDER, überschreiben diese das Profil. Für profilbasiertes Umschalten sollten sie auskommentiert sein.

---

5. Starten und Stoppen

make run

Standard-Adresse: http://localhost:8080 (Port änderbar, siehe Abschnitt 8). Beenden mit Strg + C.

Schnelltest in einem zweiten Terminal:

curl http://localhost:8080/health
# {"status":"ok"}

curl http://localhost:8080/api/config
# zeigt aktives Profil und die aufgelöste Standard-Route

---

6. Tägliche Bedienung — typische Aufgaben

a) Text sprechen lassen (/api/speak)

curl -X POST http://localhost:8080/api/speak \
  -H 'Content-Type: application/json' \
  -d '{"text":"Guten Morgen, wie geht es Ihnen?"}' \
  --output antwort.pcm

b) Chatten (Text rein, gesprochene Antwort raus) (/api/chat)

Nur den Trace als JSON ansehen (ohne Audio):

curl -X POST "http://localhost:8080/api/chat?debug=true" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Wie wird das Wetter morgen?"}'

Komfortabler mit dem mitgelieferten Client (spielt die Antwort ab):

python chat_client.py "Erzähl mir einen guten Morgen-Spruch"

chat_client.py erwartet den Dienst auf Port 8003 — bei Bedarf im Skript GATEWAY_URL anpassen oder den Dienst mit PORT=8003 make run starten.

c) Audio transkribieren (/api/transcribe)

curl -X POST http://localhost:8080/api/transcribe \
  -F "file=@aufnahme.wav" -F "language=de"

d) Gerät oder Provider einmalig umstellen (pro Aufruf)

curl -X POST http://localhost:8080/api/speak \
  -H 'Content-Type: application/json' \
  -d '{"text":"Test","tts_provider":"piper","output_endpoint":"loopback"}'

e) Präferenzen für eine Session festlegen

# einmal setzen
curl -X POST http://localhost:8080/api/sessions/oma-anna/route \
  -H 'Content-Type: application/json' \
  -d '{"llm_provider":"openrouter","language":"de"}'

# danach mit dieser Session nutzen
curl -X POST "http://localhost:8080/api/chat?session_id=oma-anna&debug=true" \
  -H 'Content-Type: application/json' -d '{"text":"Hallo!"}'

---

7. Verfügbare Geräte und Bausteine ansehen

curl http://localhost:8080/api/devices    # Audio-Endpunkte mit Fähigkeiten
curl http://localhost:8080/api/config     # Profil, Route, Provider, Endpunkte

---

8. Port ändern

PORT=8003 make run                      # einmalig
sed -i 's/^PORT=.*/PORT=8003/' .env     # dauerhaft

---

9. Mit Docker betreiben

export OPENROUTER_API_KEY=sk-or-v1-...
docker compose up --build

Der Key wird aus der Shell in den Container durchgereicht; fehlt er, bricht der Start mit klarer Meldung ab.

---

10. Fehlerbehebung

Symptom	Ursache	Lösung
OPENROUTER_API_KEY is empty / 401	Key nicht in der Umgebung	export OPENROUTER_API_KEY=…, neues Terminal / source ~/.bashrc
HTTP 422 „Unbekannter …-Provider/Endpunkt"	Tippfehler in *_provider / *_endpoint	gültige Werte via GET /api/config prüfen
VA_PROFILE wirkt nicht	DEFAULT_*_PROVIDER in .env überschreibt es	diese Zeilen in .env auskommentieren
LLM-Timeout / Connection refused (lokal)	lokaler LLM-Server (Port 11434) läuft nicht	LLM-Server starten oder Profil cloud wählen
Address already in use	Port belegt	anderen PORT setzen (Abschnitt 8)
chat_client.py bekommt keine Antwort	Client nutzt Port 8003	Dienst mit PORT=8003 starten oder GATEWAY_URL anpassen
Profil greift nicht / Standardwerte	config/voice-assistant.toml fehlt	Datei aus *.example.toml kopieren (Abschnitt 2)

Logs erscheinen im Terminal, in dem make run läuft. Für mehr Details LOG_LEVEL=debug in .env setzen.

---

11. Tests ausführen

make test

Alle Tests sollten grün sein. Schlägt etwas fehl, gibt die Ausgabe den genauen Testnamen und die Ursache an.