# Trixy Voice Assistant Ein professioneller, modularer Sprachassistent fuer verteilte Umgebungen mit Multi-Satellite-Support, Plugin-System und lokaler ML-Inferenz. **Version:** 1.0.0 | **Python:** 3.10+ | **Protokoll:** 1.0 --- ## Features - **Multi-Modus-Betrieb** — Server, Client (Satellite), Standalone oder Trainer - **Satellite-Management** — Mehrere Geraete mit automatischer Wakeword-Arbitrierung (hoechster Audio-Level gewinnt) - **Plugin-System** — 16 mitgelieferte Plugins, erweiterbar ueber Extension Points - **Eigenes Netzwerk-Protokoll** — Binaeres Protokoll (`TRXI`) mit AES-256-GCM-Verschluesselung auf 4 spezialisierten Ports - **Lokale ML-Inferenz** — Wakeword-Erkennung (OpenWakeWord), Sprecheridentifikation, LLM-Intent-Erkennung - **Event-getriebene Architektur** — Pub/Sub mit Prioritaeten, Middleware, Dead-Letter-Queue - **TUI** — Terminal-UI basierend auf Textual (deaktivierbar mit `--debug`) --- ## Schnellstart ### Voraussetzungen - Python 3.10+ - PyTorch - PortAudio (`sudo apt install portaudio19-dev` unter Linux) ### Installation ```bash git clone cd trixy7/source # Interaktive Installation (empfohlen) chmod +x install_linux.sh ./install_linux.sh ``` Das Installationsskript fuehrt durch Moduswahl, Konfiguration, Netzwerk-Setup und Autostart-Einrichtung. ### Manueller Start ```bash # Server — Zentraler Hub fuer Satellites python3 main.py server [--debug] [--config config/server_config.json] # Client — Leichtgewichtiger Satellite python3 main.py client --host --port 2101 --room --alias [--debug] # Standalone — All-in-One ohne Server python3 main.py standalone [--debug] [--config config/standalone_config.json] # Trainer — ML-Modelle trainieren python3 main.py train [wakeword|voice-recognition|all] ``` Alternativ ueber die Start-Skripte (fuehren Update + Bereinigung + Start durch): ```bash ./run_linux.sh server # Linux run_windows.bat standalone # Windows ``` --- ## Architektur ``` ┌─────────────────────────────────┐ │ Server │ │ ┌───────────┐ ┌──────────────┐ │ │ │ Plugins │ │ EventManager │ │ │ └───────────┘ └──────────────┘ │ │ ┌───────────┐ ┌──────────────┐ │ │ │ Satellite │ │ ML-Inferenz │ │ │ │ Manager │ │ (STT/NLP) │ │ │ └───────────┘ └──────────────┘ │ └──────┬───┬───┬───┬──────────────┘ │ │ │ │ Port 2101 ───┘ │ │ └─── Port 2104 (Commands) │ │ (Musik 48kHz) Port 2102─┘ └─Port 2103 (Audio In) (Audio Out) │ │ ┌──────┴───────────┴──────┐ │ Client (Satellite) │ │ ┌────────────────────┐ │ │ │ Wakeword-Erkennung │ │ │ │ (lokal, ONNX) │ │ │ └────────────────────┘ │ │ ┌─────────┐ ┌─────────┐ │ │ │ Mikrofon│ │ Speaker │ │ │ └─────────┘ └─────────┘ │ └───────────────────────────┘ ``` ### Ablauf einer Sprachanfrage 1. **Wakeword** — Client erkennt Wakeword lokal → Server wird benachrichtigt 2. **Arbitrierung** — Bei mehreren Satellites: 1 Sekunde warten, hoechster Audio-Level gewinnt 3. **Audio-Streaming** — Ausgewaehlter Client streamt Audio (16kHz mono) an Server 4. **STT** — Server transkribiert Sprache (Whisper/Vosk) 5. **Korrektur** — STT-Text durchlaeuft Korrektur-Pipeline (SymSpell, Phonetik, KenLM) 6. **NLP** — LLM erkennt Intent und extrahiert Slots 7. **Handler** — Plugin fuehrt Intent aus und liefert Daten 8. **Antwort** — LLM formuliert natuerliche Antwort → TTS → Audio zurueck an Client --- ## Verzeichnisstruktur ``` trixy7/source/ ├── main.py # Einstiegspunkt ├── trixy_core/ # Kern-Framework │ ├── service/ # Service-Container mit Prioritaeten │ ├── events/ # EventManager, Middleware, DLQ │ ├── network/ # Protokoll, Verschluesselung, Security │ ├── satellite/ # Satellite-Verwaltung, Registrierung │ ├── plugins/ # Plugin-System, Extension Points │ ├── wakeword/ # Wakeword-Erkennung (Client-seitig) │ ├── audio/ # Audio-Processing-Pipeline │ ├── nlp/ # Intent-Erkennung, Dispatcher │ ├── stt/ # STT-Korrektur (6 Schichten) │ ├── conversation/ # Konversations-Verwaltung │ ├── config/ # ConfigManager mit Dataclasses │ ├── tui/ # Terminal-UI (Textual) │ └── utils/ # Debug-Ausgabe, Version, Hilfsfunktionen ├── plugins/ # 16 mitgelieferte Plugins ├── config/ # JSON-Konfigurationen │ ├── server_config.json │ ├── client_config.json │ ├── standalone_config.json │ └── trainer_config.json ├── models/ # ML-Modelle │ ├── wakeword/ # Wakeword-Modelle (ONNX) │ ├── nlp/ # LLM (GGUF) │ └── piper/ # TTS-Modelle ├── trainer/ # ML-Training-Pipeline ├── assets/{profil}/ # Audio, Bilder, Daten (mit "default"-Fallback) ├── satellites/ # Registrierte Satellites (JSON pro MAC) ├── certs/ # Verschluesselungs-Keys, SSL-Zertifikate ├── bash/ # Update- und Prepare-Skripte ├── tests/ # Pytest-Tests └── docs/project_notes/ # Bugs, ADRs, Key-Facts ``` --- ## Plugins ### Mitgeliefert | Plugin | Version | Beschreibung | |--------|---------|-------------| | **music** | 1.0.0 | Musikwiedergabe ueber YouTube und lokale Dateien | | **nlp_llm** | 1.0.0 | LLM-basierte Intent-Erkennung (Llama, Qwen, Ollama) | | **notes** | 2.0.0 | Notizen per Sprachbefehl | | **timer** | 1.0.0 | Timer und Countdown | | **reminders** | 1.0.0 | Erinnerungen verwalten | | **calendar** | 1.0.0 | Kalender-Anbindung (Outlook, Google, CalDAV) | | **weather** | 1.0.0 | Wetter-Abfrage mit Cache | | **datetime_info** | 1.0.0 | Datum und Uhrzeit | | **crossfade** | 1.0.0 | Nahtlose Musik-Uebergaenge | ### STT-Provider | Plugin | Beschreibung | |--------|-------------| | **stt_whisper** | OpenAI Whisper — hohe Qualitaet, GPU-beschleunigt | | **stt_vosk** | Vosk — leichtgewichtig, offline, schnell | | **stt_deepspeech** | Mozilla DeepSpeech — Legacy | ### TTS-Provider | Plugin | Beschreibung | |--------|-------------| | **tts_piper** | Piper — lokal, schnell, gute Qualitaet (VITS) | | **tts_google** | Google Cloud TTS — Cloud-basiert, natuerlich | | **tts_coqui** | Coqui TTS — Open Source, vielseitig | ### Eigene Plugins erstellen ``` plugins/mein_plugin/ ├── main.py # Plugin-Klasse └── config.json # Konfiguration ``` ```python from trixy_core.plugins import TrixyPlugin from trixy_core.nlp.intents.decorator import intent from trixy_core.nlp.intents.result import IntentResult class MeinPlugin(TrixyPlugin): NAME = "mein_plugin" VERSION = "1.0.0" DESCRIPTION = "Beschreibung" AUTHOR = "Autor" async def on_load(self): pass @intent("mein_intent", slots={"param": str}) async def handle_intent(self, data) -> IntentResult: return IntentResult.success_with_response("Antwort!") ``` --- ## Netzwerk-Protokoll Trixy nutzt ein eigenes binaeres Protokoll auf 4 TCP-Ports: | Port | Zweck | Format | |------|-------|--------| | 2101 | Kommandos | AES-256-GCM verschluesselt | | 2102 | Audio-Input | 16kHz 16-bit PCM mono (Satellite → Server) | | 2103 | Audio-Output | 16kHz 16-bit PCM mono (Server → Satellite) | | 2104 | Musik-Stream | 48kHz 16-bit PCM stereo | **Protokoll-Header:** Magic `TRXI` + Version + Timestamp + 32-bit Flags + MD5 Checksum + Payload **Sicherheit:** - AES-256-GCM Verschluesselung fuer Kommandos - Optionale MAC-Adress-Whitelist - Rate-Limiting und DDoS-Schutz - TLS-Unterstuetzung (optional) --- ## Konfiguration Konfigurationen liegen als JSON in `config/` und werden beim Start automatisch geladen. File-Watching ermoeglicht Auto-Reload zur Laufzeit. **Wichtige Einstellungen:** ```jsonc // server_config.json { "network": { "bind_address": "0.0.0.0", // Bei Hotspot: "10.42.0.1" "command_port": 2101 }, "wakeword": { "models": ["custom", "system_command"], "threshold": 0.5, "arbitration_timeout_seconds": 1.0 } } // client_config.json { "server": { "host": "192.168.1.100", "port": 2101 }, "identity": { "room": "Wohnzimmer", "alias": "Echo-1" } } ``` --- ## ML-Modelle | Modell-Typ | Verzeichnis | Format | Beschreibung | |-----------|-------------|--------|-------------| | Wakeword | `models/wakeword/{name}/` | ONNX, PTH, PT | OpenWakeWord-basiert | | Sprecheridentifikation | `models/voice_recognition/` | ONNX, PTH | Dynamische Speaker-Anzahl | | NLP/LLM | `models/nlp/` | GGUF | Intent-Erkennung (Qwen, Llama) | | TTS | `models/piper/` | ONNX | Piper Sprachsynthese | **Audio-Spezifikation:** 16kHz, 16-bit PCM, Mono, Log-Mel-Spectrogram Features --- ## Tests ```bash pytest tests/ -v # Alle Tests pytest tests/test_network.py -v # Netzwerk-Tests pytest tests/ -k "satellite" # Nach Pattern filtern ``` --- ## Projektstruktur-Dokumentation Architekturentscheidungen, Bug-Fixes und Key-Facts werden in `docs/project_notes/` gepflegt: | Datei | Inhalt | |-------|--------| | `decisions.md` | Architekturentscheidungen (ADRs) mit Kontext und Trade-offs | | `bugs.md` | Bug-Log mit Ursachen und Loesungen | | `key_facts.md` | Projektkonfiguration und Referenzwerte | | `issues.md` | Abgeschlossene Arbeiten | --- ## Lizenz *Noch nicht festgelegt.*