breakpilot-pwa/agent-core/README.md

# Breakpilot Agent Core

Multi-Agent Architecture Infrastructure für Breakpilot.

## Übersicht

Das `agent-core` Modul stellt die gemeinsame Infrastruktur für Breakpilots Multi-Agent-System bereit:

- **Session Management**: Agent-Sessions mit Checkpoints und Recovery
- **Shared Brain**: Langzeit-Gedächtnis 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-Abhängigkeiten
├── pytest.ini               # Test-Konfiguration
│
├── soul/                    # Agent SOUL Files (Persönlichkeiten)
│   ├── 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-Gedächtnis
│   ├── 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-Überwachung
│   └── 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-Fähigkeiten.

```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 läuft
- `PAUSED` - Session pausiert
- `COMPLETED` - Session erfolgreich beendet
- `FAILED` - Session fehlgeschlagen

### 2. Heartbeat Monitoring

Überwacht 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-Gedächtnis für 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 hinzufügen
context.add_message(MessageRole.USER, "Was ist Photosynthese?")
context.add_message(MessageRole.ASSISTANT, "Photosynthese ist...")

# Für 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

Überwacht 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 hinzufügen
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 Persönlichkeit 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 Qualitätsprüfung |
| 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 für Voice-Interaktion
session = await orchestrator.create_session(
    voice_session_id="voice-123",
    user_id="teacher-1"
)

# Task verarbeiten (nutzt Multi-Agent wenn nötig)
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 ausführen
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 |

## Nächste Schritte

1. **Migration ausführen**: `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