Trixy7/docs/project_notes/decisions.md

Architectural Decisions - Trixy Voice Assistant

Dieses Dokument protokolliert Architekturentscheidungen (ADRs) für das Projekt.

Format

• Datum und ADR-Nummer
• Kontext (warum die Entscheidung nötig war)
• Entscheidung (was gewählt wurde)
• Alternativen
• Konsequenzen (Trade-offs)

---

Entscheidungen

ADR-001: Service Container Pattern (2026-01-31)

Kontext:

• Benötigen zentrale Verwaltung aller Systemkomponenten
• Services haben Abhängigkeiten untereinander
• Lifecycle-Management für sauberes Starten/Stoppen

Entscheidung:

• Alle Services erben von IService mit PRIORITY, GROUP, DEPENDENCIES
• ServiceContainer verwaltet Registrierung, Start-Reihenfolge, Health-Checks
• Prioritätsbasierte Startreihenfolge mit Abhängigkeitsauflösung

Alternativen:

• Dependency Injection Framework (z.B. dependency-injector) → Abgelehnt: Zu viel Overhead für unser Use-Case
• Manuelle Initialisierung → Abgelehnt: Fehleranfällig, keine Lifecycle-Hooks

Konsequenzen:

• ✅ Klare Abhängigkeitsverwaltung
• ✅ Automatische Startreihenfolge
• ✅ Health-Checks und Auto-Restart
• ❌ Etwas Boilerplate für neue Services

ADR-002: Event-Driven Pub/Sub System (2026-01-31)

Kontext:

• Lose Kopplung zwischen Komponenten gewünscht
• Plugins müssen auf Ereignisse reagieren können
• Async Handler für Performance

Entscheidung:

• Zentraler EventManager mit Prioritätsstufen
• @TrixyEvent Decorator für einfache Handler-Registrierung
• Events sind abbrechbar (außer MONITOR-Priorität)

Alternativen:

• Direct Method Calls → Abgelehnt: Enge Kopplung
• Message Queue (Redis, RabbitMQ) → Abgelehnt: Overkill für lokales System
• Python Signals → Abgelehnt: Nicht async-kompatibel

Konsequenzen:

• ✅ Lose Kopplung
• ✅ Einfache Plugin-Integration
• ✅ Prioritätsbasierte Verarbeitung
• ❌ Debugging kann bei vielen Handlern schwieriger sein

ADR-003: Eigenes Binärprotokoll (Trixy Protocol) (2026-01-31)

Kontext:

• Effiziente Kommunikation zwischen Server und Satellites
• Verschlüsselung erforderlich
• Verschiedene Datentypen (Commands, Audio, Music)

Entscheidung:

• Eigenes binäres Protokoll mit Magic Number TRXI
• 4 separate Ports für Command, Audio-In, Audio-Out, Music
• AES-256-GCM Verschlüsselung für Command-Kanal
• Hard-coded Commands (PING, PONG, etc.) für Effizienz

Alternativen:

• gRPC → Abgelehnt: Zu viel Overhead für Audio-Streaming
• WebSocket + JSON → Abgelehnt: Nicht effizient genug für binäre Daten
• MQTT → Abgelehnt: Nicht für Audio-Streaming geeignet

Konsequenzen:

• ✅ Optimiert für Voice-Assistant Use-Case
• ✅ Effizientes Audio-Streaming
• ✅ Starke Verschlüsselung
• ❌ Eigene Implementierung zu pflegen
• ❌ Kein Standard-Tooling

ADR-004: Plugin-System mit Hot-Reload (2026-01-31)

Kontext:

• Erweiterbarkeit ohne Core-Änderungen
• Plugins sollen zur Laufzeit ladbar sein
• Einfache Plugin-Entwicklung

Entscheidung:

• Plugins in ./plugins/{name}/ mit main.py und config.json
• TrixyPlugin Basisklasse mit Lifecycle-Hooks
• Dynamisches Laden via importlib

Alternativen:

• Entry Points (setuptools) → Abgelehnt: Erfordert Installation
• Single-File Plugins → Abgelehnt: Keine Konfiguration möglich

Konsequenzen:

• ✅ Einfache Plugin-Entwicklung
• ✅ Hot-Reload möglich
• ✅ Separate Konfiguration pro Plugin
• ❌ Keine Isolation zwischen Plugins

ADR-005: Pluggable NLP mit Decorator-basierter Intent-Registrierung (2026-02-01)

Kontext:

• Intent-Erkennung aus STT-Output erforderlich
• Verschiedene NLP-Backends sollen unterstützt werden (LLM, rule-based)
• Pi 5 mit 4GB RAM als Zielplattform → Ressourcen-Limitierungen
• Plugins sollen eigene Intents deklarieren können

