# Voice Service

Der Voice Service ist eine Voice-First Interface für die Breakpilot-Plattform mit DSGVO-konformem Design.

## Übersicht

| Eigenschaft | Wert |
|-------------|------|
| **Port** | 8082 |
| **Framework** | FastAPI (Python) |
| **Streaming** | WebSocket |
| **DSGVO** | Privacy-by-Design |

## Architektur

```
┌─────────────────────────────────────────────────────────────────┐
│                    Voice Service (Port 8082)                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│   │   Sessions   │───>│    Task      │───>│    BQAS      │      │
│   │   API        │    │ Orchestrator │    │  (Quality)   │      │
│   └──────────────┘    └──────────────┘    └──────────────┘      │
│                              │                                    │
│         ┌────────────────────┼────────────────────┐              │
│         │                    │                    │              │
│         ▼                    ▼                    ▼              │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│   │  WebSocket   │    │  Encryption  │    │   Logging    │      │
│   │  Streaming   │    │  Service     │    │  (structlog) │      │
│   └──────────────┘    └──────────────┘    └──────────────┘      │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘
```

## Kernkomponenten

### PersonaPlex + TaskOrchestrator

- Voice-first Interface für Breakpilot
- Real-time Voice Processing
- Multi-Agent Integration

### DSGVO-Compliance (Privacy-by-Design)

| Feature | Beschreibung |
|---------|--------------|
| **Keine Audio-Persistenz** | Nur RAM-basiert, keine dauerhafte Speicherung |
| **Namespace-Verschlüsselung** | Schlüssel nur auf Lehrer-Gerät |
| **TTL-basierte Löschung** | Automatische Datenlöschung nach Zeitablauf |
| **Transcript-Verschlüsselung** | Verschlüsselte Transkripte |

## API-Endpunkte

### Sessions

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/sessions` | Session erstellen |
| GET | `/api/v1/sessions/:id` | Session abrufen |
| DELETE | `/api/v1/sessions/:id` | Session beenden |

### Task Orchestration

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/tasks` | Task erstellen |
| GET | `/api/v1/tasks/:id` | Task-Status abrufen |

### BQAS (Quality Assessment)

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/bqas/evaluate` | Qualitätsbewertung |
| GET | `/api/v1/bqas/metrics` | Metriken abrufen |

### WebSocket

| Endpoint | Beschreibung |
|----------|--------------|
| `/ws/voice` | Real-time Voice Streaming |

### Health

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/health` | Health Check |
| GET | `/ready` | Readiness Check |

## Verzeichnisstruktur

```
voice-service/
├── main.py                    # FastAPI Application
├── config.py                  # Konfiguration
├── pyproject.toml             # Projekt-Metadaten
├── requirements.txt           # Dependencies
├── api/
│   ├── sessions.py            # Session-Management
│   ├── streaming.py           # WebSocket Voice Streaming
│   ├── tasks.py               # Task Orchestration
│   └── bqas.py                # Quality Assessment
├── services/
│   ├── task_orchestrator.py   # Task-Routing
│   └── encryption.py          # Verschlüsselung
├── bqas/
│   ├── judge.py               # LLM Judge
│   └── quality_judge_agent.py # Agent-Integration
├── models/                    # Datenmodelle
├── scripts/                   # Utility-Scripts
└── tests/                     # Test-Suite
```

## Konfiguration

```env
# .env
VOICE_SERVICE_PORT=8082
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql://...
ENCRYPTION_KEY=...
TTL_MINUTES=60
```

## Entwicklung

```bash
# Dependencies installieren
cd voice-service
pip install -r requirements.txt

# Server starten
uvicorn main:app --reload --port 8082

# Tests ausführen
pytest -v
```

## Docker

Der Service läuft als Teil von docker-compose.yml:

```yaml
voice-service:
  build:
    context: ./voice-service
  ports:
    - "8082:8082"
  environment:
    - REDIS_URL=redis://valkey:6379
  depends_on:
    - valkey
    - postgres
```

## Weiterführende Dokumentation

- [Multi-Agent Architektur](../../architecture/multi-agent.md)
- [BQAS Quality System](../../architecture/bqas.md)