e22019b2d5
- CLAUDE.md: Comprehensive documentation for Lehrer KI platform - docs-src: Klausur, Voice, Agent-Core, KI-Pipeline docs - mkdocs.yml: Lehrer-specific nav with blue theme - docker-compose: Added docs service (port 8010, profile: docs) - .claude/rules: testing, docs, open-source, abiturkorrektur, vocab-worksheet, multi-agent, experimental-dashboard Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
161 lines
5.6 KiB
Markdown
161 lines
5.6 KiB
Markdown
# 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)
|