Voice-Agent

Self-hosted Transkriptions- und Protokollsystem für Sitzungsaufzeichnungen — vollständig lokal, DSGVO-konform.

Vollständiges Lastenheft: siehe need.md

Architektur

Benutzer
  │
  ▼  HTTP (Upload)
┌─────────────────────────────┐         ┌──────────────────────────────┐
│  LXC-Container              │  HTTP   │  Mac (Apple Silicon)         │
│  - FastAPI + HTML/JS UI     │ ──────► │  - FastAPI Worker            │
│  - SQLite Job-Store         │         │  - lightning-whisper-mlx     │
│  - Result-Verzeichnis       │ ◄────── │  - Ollama (llama3.1:8b)      │
│  - Nginx Reverse Proxy      │         │  - python-docx               │
└─────────────────────────────┘         └──────────────────────────────┘

• LXC: keine AI-Verarbeitung — nur Uploads, Job-Tracking, Auslieferung.
• Mac: Stateless API. Erhält Audio/Text, gibt Transkripte / Zusammenfassungen / Protokolle / DOCX zurück.

MVP-Funktionsumfang (v0.1)

• Audio-Upload (MP3, WAV, M4A, MP4, OGG, FLAC, max. 500 MB)
• Whisper-Transkription auf dem Mac
• Ollama-Zusammenfassung (Beschlüsse, Aufgaben, Teilnehmer)
• Strukturiertes Sitzungsprotokoll
• DOCX-Export
• Speaker-Diarization (Prio 2)
• Auth / Benutzerverwaltung (Prio 2)
• PDF-Export (Prio 2)

---

Installation — Schritt für Schritt

Voraussetzungen:

• Mac (Apple Silicon empfohlen, M1/M2/M3/M4) mit min. 16 GB RAM, besser 32 GB.
• Proxmox-Host für den LXC-Container.
• Netzwerk: Mac und LXC im selben LAN, der LXC muss den Mac auf Port 8080 erreichen.

Schritt 1 — LXC-Container provisionieren (Proxmox)

Entweder mit dem Toolkit-Skill /proxmox-lxc oder manuell ein Container mit:

• Debian 13 (Trixie) oder Ubuntu 24.04
• 2 vCPU, 2 GB RAM, 20 GB Disk reichen
• Statische LAN-IP, SSH-Zugang als root

Schritt 2 — App im LXC installieren

Im Container als root einloggen, dann eine der folgenden Optionen wählen:

Option A — Auto-Install per Curl (Repo wird selbst geklont):