Entscheidung:

• IntentRegistry Singleton für globale Intent-Verwaltung
• @intent Decorator auf Plugin-Methoden für Intent-Deklaration
• NLPProvider Interface für austauschbare Backends
• Dual-Response-Flow: LLM liefert Antwort direkt ODER create_output_text Event

Architektur (korrigierter 3-Phasen-Flow):

Phase 1: Intent-Erkennung (LLM)
   speech_recognized → LLM → intent + slots (KEINE Antwort!)
                         ↓
Phase 2: Handler-Ausführung
   intent_received → Handler → führt Aktion aus, liefert Daten
                         ↓
Phase 3: Antwort-Generierung
   Handler-Ergebnis → LLM/Template → natürliche Antwort → TTS

Wichtig: Die Antwort wird NACH dem Handler generiert, damit:

• Wikipedia-Plugin Daten laden kann
• Smart-Home-Plugin Aktion bestätigen kann
• Wetter-Plugin aktuelle Daten einfügen kann

Alternativen:

• Rasa NLU → Abgelehnt: Zu ressourcenintensiv für Pi 5
• Statische Intent-Konfiguration → Abgelehnt: Keine Plugin-Erweiterbarkeit
• Zentrale Intent-Deklaration → Abgelehnt: Plugins können keine eigenen Intents

Konsequenzen:

• ✅ Plugins deklarieren Intents direkt am Handler
• ✅ Automatische Discovery via PluginManager
• ✅ LLM-basiert für komplexe Anfragen
• ✅ Fallback auf rule-based möglich
• ✅ Response-Text optional (einfache NLP ohne Textgenerierung)
• ❌ LLM benötigt ~800MB RAM
• ❌ Latenz bei LLM-Inferenz (~1-3s auf Pi 5)

Empfohlene Modelle für Pi 5:

• Llama 3.2 1B (~800MB) - Beste Balance
• Qwen2.5-0.5B (~400MB) - Schneller, niedrigere Qualität

ADR-006: Download-Events als typisierte EventData statt Dict (2026-02-27)

Kontext:

• Download-Funktionen nutzten emit() mit unstrukturierten Dicts
• Plugins konnten Downloads nur beobachten, nicht beeinflussen
• progress_callback Parameter war redundant (pprogress() existiert bereits)

Entscheidung:

• 6 typisierte EventData-Klassen in trixy_core/events/event_data/download.py
• trigger() statt emit() fuer alle Download-Events
• BeforeDownload und BeforeExtract sind cancellable — Plugins koennen URL/Pfad aendern oder Download verbieten
• progress_callback komplett entfernt

Alternativen:

• Nur progress_callback entfernen, emit() beibehalten → Abgelehnt: Verpasste Chance fuer Plugin-Einfluss
• Hook-System statt Events → Abgelehnt: Event-System bereits vorhanden und bewaehrt

Konsequenzen:

• ✅ Plugins koennen Downloads redirecten, verbieten, Speicherort aendern
• ✅ Typsichere Event-Daten statt freie Dicts
• ✅ Konsistent mit restlichem Event-System (trigger/EventData)
• ❌ Breaking Change fuer Code der auf alte Event-Namen hoert (download_started → before_download)

---

ADR-007: STT-Korrektur via Event-Prioritaet statt neuem Event (2026-02-28)

Kontext:

• STT-Ausgaben enthalten haeufig kontextuelle Fehler (echte Woerter im falschen Kontext)
• NLP-Plugin hatte primitive _correct_stt_text() mit nur 2 Aliases
• Korrektur muss vor NLP-Verarbeitung stattfinden

Entscheidung:

• STTCorrectorService registriert sich mit EventPriority.HIGH auf speech_recognized
• NLP-Plugin nutzt default NORMAL — Corrector laeuft immer zuerst
• Korrektur per in-place Modifikation von event_data.text (Referenzsemantik)
• Kein neues Event, kein Breaking Change

Alternativen:

• Neues stt_corrected Event einfuehren → Abgelehnt: Erfordert NLP-Plugin-Aenderung, verkompliziert Pipeline
• Korrektur im NLP-Plugin belassen → Abgelehnt: Nicht konfigurierbar, nicht erweiterbar, monolithisch
• Pre-Processing-Middleware im EventManager → Abgelehnt: Ueberengineered fuer diesen Anwendungsfall

Konsequenzen:

