From 303372f0b96e6965cd2af6d20669bd4019c82c2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dieter=20Schl=C3=BCter?= Date: Sun, 21 Jun 2026 15:27:34 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Admin-API=20(=C2=A77.1),=20Admin-Panel/?= =?UTF-8?q?Ger=C3=A4te-TTS/Presets=20+=20Verzeichnisstruktur=20nachziehen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- Docs/voice-assistant-architecture.md | 48 +++++++++++++++++++++++++--- README.md | 5 +-- 2 files changed, 46 insertions(+), 7 deletions(-) diff --git a/Docs/voice-assistant-architecture.md b/Docs/voice-assistant-architecture.md index 66b5315..580a247 100644 --- a/Docs/voice-assistant-architecture.md +++ b/Docs/voice-assistant-architecture.md @@ -170,7 +170,6 @@ ein No-op; `LoopbackOutput` sammelt die Chunks (testbar ohne Hardware). | `GET /api/devices` | verfügbare Audio-Endpunkte + Capabilities | | `POST /api/sessions/{id}/route` | bevorzugte Geräte/Provider/Sprache je Session | | `GET /api/config` | aktives Profil + aufgelöste Route (ohne Secrets) | -| `POST /api/admin/users` | Nutzer anlegen (Admin-Key) → Token einmalig | | `GET /api/me` · `PUT /api/me/prefs` | aktueller Nutzer + dauerhafte Präferenzen | | `GET/POST/DELETE /api/me/memories` | Langzeit-Erinnerungen des Nutzers | | `GET /api/metrics` | Metriken (JSON / Prometheus) | @@ -181,6 +180,32 @@ Endpunkt-/Provider-Auswahl ist über **Request-Body** (pro Aufruf), **Session** (`?session_id=…`) und **Defaults/Profil** steuerbar. Verwendete Route erscheint als `X-*`-Header bzw. im `?debug`-JSON. +### 7.1 Admin-API (alle hinter `require_admin`, Audit-geloggt) + +Trägt das Admin-Web-Panel (5 Bereiche + Übersicht-Dashboard). Schreibende Aktionen +werden ins Audit-Log geschrieben. + +| Methode & Pfad | Zweck | +|--------------------------------------------------|-------| +| `POST /api/admin/users` | Nutzer anlegen → Token einmalig | +| `GET /api/admin/users` | Nutzerliste | +| `PUT/DELETE /api/admin/users/{id}` | Nutzer ändern/löschen | +| `POST /api/admin/users/{id}/token` | Token neu ausstellen | +| `GET/POST/DELETE /api/admin/users/{id}/memories` | Erinnerungen je Nutzer | +| `GET /api/admin/users/{id}/sessions`·`/usage` | Sessions / Kontingent-Nutzung | +| `GET /api/admin/sessions/{id}/messages` | Gesprächsverlauf einsehen | +| `GET/PUT/DELETE /api/admin/config[/{key}]` | Live-Config lesen/setzen (z. B. `top_p`) | +| `GET /api/admin/llm/status` | LLM-/GPU-Status (read-only) | +| `POST /api/admin/llm/backend` | Backend wechseln (Ollama ↔ llama.cpp) | +| `POST /api/admin/gateway/restart` | Gateway aus dem Panel neu starten | +| `GET/POST/DELETE /api/admin/pronunciation/{lang}`| Aussprache-Lexika pflegen | +| `GET /api/admin/usage`·`/emergency-events` | Gesamt-Nutzung / Notfall-Ereignisse | +| `GET /api/admin/db-export` | SQLite-Export | +| `WS /api/admin/log` | Live-Log-Stream | + +Config-Änderungen sind als **Live** (sofort wirksam) oder **Restart** (Neustart nötig) +gekennzeichnet; der Backend-Wechsel und Live-Parameter wie `top_p` laufen ohne Neustart. + ## 8. Stand der Implementierung **Umgesetzt:** FastAPI-Gateway, alle o. g. REST-Endpunkte; OpenRouter-Adapter für @@ -195,7 +220,15 @@ Store, fließt ins LLM)**; **Langzeit-Erinnerungen pro Nutzer (als LLM-Kontext)* über WebSocket (`/ws/voice`: Audio rein → STT → Antwort-Pipeline) mit VAD-Aeusserungs- erkennung und Barge-in (`interrupt`)**; **Resilienz (Fallback-Ketten je Modul, In-Memory-Metriken `/api/metrics`), Tageskontingent pro Nutzer und heuristische -Notfall-Eskalation**; automatisierte Tests. +Notfall-Eskalation**; **Admin-Web-Panel (5 Bereiche + Übersicht-Dashboard) über die +Admin-API (§7.1) inkl. Backend-Wechsel, Gateway-Neustart, Live-Config-Parameter, +LLM-/GPU-Status, Aussprache-Lexika, Live-Log und Audit-Logging schreibender +Aktionen**; automatisierte Tests. + +**Web-/Mobil-Frontend:** schlankes Web-Interface unter `/` (Tailwind, kein Build), +mit **Geräte-TTS** (Browser-SpeechSynthesis auf Mobilgeräten; fällt auf Server-Audio +zurück, wenn keine lokalen Stimmen vorhanden) und **Ton-Presets** (Schnell → piper, +Hohe Qualität → chatterbox, Cloud → openrouter). Auth-Gate (Bearer-Token). **Echtes lokales STT & TTS:** `faster-whisper` (optionale Dependency `.[local]`, CTranslate2) transkribiert real; `piper` (in-process via piper-Python-API, Stimmmodell @@ -235,16 +268,21 @@ voice-assistant-scaffold/ │ ├── dependencies.py # Registries, ResolvedRoute, resolve_route, Store-/Router-Singleton │ ├── store.py # Persistenz: Store-Interface + SQLiteStore (Nutzer/Sessions/Verlauf) │ ├── auth.py # Bearer-Token-Auth (require_user) + Admin-Schutz +│ ├── audit.py # Audit-Log schreibender Admin-Aktionen +│ ├── admin_llm.py # LLM-/GPU-Status + Backend-Wechsel (Ollama ↔ llama.cpp) +│ ├── runtime_config.py # Live-Config (zur Laufzeit setzbare Parameter) │ ├── metrics.py # In-Memory-Metriken (Counter/Timer, JSON + Prometheus) │ ├── quota.py # Tageskontingent pro Nutzer (Kostenkontrolle) -│ ├── safety/ # emergency.py: heuristische Notfall-Erkennung/-Eskalation +│ ├── safety/ # emergency.py (Heuristik) + llm_classifier.py (Notfall-Klassifikation) │ ├── errors.py # RoutingError -> HTTP 422 │ ├── schemas.py # Pydantic-Modelle │ ├── api/ # health, chat, speak, transcribe, devices, sessions, config, admin, me, ws -│ ├── core/ # orchestrator +│ ├── core/ # orchestrator, memory_extractor (Auto-Erinnerungen), warmup (Modell-Vorladen) │ ├── audio/ # router, transport_router, vad, endpoints/input|output/* │ ├── pipeline/ # input_cleaner, spoken_response_adapter, tts_normalizer, sentence_chunker, german_numbers -│ └── providers/ # stt/ llm/ tts/ (openrouter + lokale Stubs) + fallback.py +│ ├── providers/ # stt/ llm/ tts/ (openrouter + lokale + chatterbox) + fallback.py +│ ├── utils/ # Hilfsfunktionen +│ └── web/ # Web-/Admin-Frontend (Tailwind, kein Build) ├── config/ # voice-assistant.example.toml (+ lokale .toml, gitignored) ├── data/ # SQLite-DB (gitignored) ├── deploy/ # systemd unit + env-Beispiel diff --git a/README.md b/README.md index fc1fc9f..d28ed79 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ Jede Achse — Hardware, Betrieb, Software — ist frei konfigurierbar, ohne Cod - **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) +- **Web-Interface** unter `/` (Tailwind, kein Build, mobiltauglich) mit Geräte-TTS (Browser-Sprachausgabe) und Ton-Presets (Schnell/Hohe Qualität/Cloud) +- **Admin-Panel** (5 Bereiche + Übersicht-Dashboard): Nutzer/Sessions, LLM-/GPU-Status, Backend-Wechsel + Gateway-Neustart, Live-Config, Aussprache-Lexika, Live-Log, Audit-Logging - **Keine Secrets im Code** — API-Keys nur über die Umgebung --- @@ -193,7 +194,7 @@ make llm-status # Container- und HTTP-Status prüfen ## Projektstruktur (Kurzform) ```text -app/ Gateway: config, api/, core/, audio/, pipeline/, providers/ +app/ Gateway: config, api/, core/, audio/, pipeline/, providers/, web/ (Frontend + Admin) 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