Benjamin_Boenisch/breakpilot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update MkDocs for 3-project architecture (core/lehrer/compliance)

Browse Source 
- Rewrite system-architecture.md with new 3-project diagram
- Update index.md with Core services table and nginx routing
- Replace service docs that moved to lehrer/compliance with redirects
  (klausur-service, voice-service, agent-core, ki-daten-pipeline -> lehrer)
  (ai-compliance-sdk -> compliance)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
2026-02-14 19:51:09 +01:00
parent f2a24d7341
commit fdfe38b61a
7 changed files with 260 additions and 1414 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
docs-src/services/agent-core/index.md
View File

@@ -1,420 +1,10 @@
# Breakpilot Agent Core
Multi-Agent Architecture Infrastructure fuer Breakpilot.
## Uebersicht
Das `agent-core` Modul stellt die gemeinsame Infrastruktur fuer Breakpilots Multi-Agent-System bereit:
- **Session Management**: Agent-Sessions mit Checkpoints und Recovery
- **Shared Brain**: Langzeit-Gedaechtnis und Kontext-Verwaltung
- **Orchestration**: Message Bus, Supervisor und Task-Routing
## Architektur
```
┌─────────────────────────────────────────────────────────────────┐
│ Breakpilot Services │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │Voice Service│ │Klausur Svc │ │ Admin-v2 / AlertAgent │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
│ │ │ │ │
│ └────────────────┼──────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────┐ │
│ │ Agent Core │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────────────┐ │ │
│ │ │ Sessions │ │Shared Brain │ │ Orchestrator │ │ │
│ │ │ - Manager │ │ - Memory │ │ - Message Bus │ │ │
│ │ │ - Heartbeat │ │ - Context │ │ - Supervisor │ │ │
│ │ │ - Checkpoint│ │ - Knowledge │ │ - Task Router │ │ │
│ │ └─────────────┘ └─────────────┘ └───────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────┐ │
│ │ Infrastructure │ │
│ │ Valkey (Redis) PostgreSQL Qdrant │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## Verzeichnisstruktur
```
agent-core/
├── __init__.py # Modul-Exports
├── README.md # Diese Datei
├── requirements.txt # Python-Abhaengigkeiten
├── pytest.ini # Test-Konfiguration
│
├── soul/ # Agent SOUL Files (Persoenlichkeiten)
│ ├── tutor-agent.soul.md
│ ├── grader-agent.soul.md
│ ├── quality-judge.soul.md
│ ├── alert-agent.soul.md
│ └── orchestrator.soul.md
│
├── brain/ # Shared Brain Implementation
│ ├── __init__.py
│ ├── memory_store.py # Langzeit-Gedaechtnis
│ ├── context_manager.py # Konversations-Kontext
│ └── knowledge_graph.py # Entity-Beziehungen
│
├── sessions/ # Session Management
│ ├── __init__.py
│ ├── session_manager.py # Session-Lifecycle
│ ├── heartbeat.py # Liveness-Monitoring
│ └── checkpoint.py # Recovery-Checkpoints
│
├── orchestrator/ # Multi-Agent Orchestration
│ ├── __init__.py
│ ├── message_bus.py # Inter-Agent Kommunikation
│ ├── supervisor.py # Agent-Ueberwachung
│ └── task_router.py # Intent-basiertes Routing
│
└── tests/ # Unit Tests
├── conftest.py
├── test_session_manager.py
├── test_heartbeat.py
├── test_message_bus.py
├── test_memory_store.py
└── test_task_router.py
```
## Komponenten
### 1. Session Management
Verwaltet Agent-Sessions mit State-Machine und Recovery-Faehigkeiten.
```python
from agent_core.sessions import SessionManager, AgentSession
# Session Manager erstellen
manager = SessionManager(
redis_client=redis,
db_pool=pg_pool,
namespace="breakpilot"
)
# Session erstellen
session = await manager.create_session(
agent_type="tutor-agent",
user_id="user-123",
context={"subject": "math"}
)
# Checkpoint setzen
session.checkpoint("task_started", {"task_id": "abc"})
# Session beenden
session.complete({"result": "success"})
```
**Session States:**
- `ACTIVE` - Session laeuft
- `PAUSED` - Session pausiert
- `COMPLETED` - Session erfolgreich beendet
- `FAILED` - Session fehlgeschlagen
### 2. Heartbeat Monitoring
Ueberwacht Agent-Liveness und triggert Recovery bei Timeout.
```python
from agent_core.sessions import HeartbeatMonitor, HeartbeatClient
# Monitor starten
monitor = HeartbeatMonitor(
timeout_seconds=30,
check_interval_seconds=5,
max_missed_beats=3
)
await monitor.start_monitoring()
# Agent registrieren
monitor.register("agent-1", "tutor-agent")
# Heartbeat senden
async with HeartbeatClient("agent-1", monitor) as client:
# Agent-Arbeit...
pass
```
### 3. Memory Store
Langzeit-Gedaechtnis fuer Agents mit TTL und Access-Tracking.
```python
from agent_core.brain import MemoryStore
store = MemoryStore(redis_client=redis, db_pool=pg_pool)
# Erinnerung speichern
await store.remember(
key="evaluation:math:student-1",
value={"score": 85, "feedback": "Gut gemacht!"},
agent_id="grader-agent",
ttl_days=30
)
# Erinnerung abrufen
result = await store.recall("evaluation:math:student-1")
# Nach Pattern suchen
similar = await store.search("evaluation:math:*")
```
### 4. Context Manager
Verwaltet Konversationskontext mit automatischer Komprimierung.
```python
from agent_core.brain import ContextManager, MessageRole
ctx_manager = ContextManager(redis_client=redis)
# Kontext erstellen
context = ctx_manager.create_context(
session_id="session-123",
system_prompt="Du bist ein hilfreicher Tutor...",
max_messages=50
)
# Nachrichten hinzufuegen
context.add_message(MessageRole.USER, "Was ist Photosynthese?")
context.add_message(MessageRole.ASSISTANT, "Photosynthese ist...")
# Fuer LLM API formatieren
messages = context.get_messages_for_llm()
```
### 5. Message Bus
Inter-Agent Kommunikation via Redis Pub/Sub.
```python
from agent_core.orchestrator import MessageBus, AgentMessage, MessagePriority
bus = MessageBus(redis_client=redis)
await bus.start()
# Handler registrieren
async def handle_message(msg):
return {"status": "processed"}
await bus.subscribe("grader-agent", handle_message)
# Nachricht senden
await bus.publish(AgentMessage(
sender="orchestrator",
receiver="grader-agent",
message_type="grade_request",
payload={"exam_id": "exam-1"},
priority=MessagePriority.HIGH
))
# Request-Response Pattern
response = await bus.request(message, timeout=30.0)
```
### 6. Agent Supervisor
Ueberwacht und koordiniert alle Agents.
```python
from agent_core.orchestrator import AgentSupervisor, RestartPolicy
supervisor = AgentSupervisor(message_bus=bus, heartbeat_monitor=monitor)
# Agent registrieren
await supervisor.register_agent(
agent_id="tutor-1",
agent_type="tutor-agent",
restart_policy=RestartPolicy.ON_FAILURE,
max_restarts=3,
capacity=10
)
# Agent starten
await supervisor.start_agent("tutor-1")
# Load Balancing
available = supervisor.get_available_agent("tutor-agent")
```
### 7. Task Router
Intent-basiertes Routing mit Fallback-Ketten.
```python
from agent_core.orchestrator import TaskRouter, RoutingRule, RoutingStrategy
router = TaskRouter(supervisor=supervisor)
# Eigene Regel hinzufuegen
router.add_rule(RoutingRule(
intent_pattern="learning_*",
agent_type="tutor-agent",
priority=10,
fallback_agent="orchestrator"
))
# Task routen
result = await router.route(
intent="learning_math",
context={"grade": 10},
strategy=RoutingStrategy.LEAST_LOADED
)
if result.success:
print(f"Routed to {result.agent_id}")
```
## SOUL Files
SOUL-Dateien definieren die Persoenlichkeit und Verhaltensregeln jedes Agents.
| Agent | SOUL File | Verantwortlichkeit |
|-------|-----------|-------------------|
| TutorAgent | tutor-agent.soul.md | Lernbegleitung, Fragen beantworten |
| GraderAgent | grader-agent.soul.md | Klausur-Korrektur, Bewertung |
| QualityJudge | quality-judge.soul.md | BQAS Qualitaetspruefung |
| AlertAgent | alert-agent.soul.md | Monitoring, Benachrichtigungen |
| Orchestrator | orchestrator.soul.md | Task-Koordination |
## Datenbank-Schema
### agent_sessions
```sql
CREATE TABLE agent_sessions (
id UUID PRIMARY KEY,
agent_type VARCHAR(50) NOT NULL,
user_id UUID REFERENCES users(id),
state VARCHAR(20) NOT NULL DEFAULT 'active',
context JSONB DEFAULT '{}',
checkpoints JSONB DEFAULT '[]',
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
last_heartbeat TIMESTAMPTZ DEFAULT NOW()
);
```
### agent_memory
```sql
CREATE TABLE agent_memory (
id UUID PRIMARY KEY,
namespace VARCHAR(100) NOT NULL,
key VARCHAR(500) NOT NULL,
value JSONB NOT NULL,
agent_id VARCHAR(50) NOT NULL,
access_count INTEGER DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW(),
expires_at TIMESTAMPTZ,
UNIQUE(namespace, key)
);
```
### agent_messages
```sql
CREATE TABLE agent_messages (
id UUID PRIMARY KEY,
sender VARCHAR(50) NOT NULL,
receiver VARCHAR(50) NOT NULL,
message_type VARCHAR(50) NOT NULL,
payload JSONB NOT NULL,
priority INTEGER DEFAULT 1,
correlation_id UUID,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
## Integration
### Mit Voice-Service
```python
from services.enhanced_task_orchestrator import EnhancedTaskOrchestrator
orchestrator = EnhancedTaskOrchestrator(
redis_client=redis,
db_pool=pg_pool
)
await orchestrator.start()
# Session fuer Voice-Interaktion
session = await orchestrator.create_session(
voice_session_id="voice-123",
user_id="teacher-1"
)
# Task verarbeiten (nutzt Multi-Agent wenn noetig)
await orchestrator.process_task(task)
```
### Mit BQAS
```python
from bqas.quality_judge_agent import QualityJudgeAgent
judge = QualityJudgeAgent(
message_bus=bus,
memory_store=memory
)
await judge.start()
# Direkte Evaluation
result = await judge.evaluate(
response="Der Satz des Pythagoras...",
task_type="learning_math",
context={"user_input": "Was ist Pythagoras?"}
)
if result["verdict"] == "production_ready":
# Response ist OK
pass
```
## Tests
```bash
# In agent-core Verzeichnis
cd agent-core
# Alle Tests ausfuehren
pytest -v
# Mit Coverage
pytest --cov=. --cov-report=html
# Einzelnes Test-Modul
pytest tests/test_session_manager.py -v
# Async-Tests
pytest tests/test_message_bus.py -v
```
## Metriken
Das Agent-Core exportiert folgende Metriken:
| Metrik | Beschreibung |
|--------|--------------|
| `agent_session_duration_seconds` | Dauer von Agent-Sessions |
| `agent_heartbeat_delay_seconds` | Zeit seit letztem Heartbeat |
| `agent_message_latency_ms` | Latenz der Inter-Agent Kommunikation |
| `agent_memory_access_total` | Memory-Zugriffe pro Agent |
| `agent_error_total` | Fehler pro Agent-Typ |
## Naechste Schritte
1. **Migration ausfuehren**: `psql -f backend/migrations/add_agent_core_tables.sql`
2. **Voice-Service erweitern**: Enhanced Orchestrator aktivieren
3. **BQAS integrieren**: Quality Judge Agent starten
4. **Monitoring aufsetzen**: Metriken in Grafana integrieren
# Agent Core
!!! info "Verschoben nach breakpilot-lehrer"
Agent Core gehoert zum **breakpilot-lehrer** Projekt (Team A).
Die aktuelle Dokumentation befindet sich in der [Lehrer MkDocs-Instanz](http://macmini:8010/services/agent-core/).
**Container:** `bp-lehrer-agent-core`
**Profil:** `dev`
**Repo:** `breakpilot-lehrer/agent-core/`

103
docs-src/services/ai-compliance-sdk/index.md
View File

@@ -1,97 +1,10 @@
# AI Compliance SDK
Das AI Compliance SDK ist ein Go-basierter Service zur Compliance-Bewertung von KI-Anwendungsfällen.
## Übersicht
| Eigenschaft | Wert |
|-------------|------|
| **Port** | 8090 |
| **Framework** | Go (Gin) |
| **Datenbank** | PostgreSQL |
| **Vector DB** | Qdrant (Legal RAG) |
## Kernkomponenten
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ UCCA System │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Frontend │───>│ SDK API │───>│ PostgreSQL │ │
│ │ (Next.js) │ │ (Go) │ │ Database │ │
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Policy │ │ Escalation │ │ Legal RAG │ │
│ │ Engine │ │ Workflow │ │ (Qdrant) │ │
│ │ (45 Regeln) │ │ (E0-E3) │ │ 2,274 Chunks │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## Features
- **UCCA (Use-Case Compliance Advisor)**: Deterministische Bewertung von KI-Anwendungsfällen
- **Policy Engine**: 45 regelbasierte Compliance-Prüfungen
- **License Policy Engine**: Standards/Normen-Compliance (DIN, ISO, VDI)
- **Legal RAG**: Semantische Suche in EU-Verordnungen (DSGVO, AI Act, NIS2)
- **Eskalations-Workflow**: E0-E3 Stufen mit Human-in-the-Loop
- **Wizard & Legal Assistant**: Geführte Eingabe mit Rechtsassistent
- **Generic Obligations Framework**: NIS2, DSGVO, AI Act Module
## Kernprinzip
> **"LLM ist NICHT die Quelle der Wahrheit. Wahrheit = Regeln + Evidenz. LLM = Übersetzer + Subsumptionshelfer"**
Das System folgt einem strikten **Human-in-the-Loop** Ansatz:
1. **Deterministische Regeln** treffen alle Compliance-Entscheidungen
2. **LLM** erklärt nur Ergebnisse, überschreibt nie BLOCK-Entscheidungen
3. **Menschen** (DSB, Legal) treffen finale Entscheidungen bei kritischen Fällen
## API-Endpunkte
### Assessment
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
| GET | `/sdk/v1/ucca/assessments` | Assessments auflisten |
| GET | `/sdk/v1/ucca/assessments/:id` | Assessment abrufen |
| POST | `/sdk/v1/ucca/assessments/:id/explain` | LLM-Erklärung generieren |
### Eskalation
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/escalations` | Eskalationen auflisten |
| POST | `/sdk/v1/ucca/escalations/:id/decide` | Entscheidung treffen |
### Obligations Framework
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/obligations/assess` | Pflichten-Assessment |
| POST | `/sdk/v1/ucca/obligations/export/memo` | PDF-Export |
## Weiterführende Dokumentation
- [Architektur](./ARCHITECTURE.md) - Detaillierte Systemarchitektur
- [Entwickler-Guide](./DEVELOPER.md) - Entwickler-Dokumentation
- [Auditor-Dokumentation](./AUDITOR_DOCUMENTATION.md) - Dokumentation für externe Auditoren
## Tests
```bash
cd ai-compliance-sdk
go test -v ./...
# Mit Coverage
go test -cover ./...
```
!!! info "Verschoben nach breakpilot-compliance"
Das AI Compliance SDK gehoert zum **breakpilot-compliance** Projekt (Team B).
Die aktuelle Dokumentation befindet sich in der [Compliance MkDocs-Instanz](http://macmini:8011/services/ai-compliance-sdk/).
**Container:** `bp-compliance-ai-sdk`
**Ports:** 8090 (intern), 8093 (via Nginx)
**Repo:** `breakpilot-compliance/ai-compliance-sdk/`

219
docs-src/services/ki-daten-pipeline/index.md
View File

@@ -1,215 +1,8 @@
# KI-Daten-Pipeline
Die KI-Daten-Pipeline ist ein zusammenhaengendes System aus drei Modulen, das den Datenfluss von der Erfassung bis zur semantischen Suche abbildet.
## Uebersicht
```mermaid
flowchart LR
subgraph OCR["OCR-Labeling"]
A[Klausur-Scans] --> B[OCR Erkennung]
B --> C[Ground Truth Labels]
end
subgraph RAG["RAG Pipeline"]
D[PDF Dokumente] --> E[Text-Extraktion]
E --> F[Chunking]
F --> G[Embedding]
end
subgraph SEARCH["Daten & RAG"]
H[Qdrant Collections]
I[Semantische Suche]
end
C -->|Export| D
G -->|Indexierung| H
H --> I
I -->|Ergebnisse| J[Klausur-Korrektur]
```
## Module
| Modul | Pfad | Funktion | Backend |
|-------|------|----------|---------|
| **OCR-Labeling** | `/ai/ocr-labeling` | Ground Truth fuer Handschrift-OCR | klausur-service:8086 |
| **RAG Pipeline** | `/ai/rag-pipeline` | Dokument-Indexierung | klausur-service:8086 |
| **Daten & RAG** | `/ai/rag` | Vektor-Suche & Collection-Mapping | klausur-service:8086 |
## Datenfluss
### 1. OCR-Labeling (Eingabe)
Das OCR-Labeling-Modul erfasst Ground Truth Daten fuer das Training von Handschrift-Erkennungsmodellen:
- **Upload**: Klausur-Scans (PDF/Bilder) werden hochgeladen
- **OCR-Verarbeitung**: Mehrere OCR-Modelle erkennen den Text
- `llama3.2-vision:11b` - Vision LLM (beste Qualitaet)
- `trocr` - Microsoft Transformer (schnell)
- `paddleocr` - PaddleOCR + LLM (4x schneller)
- `donut` - Document Understanding (strukturiert)
- **Labeling**: Manuelles Pruefen und Korrigieren der OCR-Ergebnisse
- **Export**: Gelabelte Daten koennen exportiert werden fuer:
- TrOCR Fine-Tuning
- Llama Vision Fine-Tuning
- Generic JSON
### 2. RAG Pipeline (Verarbeitung)
Die RAG Pipeline verarbeitet Dokumente und macht sie suchbar:
```mermaid
flowchart TD
A[Datenquellen] --> B[OCR/Text-Extraktion]
B --> C[Chunking]
C --> D[Embedding]
D --> E[Qdrant Indexierung]
subgraph sources["Datenquellen"]
S1[NiBiS PDFs]
S2[Eigene EH]
S3[Rechtskorpus]
S4[Schulordnungen]
end
```
**Verarbeitungsschritte:**
1. **Dokumentenextraktion**: PDFs und Bilder werden per OCR in Text umgewandelt
2. **Chunking**: Lange Texte werden in Abschnitte aufgeteilt
- Chunk-Groesse: 1000 Zeichen
- Ueberlappung: 200 Zeichen
3. **Embedding**: Jeder Chunk wird in einen Vektor umgewandelt
- Modell: `text-embedding-3-small`
- Dimensionen: 1536
4. **Indexierung**: Vektoren werden in Qdrant gespeichert
### 3. Daten & RAG (Ausgabe)
Das Daten & RAG Modul ermoeglicht die Verwaltung und Suche:
- **Collection-Uebersicht**: Status aller Qdrant Collections
- **Semantische Suche**: Fragen werden in Vektoren umgewandelt und aehnliche Dokumente gefunden
- **Regulierungs-Mapping**: Zeigt welche Regulierungen indexiert sind
## Qdrant Collections
| Collection | Inhalt | Status |
|------------|--------|--------|
| `bp_nibis_eh` | Offizielle NiBiS Erwartungshorizonte | Aktiv |
| `bp_eh` | Benutzerdefinierte Erwartungshorizonte | Aktiv |
| `bp_schulordnungen` | Schulordnungen aller Bundeslaender | In Arbeit |
| `bp_legal_corpus` | Rechtskorpus (DSGVO, AI Act, BSI, etc.) | Aktiv |
## Technische Architektur
### Services
```mermaid
graph TB
subgraph Frontend["Admin-v2 (Next.js)"]
F1["/ai/ocr-labeling"]
F2["/ai/rag-pipeline"]
F3["/ai/rag"]
end
subgraph Backend["klausur-service (Python)"]
B1[OCR Endpoints]
B2[Indexierungs-Jobs]
B3[Such-API]
end
subgraph Storage["Datenbanken"]
D1[(PostgreSQL)]
D2[(Qdrant)]
D3[(MinIO)]
end
F1 --> B1
F2 --> B2
F3 --> B3
B1 --> D1
B1 --> D3
B2 --> D2
B3 --> D2
```
### Backend-Endpunkte
#### OCR-Labeling (`/api/v1/ocr-label/`)
| Endpoint | Methode | Beschreibung |
|----------|---------|--------------|
| `/sessions` | GET/POST | Session-Verwaltung |
| `/sessions/{id}/upload` | POST | Bilder hochladen |
| `/queue` | GET | Labeling-Queue |
| `/confirm` | POST | OCR bestaetigen |
| `/correct` | POST | OCR korrigieren |
| `/skip` | POST | Item ueberspringen |
| `/stats` | GET | Statistiken |
| `/export` | POST | Trainingsdaten exportieren |
#### RAG Pipeline (`/api/ai/rag-pipeline`)
| Action | Beschreibung |
|--------|--------------|
| `jobs` | Indexierungs-Jobs auflisten |
| `dataset-stats` | Datensatz-Statistiken |
| `create-job` | Neue Indexierung starten |
| `pause` | Job pausieren |
| `resume` | Job fortsetzen |
| `cancel` | Job abbrechen |
#### Legal Corpus (`/api/legal-corpus/`)
| Endpoint | Beschreibung |
|----------|--------------|
| `/status` | Collection-Status |
| `/search` | Semantische Suche |
| `/ingest` | Dokumente indexieren |
## Integration mit Klausur-Korrektur
Die KI-Daten-Pipeline liefert Erwartungshorizont-Vorschlaege fuer die Klausur-Korrektur:
```mermaid
sequenceDiagram
participant L as Lehrer
participant K as Klausur-Korrektur
participant R as RAG-Suche
participant Q as Qdrant
L->>K: Schueler-Antwort pruefen
K->>R: EH-Vorschlaege laden
R->>Q: Semantische Suche
Q->>R: Top-k Chunks
R->>K: Relevante EH-Passagen
K->>L: Bewertungsvorschlaege
```
## Deployment
Die Module werden als Teil des admin-v2 Containers deployed:
```bash
# 1. Sync
rsync -avz --delete --exclude 'node_modules' --exclude '.next' --exclude '.git' \
/Users/benjaminadmin/Projekte/breakpilot-pwa/admin-v2/ \
macmini:/Users/benjaminadmin/Projekte/breakpilot-pwa/admin-v2/
# 2. Build & Deploy
ssh macmini "/usr/local/bin/docker compose \
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
build --no-cache admin-v2 && \
/usr/local/bin/docker compose \
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
up -d admin-v2"
```
## Verwandte Dokumentation
- [OCR Labeling Spezifikation](../klausur-service/OCR-Labeling-Spec.md)
- [RAG Admin Spezifikation](../klausur-service/RAG-Admin-Spec.md)
- [NiBiS Ingestion Pipeline](../klausur-service/NiBiS-Ingestion-Pipeline.md)
- [Multi-Agent Architektur](../../architecture/multi-agent.md)
!!! info "Verschoben nach breakpilot-lehrer"
Die KI-Daten-Pipeline gehoert zum **breakpilot-lehrer** Projekt (Team A).
Die aktuelle Dokumentation befindet sich in der [Lehrer MkDocs-Instanz](http://macmini:8010/services/ki-daten-pipeline/).
**Repo:** `breakpilot-lehrer/`

181
docs-src/services/klausur-service/index.md
View File

@@ -1,173 +1,10 @@
# Klausur-Service
# Klausur Service
Der Klausur-Service ist ein FastAPI-basierter Microservice fuer KI-gestuetzte Abitur-Klausurkorrektur.
## Uebersicht
| Eigenschaft | Wert |
|-------------|------|
| **Port** | 8086 |
| **Framework** | FastAPI (Python) |
| **Datenbank** | PostgreSQL + Qdrant (Vektor-DB) |
| **Speicher** | MinIO (Datei-Storage) |
## Features
- **OCR-Erkennung**: Automatische Texterkennung aus gescannten Klausuren
- **KI-Bewertung**: Automatische Bewertungsvorschlaege basierend auf Erwartungshorizont
- **BYOEH**: Bring-Your-Own-Expectation-Horizon mit Client-seitiger Verschluesselung
- **Fairness-Analyse**: Statistische Analyse der Bewertungskonsistenz
- **PDF-Export**: Gutachten und Notenuebersichten als PDF
- **Zweitkorrektur**: Vollstaendiger Workflow fuer Erst-, Zweit- und Drittkorrektur
## Architektur
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend (Next.js) │
│ /website/app/admin/klausur-korrektur/ │
│ - Klausur-Liste │
│ - Studenten-Liste │
│ - Korrektur-Workspace (2/3-1/3 Layout) │
│ - Fairness-Dashboard │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ klausur-service (FastAPI) │
│ Port 8086 - /klausur-service/backend/main.py │
│ - Klausur CRUD (/api/v1/klausuren) │
│ - Student Work (/api/v1/students) │
│ - Annotations (/api/v1/annotations) │
│ - BYOEH (/api/v1/eh) │
│ - PDF Export │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Infrastruktur │
│ - Qdrant (Vektor-DB fuer RAG) │
│ - MinIO (Datei-Storage) │
│ - PostgreSQL (Metadaten) │
│ - Embedding-Service (Port 8087) │
└─────────────────────────────────────────────────────────────┘
```
## API Endpoints
### Klausur-Verwaltung
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/klausuren` | Liste aller Klausuren |
| POST | `/api/v1/klausuren` | Neue Klausur erstellen |
| GET | `/api/v1/klausuren/{id}` | Klausur-Details |
| DELETE | `/api/v1/klausuren/{id}` | Klausur loeschen |
### Studenten-Arbeiten
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/klausuren/{id}/students` | Arbeit hochladen |
| GET | `/api/v1/klausuren/{id}/students` | Studenten-Liste |
| GET | `/api/v1/students/{id}` | Einzelne Arbeit |
| PUT | `/api/v1/students/{id}/criteria` | Kriterien bewerten |
| PUT | `/api/v1/students/{id}/gutachten` | Gutachten speichern |
### KI-Funktionen
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/students/{id}/gutachten/generate` | Gutachten generieren |
| GET | `/api/v1/klausuren/{id}/fairness` | Fairness-Analyse |
| POST | `/api/v1/students/{id}/eh-suggestions` | EH-Vorschlaege via RAG |
### PDF-Export
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/students/{id}/export/gutachten` | Einzelgutachten PDF |
| GET | `/api/v1/students/{id}/export/annotations` | Anmerkungen PDF |
| GET | `/api/v1/klausuren/{id}/export/overview` | Notenuebersicht PDF |
| GET | `/api/v1/klausuren/{id}/export/all-gutachten` | Alle Gutachten PDF |
## Notensystem
Das System verwendet das deutsche 15-Punkte-System fuer Abiturklausuren:
| Punkte | Prozent | Note |
|--------|---------|------|
| 15 | >= 95% | 1+ |
| 14 | >= 90% | 1 |
| 13 | >= 85% | 1- |
| 12 | >= 80% | 2+ |
| 11 | >= 75% | 2 |
| 10 | >= 70% | 2- |
| 9 | >= 65% | 3+ |
| 8 | >= 60% | 3 |
| 7 | >= 55% | 3- |
| 6 | >= 50% | 4+ |
| 5 | >= 45% | 4 |
| 4 | >= 40% | 4- |
| 3 | >= 33% | 5+ |
| 2 | >= 27% | 5 |
| 1 | >= 20% | 5- |
| 0 | < 20% | 6 |
## Bewertungskriterien
| Kriterium | Gewicht | Beschreibung |
|-----------|---------|--------------|
| Rechtschreibung | 15% | Orthografie |
| Grammatik | 15% | Grammatik & Syntax |
| Inhalt | 40% | Inhaltliche Qualitaet |
| Struktur | 15% | Aufbau & Gliederung |
| Stil | 15% | Ausdruck & Stil |
## Verzeichnisstruktur
```
klausur-service/
├── backend/
│ ├── main.py # API Endpoints + Datenmodelle
│ ├── qdrant_service.py # Vektor-Datenbank Operationen
│ ├── eh_pipeline.py # BYOEH Verarbeitung
│ ├── hybrid_search.py # Hybrid Search (BM25 + Semantic)
│ └── requirements.txt # Python Dependencies
├── frontend/
│ └── src/
│ ├── components/ # React Komponenten
│ ├── pages/ # Seiten
│ └── services/ # API Client
└── docs/
├── BYOEH-Architecture.md
└── BYOEH-Developer-Guide.md
```
## Konfiguration
### Umgebungsvariablen
```env
# Klausur-Service
KLAUSUR_SERVICE_PORT=8086
QDRANT_URL=http://qdrant:6333
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=...
MINIO_SECRET_KEY=...
# Embedding-Service
EMBEDDING_SERVICE_URL=http://embedding:8087
OPENAI_API_KEY=sk-...
# BYOEH
BYOEH_ENCRYPTION_ENABLED=true
EH_UPLOAD_DIR=/app/eh-uploads
```
## Weiterführende Dokumentation
- [BYOEH Architektur](./BYOEH-Architecture.md) - Client-seitige Verschluesselung
- [OCR Compare](./OCR-Compare.md) - Block Review Feature fuer OCR-Vergleich
- [Zeugnis-System](../../architecture/zeugnis-system.md) - Zeugniserstellung
- [Backend API](../../api/backend-api.md) - Allgemeine API-Dokumentation
!!! info "Verschoben nach breakpilot-lehrer"
Der Klausur Service gehoert zum **breakpilot-lehrer** Projekt (Team A).
Die aktuelle Dokumentation befindet sich in der [Lehrer MkDocs-Instanz](http://macmini:8010/services/klausur-service/).
**Container:** `bp-lehrer-klausur-service`
**Port:** 8086
**Repo:** `breakpilot-lehrer/klausur-service/`

166
docs-src/services/voice-service/index.md
View File

@@ -1,160 +1,10 @@
# 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)
!!! info "Verschoben nach breakpilot-lehrer"
Der Voice Service gehoert zum **breakpilot-lehrer** Projekt (Team A).
Die aktuelle Dokumentation befindet sich in der [Lehrer MkDocs-Instanz](http://macmini:8010/services/voice-service/).
**Container:** `bp-lehrer-voice-service`
**Port:** 8091
**Repo:** `breakpilot-lehrer/voice-service/`