bash <(curl -sSL https://git.cynfo.net/christian/voice-agent/raw/branch/main/deploy/install.sh)

Option B — Manuell aus geklontem Repo:

git clone https://git.cynfo.net/christian/voice-agent.git /var/www/voice-agent
cd /var/www/voice-agent
./deploy/install.sh

Das Skript installiert idempotent:

1. apt-Pakete (git python3-venv nginx ffmpeg ...)
2. Deploy-User deploy, klont/aktualisiert Repo nach /var/www/voice-agent
3. Python-venv + Dependencies in lxc-frontend/.venv
4. .env aus Vorlage anlegen (falls nicht vorhanden)
5. Verzeichnisse /var/lib/voice-agent/{uploads,results}
6. systemd-Service voice-agent.service (autostart, restart on-failure)
7. Nginx-Reverse-Proxy auf Port 80 → 127.0.0.1:8000

Erneutes Ausführen aktualisiert auf den neuesten main.

Schritt 3 — Mac-Worker einrichten

Auf dem Mac (Details in mac-worker/README.md):

# Repo holen
git clone https://git.cynfo.net/christian/voice-agent.git ~/voice-agent
cd ~/voice-agent/mac-worker

# Python-Umgebung
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
cp .env.example .env

# Ollama + Modell
brew install ollama
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"
brew services restart ollama
ollama pull llama3.1:8b

# Worker starten (Vordergrund — für Test)
uvicorn app.main:app --host 0.0.0.0 --port 8080

# Für Dauerbetrieb: als LaunchAgent registrieren
# (startet bei Login, restart nach Crash, Logs in ~/Library/Logs/)
./deploy/install-launchagent.sh

Test vom LXC aus:

curl http://<MAC-LAN-IP>:8080/health
# erwartet: {"status":"ok","whisper_engine":"mlx","ollama_reachable":true,...}

Schritt 4 — LXC mit Mac verbinden

Im LXC MAC_API_URL auf die Mac-LAN-IP setzen:

sudo nano /var/www/voice-agent/lxc-frontend/.env
# MAC_API_URL=http://192.168.x.y:8080
sudo systemctl restart voice-agent

Schritt 5 — Benutzen

Browser auf http://<LXC-IP>/ → Audio hochladen → fertig.

---

Update / Neudeployment

Auf dem LXC einfach nochmal:

sudo /var/www/voice-agent/deploy/install.sh

Auf dem Mac:

cd ~/voice-agent && git pull
cd mac-worker && source .venv/bin/activate && pip install -r requirements.txt
# Worker neu starten

---

Modelle

Transkription (Mac, Whisper)

WHISPER_ENGINE	WHISPER_MODEL	Wann nutzen
mlx	large-v3 (Default)	Maximale Qualität, langsamer (~0.3× Realzeit auf M2)
mlx	distil-large-v3	~5× schneller, minimal schlechtere Qualität
mlx	medium	Schneller, deutlich schlechter bei Fachbegriffen
faster	large-v3	Intel-Mac / Linux / CUDA
mock	–	Tests ohne Modell-Download

Standard ist mlx + large-v3. Für lange Sitzungen lohnt sich ein Test mit distil-large-v3. Alternativen (whisper.cpp + CoreML, WhisperX mit Diarization, Voxtral) sind in mac-worker/README.md dokumentiert.

Zusammenfassung (Ollama)

Standard: llama3.1:8b — solide Basisqualität bei deutschen Texten, ~8 GB Speicher.

Empfohlene Alternativen je nach Hardware (alle via ollama pull <name> und OLLAMA_MODEL=<name> in .env):

Modell	Größe	RAM-Bedarf	Stärken
llama3.1:8b (Default)	8 B	~8 GB	Schnell, brauchbares Deutsch
qwen2.5:14b	14 B	~10 GB	Sehr zuverlässige JSON-Ausgabe, exzellentes Deutsch
mistral-small:24b	24 B	~16 GB	Europäisch trainiert, beste Kompromiss-Wahl
gemma3:12b	12 B	~10 GB	Stark multilingual, gute Strukturierung
gpt-oss:20b	20 B	~14 GB	Sehr gute strukturierte Ausgabe (OpenAI Open-Weight)
llama3.3:70b	70 B	~48 GB	Top-Qualität, nur auf Macs mit 64 GB+

Für Sitzungsprotokolle (deutsch, viel JSON-Struktur) ist qwen2.5:14b oder mistral-small:24b der beste Sweet-Spot auf einem Mac mit 32 GB.

Detaillierte Bewertung siehe mac-worker/README.md.

---

Verzeichnisstruktur

voice-agent/
├── lxc-frontend/        # FastAPI Web-App (läuft im LXC)
│   ├── app/
│   ├── requirements.txt
│   └── .env.example
├── mac-worker/          # FastAPI AI-Worker (läuft auf dem Mac)
│   ├── app/
│   ├── requirements.txt
│   └── .env.example
├── deploy/              # systemd / nginx / install.sh
├── config/              # Toolkit-Konfiguration (project.env)
├── .claude/             # KI-Agenten Skills
├── need.md              # Lastenheft
└── README.md

Sicherheit

• Vollständig lokaler Betrieb. Keine Cloud-Calls.
• HTTPS via Reverse-Proxy ist Aufgabe der Infrastruktur (Let's Encrypt o. Ä.).
• Mac-Worker hat keine Auth — Betrieb nur im internen Netz.
• Uploads / Ergebnisse unter /var/lib/voice-agent/ — bei Bedarf Backup einplanen.