• ✅ Kein Breaking Change fuer bestehende Plugins
• ✅ Flexibel durch Layer-System (6 optionale Schichten)
• ✅ Graceful Degradation bei fehlenden Libraries
• ❌ Korrektur-Reihenfolge nur per Prioritaet steuerbar (nicht per explizitem Hook)
• ❌ Debugging schwieriger da Text still modifiziert wird (Log-Ausgabe hilft)

---

ADR-008: Plugin-basiertes Trainer-Framework mit Subprocess-Isolation (2026-03-06)

Kontext:

• ML-Trainings (Wakeword, TTS, LLM, Speaker Recognition) brauchen einheitliche Verwaltung
• Trainings sind GPU-intensiv und koennen OOM verursachen
• Config-Tool (TUI) soll Trainings remote steuern und visualisieren

Entscheidung:

• ITrainer ABC unabhaengig von TrixyPlugin (kein gemeinsames Erbe)
• Training in multiprocessing.Process mit Queue fuer Progress-Updates
• Schema-getriebene TUI: Trainer liefert FormSchema-Dicts, Views rendern generisch
• Polling statt Push: Config-Tool pollt Progress alle 2s (bestehendes Pattern)
• TrainerRegistry mit Auto-Discovery: core/.py + plugins//trainer.py

Alternativen:

• ITrainer als TrixyPlugin-Subklasse → Abgelehnt: Trainer brauchen Subprocess-Isolation, Plugins laufen im Event-Loop
• Threading statt Multiprocessing → Abgelehnt: GIL-Problem bei CPU-intensivem Training, kein OOM-Schutz
• WebSocket-Push fuer Progress → Abgelehnt: Komplexer, bestehendes Polling-Pattern reicht (2s Intervall)

Konsequenzen:

