Trixy7

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

git clone <repository-url>
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

# Server — Zentraler Hub fuer Satellites
python3 main.py server [--debug] [--config config/server_config.json]

# Client — Leichtgewichtiger Satellite
python3 main.py client --host <server_ip> --port 2101 --room <raum> --alias <name> [--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):

./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

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:

// 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

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.