# Voice-Agent

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

> Vollständiges Lastenheft: siehe [`need.md`](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)

- [x] Audio-Upload (MP3, WAV, M4A, MP4, OGG, FLAC, max. 500 MB)
- [x] Whisper-Transkription auf dem Mac
- [x] Ollama-Zusammenfassung (Beschlüsse, Aufgaben, Teilnehmer)
- [x] Strukturiertes Sitzungsprotokoll
- [x] 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
bash <(curl -sSL https://git.cynfo.net/christian/voice-agent/raw/branch/main/deploy/install.sh)
```

**Option B — Manuell aus geklontem Repo:**

```bash
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`](mac-worker/README.md)):

```bash
# 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:

```bash
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:

```bash
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:

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

Auf dem Mac:

```bash
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`](mac-worker/README.md#alternative-transkriptions-engines) 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`](mac-worker/README.md#ollama-modell-wählen).

---

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