# proxym Voice Server — Dokumentacja

## Szybki start

```bash
# 1. Uruchom serwer z obsługą głosową
cd /home/tom/github/wronai/proxy
./scripts/proxym-voice-server.sh

# 2. W nowym terminalu — uruchom voice chat
./scripts/proxym-voice-chat.py --tts
```

## Architektura

```
┌─────────────────────────────────────────────────────────────┐
│                    HOST (Linux)                              │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  proxym     │  │   Voice     │  │   TTS       │        │
│  │  serve      │  │   Listener  │  │   Engine    │        │
│  │  :4001      │  │   (Whisper) │  │   (espeak)  │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                │                │               │
│         └────────────────┴────────────────┘               │
│                    Voice Chat CLI                          │
└─────────────────────────────────────────────────────────────┘
```

## Instalacja zależności głosowych

```bash
cd /home/tom/github/wronai/proxy
.venv/bin/pip install faster-whisper sounddevice numpy
```

## Użycie

### Serwer web (dashboard + API)

```bash
# Standardowo
proxym serve --port 4001

# Z auto-reload (development)
proxym serve --reload --port 4001

# Skrypt helper
./scripts/proxym-voice-server.sh
```

### Voice Chat (CLI)

```bash
# Tylko STT (mów → tekst → odpowiedź tekstowa)
proxym chat --voice

# STT + TTS (pełna pętla głosowa)
proxym chat --voice --tts

# Skrypt helper
./scripts/proxym-voice-chat.py --tts
```

## Konfiguracja

### Język (`~/.config/proxym/.env`)

```bash
# Polski (domyślnie)
VOICE_LANGUAGE=pl

# Angielski
VOICE_LANGUAGE=en
```

### Model Whisper

| Model | Rozmiar | Jakość | CPU/GPU |
|-------|---------|--------|---------|
| tiny | 39 MB | podstawowa | CPU |
| small | 244 MB | **dobra** (domyślnie) | CPU |
| medium | 769 MB | bardzo dobra | GPU |
| large-v3 | 1550 MB | najlepsza | GPU |

Zmiana modelu (w kodzie `src/proxym/cli/voice.py:30`):
```python
VoiceListener(model_size="small", language="pl")
```

## Endpointy API

| Endpoint | Opis |
|----------|------|
| `GET /health` | Status serwera |
| `POST /v1/chat/completions` | OpenAI-compatible chat |
| `GET /dashboard` | Web dashboard |
| `GET /dashboard/vms` | Lista VMs |
| `POST /dashboard/vms/{id}/start` | Start VM |

## Rozwiązywanie problemów

### `No module named 'faster_whisper'`
```bash
.venv/bin/pip install faster-whisper sounddevice numpy
```

### `sounddevice.PortAudioError`
```bash
# Ubuntu/Debian
sudo apt-get install libportaudio2

# Fedora
sudo dnf install portaudio
```

### Brak dostępu do mikrofonu
```bash
# Sprawdź uprawnienia
arecord -l  # lista urządzeń audio

# Dodaj użytkownika do grupy audio
sudo usermod -aG audio $USER
# (wyloguj i zaloguj ponownie)
```

## Przykłady komend głosowych (polski)

Mówisz → System rozumie → Wykonuje

| Komenda głosowa | Akcja |
|-----------------|-------|
| "status" | Pokazuje status systemu |
| "lista maszyn" | Lista VMs |
| "uruchom maszynę test" | Start VM o nazwie "test" |
| "koszty" | Pokaż dzisiejsze koszty |
| "pomoc" | Lista dostępnych komend |

## Pliki

| Plik | Opis |
|------|------|
| `scripts/proxym-voice-server.sh` | Launcher serwera |
| `scripts/proxym-voice-chat.py` | Voice chat CLI |
| `src/proxym/cli/voice.py` | Klasa VoiceListener |
| `src/proxym/cli/chat.py` | Logika chatu |