• ✅ OOM im Training toetet nur den Subprocess, nicht den Server
• ✅ Schema-getriebene Views: Neue Trainer brauchen keine TUI-Aenderungen
• ✅ Plugin-Trainer moeglich via plugins/*/trainer.py
• ❌ Subprocess-Start hat Overhead (~100ms), kein Hot-Reload
• ❌ Shared State nur via Queue/Flags (keine direkte Objektreferenz)

ADR-009: Multi-Engine TTS + Voice-Morphing fuer Wakeword-Trainer (2026-03-14)

Kontext:

• Wakeword-Trainer nutzte nur Piper TTS fuer Trainings-Datengenerierung
• Begrenzte Stimmvariation fuehrt zu weniger robusten Modellen
• Mehr TTS-Engines + Stimmveraenderung = vielfaeltigere Daten = bessere Generalisierung

Entscheidung:

• Neues trixy_core/trainer/core/tts_engines/ Paket mit ITTSEngine ABC
• 7 Engines: Piper, Edge TTS, gTTS, Coqui, eSpeak-NG, Bark, Voice-Cloning (KI)
• Engines sind optional — nicht installierte zeigen "Installieren"-Button in TUI
• Voice-Morphing via DSP (keine neuen Abhaengigkeiten):
  • VTLP (Vocal Tract Length Perturbation) fuer Formant-Verschiebung
  • LPC Source-Filter-Zerlegung fuer formant-erhaltenden Pitch-Shift
  • Hauchigkeit (Aspiration) via Bandpass-gefiltertem Rauschen
  • Jitter/Shimmer fuer natuerliche Mikro-Variation
  • 8 Presets: Male→Female, Female→Male, Adult→Child, Tiefe/Helle Stimme, Fluestern, Aeltere Stimme
• Voice-Cloning Engine: Coqui TTS XTTS/YourTTS mit Referenz-WAVs aus trainer/assets/voice_clones/
• Bug-Fix: Abgehackte Sample-Enden durch 15ms Fade-In/Out behoben

Alternativen Voice-Morphing:

• librosa/PyWorld als Abhaengigkeit → Abgelehnt: Keine neuen Deps gewuenscht
• RVC fuer Voice-Changing → Zu komplex fuer Training-Augmentation, besser als eigenes Feature spaeter
• Nur einfaches Pitch-Shifting → Abgelehnt: Chipmunk-Effekt ohne Formant-Erhaltung

Konsequenzen:

• ✅ Voice-Pool aus mehreren Engines fuer maximale Variation
• ✅ Voice-Morphing vervielfacht Samples ohne neue Abhaengigkeiten
• ✅ LPC + VTLP liefert natuerliche Stimmtransformation (kein Chipmunk)
• ✅ KI-Voice-Cloning optional fuer hoechste Qualitaet
• ✅ Fade-In/Out verhindert Klick-Artefakte
• ❌ LPC-basierter Pitch-Shift ist rechenintensiver als Resampling-Trick
• ❌ Voice-Cloning braucht Referenz-WAVs + Coqui TTS (~2GB)

ADR-010: HID Media Key Support fuer Satellites (2026-03-15)

Kontext:

• Konferenzmikrofone/Headsets (Jabra, Poly) haben standardisierte Media-Tasten
• "Anruf annehmen" (Hook/Call) Taste soll als Wakeword-Trigger dienen
• Lautstaerke und Mute sollen Hardware-seitig steuerbar sein
• Arbitration muss bei manuellem Trigger sofort entscheiden (kein 1s Fenster)

Entscheidung:

• Neues trixy_core/hid/ Package mit evdev-basiertem HIDService
• 5 Tasten: VOLUME_UP, VOLUME_DOWN, MUTE, HOOK, PLAY_PAUSE
• Hook-Taste loest wakeword_manual_trigger Event aus
• WakewordService.trigger_manual(): Synthetische Detection mit confidence=1.0, audio_level=1.0
• ArbitrationCandidate.forced=True: Arbitrator schliesst Fenster sofort (kein Warten)
• Auto-Detect: Scannt /dev/input/event* nach Geraeten mit Media-Key Capabilities

Alternativen:

• ALSA Mixer fuer Lautstaerke → Abgelehnt: Nur Lautstaerke, keine Hook-Taste
• PulseAudio/PipeWire Events → Abgelehnt: Nicht auf allen Systemen (Raspberry Pi OS Lite)
• hidapi statt evdev → Abgelehnt: evdev ist Linux-Standard, besser dokumentiert

Konsequenzen:

• ✅ Hardware-Tasten funktionieren out-of-the-box (Auto-Detect)
• ✅ Manueller Wakeword-Trigger ohne Sprachkommando
• ✅ Forcierte Arbitration — kein 1s Warten bei Tastendruck
• ❌ Nur Linux (evdev), kein Windows/macOS Support
• ❌ Benoetigt Leserechte auf /dev/input/event* (Gruppe 'input' oder root)
• ❌ evdev als optionale Abhaengigkeit (pip install evdev)

ADR-011: Online-Service mit Offline-Cache (2026-03-16)

Kontext:

• Trixy soll auch bei Verbindungsausfall eingeschraenkt funktionieren
• Wetter-Plugin, Kalender etc. sollen gecachte Daten liefern wenn offline
• Kein zentraler HTTP-Client — Plugins nutzen jeweils eigene aiohttp-Sessions
• Kein Monitoring ob Internet verfuegbar ist

Entscheidung:

• Neues trixy_core/online/ Package mit 3 Komponenten:
  1. OnlineService(IService): Periodischer Connectivity-Check (TCP auf DNS-Port 53)
     • Online: alle 5 Min pruefen, Offline: jede 1 Min
     • Properties: is_online, is_offline, online_since, offline_since
     • Event: online_status_changed
  2. HttpClient: Async HTTP GET/POST/PUT/DELETE + Download + FTP/SFTP
     • download_to_file(), download_to_string()
     • Transparenter Offline-Cache ueber cache_ttl Parameter
     • Bei Netzwerk-Fehler: automatischer Fallback auf Cache
  3. ResponseCache: Persistenter SHA256-basierter Datei-Cache
     • Speichert in cache/online_cache/{hash}.json
     • TTL-basiert, aber ignore_ttl=True im Offline-Modus

Alternativen:

• requests statt aiohttp → Abgelehnt: Synchron, blockiert Event-Loop
• Redis/SQLite Cache → Abgelehnt: Zusaetzliche Abhaengigkeit, Dateisystem reicht
• ICMP Ping fuer Connectivity → Abgelehnt: Braucht root, TCP Port 53 ist zuverlaessiger

Konsequenzen:

• ✅ Plugins koennen online.http.get(url, cache_ttl=3600) nutzen — funktioniert auch offline
• ✅ Zentraler Connectivity-Status fuer alle Komponenten
• ✅ FTP/SFTP fuer Modell-Downloads von internen Servern
• ✅ Cache ueberlebt Neustarts (persistent auf Festplatte)
• ❌ aiohttp als Abhaengigkeit (ist aber bereits ueber Plugins vorhanden)
• ❌ Cache kann veraltet sein — TTL ist Schätzung, nicht Garantie

---

Tipps

• ADRs sequentiell nummerieren (ADR-001, ADR-002, etc.)
• Immer Datum angeben
• Trade-offs ehrlich dokumentieren (✅ und ❌)
• Alternativen kurz aber klar halten
• Bei Änderungen die Entscheidung aktualisieren