frankenbot/README.md

# Frankenbot - Multi-Agent Event-Management-System

Ein Flask-basiertes Multi-Agent-System zur Orchestrierung und Verwaltung von KI-Agenten für Event-Management. Entwickelt für den **Diversity-Ball Wien 2026**.

## 🎯 Überblick

Frankenbot ist ein intelligentes Event-Management-System, bei dem spezialisierte KI-Agents zusammenarbeiten, um komplexe Event-Organisationsaufgaben zu bewältigen. Ein zentraler Orchestrator koordiniert die Kommunikation zwischen den Agents und delegiert Tasks basierend auf Expertise.

## ✨ Haupt-Features

### 🤖 Multi-Agent Orchestrierung
- **Orchestrator als zentraler Hub**: Alle Agent-Kommunikation läuft über den Orchestrator
- **Spezialisierte Agents**: Budget Manager, Catering Manager, Location Manager, Program Manager, etc.
- **Agent-zu-Agent Kommunikation**: Agents können Fragen stellen, Subtasks erstellen und neue Agents vorschlagen
- **Dynamische Modellauswahl**: 29+ KI-Modelle verfügbar (OpenCode, Anthropic, Ollama)

### 📋 Task-Management
- **Persistente Speicherung**: SQLite-Datenbank für Tasks
- **Automatische Task-Verarbeitung**: TaskBeat verarbeitet Tasks alle 10 Sekunden
- **Auto-Cleanup**: Löscht completed Tasks automatisch nach 7 Tagen
- **Auto-Refresh UI**: Tasks-Seite aktualisiert sich automatisch alle 15 Sekunden
- **Task-Delegation**: Orchestrator analysiert Tasks und weist sie passenden Agents zu
- **Status-Tracking**: pending → in_progress → completed

### 💬 Chat-System
- **Live-Streaming**: Server-Sent Events für Echtzeit-Antworten
- **Agent-Auswahl**: Chat mit spezifischen Agents oder dem Orchestrator
- **Session-basierte History**: Kontext bleibt über Konversation erhalten

### 📧 Email-Integration
- **IMAP**: Email-Posteingang überwachen
- **SMTP**: Emails versenden
- **Email-to-Task**: Automatische Task-Erstellung aus Emails
- **Whitelist-System**: Nur autorisierte Absender (diversityball.at Domain)
- **Intelligente Vorstellung**: Neue Absender werden automatisch gebeten sich vorzustellen
- **Team-Member Lernsystem**: Orchestrator baut automatisch Wissensdatenbank auf

### 📁 Datei-Management
- **Agent Work-Folders**: Jeder Agent hat eigenes Arbeitsverzeichnis
- **Email-Vorlagen**: Wiederverwendbare Email-Templates
- **Projekt-Dateien**: Zentrale Dokumentenverwaltung
- **Upload & Download**: Web-basierter Datei-Manager

### 🧠 Memory-System
- **JSON-basierte Erinnerungen**: Strukturierte Agent-Memories
- **Kategorien**: tasks, notes, decisions, contacts
- **Agent-spezifisch**: Jeder Agent verwaltet eigene Erinnerungen
- **Memory-Summaries**: Kompakte Übersichten für Prompts

### 📚 Wissensdatenbank
- **On-Demand Zugriff**: Agents nutzen `@READ_KNOWLEDGE` statt volle KB im Prompt
- **Performance-Optimierung**: Reduziert Prompt-Größe um ~15KB
- **Event-spezifisch**: Diversity-Ball Wien 2026 Informationen
- **Self-Learning**: System lernt automatisch über Team-Members und Verantwortlichkeiten

### 👥 Team-Management
- **Team-Members Datenbank**: Reale Mitarbeiter mit Rollen und Verantwortlichkeiten
- **Automatisches Lernen**: Neue Absender werden erkannt und vorgestellt
- **Orchestrator Beat**: Prüft alle 30 Minuten Tasks und eskaliert bei Bedarf
- **Direkter Kontakt**: Orchestrator kann Team-Members per Email/Telegram kontaktieren
- **Intelligente Koordination**: Weiß wer wofür verantwortlich ist

### 💬 Telegram-Integration
- **Bidirektionale Kommunikation**: Nachrichten senden und empfangen
- **QR-Code Setup**: Einfache Bot-Verbindung über Settings-Seite
- **Task-Erstellung**: Telegram-Nachrichten werden automatisch zu Tasks
- **Antworten**: Agent-Responses werden zurück zu Telegram gesendet
- **User-Whitelist**: Nur autorisierte Telegram-User

## 🚀 Installation

### Voraussetzungen
```bash
# Python 3.10+
python --version

# OpenCode CLI (für Agent-Ausführung)
opencode --version
```

### Abhängigkeiten installieren
```bash
pip install flask python-dotenv
```

### Email-Konfiguration (Optional)
```bash
cp .env.example .env
# .env editieren und Email-Credentials eintragen
```

## 📖 Verwendung

### App starten
```bash
# Foreground
python app.py

# Background (empfohlen)
nohup python app.py > app_output.log 2>&1 &
```

Die Anwendung läuft dann auf: **http://localhost:5000**

### Agent-Kommandos

Agents können folgende Kommandos in ihren Antworten verwenden:

#### Frage an Orchestrator
```
@ASK_ORCHESTRATOR
Question: Wie hoch ist das verfügbare Budget für Catering?
Context: Ich plane das Menü und brauche Budget-Info
@END
```

#### Subtask erstellen
```
@CREATE_SUBTASK
Task: Location-Vertrag prüfen
Requirements: Rechtliche Prüfung der Mietbedingungen
@END
```

#### Wissensdatenbank durchsuchen
```
@READ_KNOWLEDGE
Topic: Budget
@END
```

#### Neuen Agent vorschlagen
```
@SUGGEST_AGENT
Role: Security Manager
Skills: Sicherheitsplanung, Crowd Management
Reason: Für große Events mit 500+ Gästen benötigt
@END
```

#### Team-Member kontaktieren
```
@SEND_EMAIL
To: georg.tschare@signtime.media
Subject: Budget-Freigabe benötigt
Body: Hallo Georg, für das Catering benötigen wir eine Budget-Freigabe...
@END
```

#### Team-Member aktualisieren
```
@UPDATE_TEAM_MEMBER
Identifier: p.dyderski@live.at
TelegramID: 123456789
Responsibilities: System-Administration, 3D-Visualisierung, AI-Agenten, R&D
@END
```

#### Neues Team-Mitglied hinzufügen
```
@ADD_TEAM_MEMBER
Name: Max Mustermann
Role: Marketing Coordinator
Responsibilities: Social Media, Content Creation
Email: max@diversityball.at
@END
```

## 🗂️ Projekt-Struktur

```
frankenbot/
├── app.py                          # Haupt-Flask-App (2900+ Zeilen)
├── agent_config.json               # Agent-Modell-Zuweisungen
├── diversityball_knowledge.md      # Event-Wissensdatenbank
├── email_journal.db                # SQLite-Datenbank (Emails, Tasks, Team-Members)
│
├── agents/                         # Agent-Verzeichnisse
│   ├── orchestrator/
│   │   ├── systemprompt.md
│   │   ├── personality.md
│   │   ├── work/                   # Arbeitsverzeichnis
│   │   └── memory/                 # JSON-Erinnerungen
│   ├── budget_manager/
│   ├── catering_manager/
│   ├── location_manager/
│   └── ...
│
├── templates/                      # HTML-Templates (Jinja2)
│   ├── base.html
│   ├── index.html                  # Dashboard
│   ├── chat.html                   # Agent-Chat
│   ├── orchestrator.html           # Orchestrator-Chat
│   ├── tasks.html                  # Task-Management
│   ├── agents.html                 # Agent-Verwaltung
│   ├── files.html                  # Datei-Manager
│   └── emails.html                 # Email-Interface
│
├── static/
│   └── style.css                   # CSS-Styling
│
└── uploads/                        # Hochgeladene Dateien
```

## 🤖 Verfügbare Agents

| Agent | Rolle | Verantwortlich für |
|-------|-------|-------------------|
| **Orchestrator** | Koordinator | Task-Delegation, Agent-Kommunikation |
| **Budget Manager** | Finanzplanung | Budget-Tracking, Kostenkalkulation |
| **Catering Manager** | Verpflegung | Menüplanung, Catering-Koordination |
| **Location Manager** | Veranstaltungsort | Raumbuchung, Logistik |
| **Program Manager** | Programmablauf | Zeitplanung, Ablaufkoordination |
| **Researcher** | Recherche | Web-Recherche, Informationsbeschaffung |
| **Document Editor** | Dokumentation | Dokument-Erstellung, Bearbeitung |
| **Tax Advisor** | Steuern | Steuerliche Beratung, AKM-Meldungen |
| **Musik Rechte Advisor** | Musikrechte | GEMA/AKM-Compliance |
| **Zusammenfasser** | Synthese | Informations-Aggregation |

## 🔧 Technologie-Stack

- **Backend**: Flask 3.x
- **Frontend**: Bootstrap 5, Vanilla JavaScript
- **Database**: SQLite (Email-Journal, Tasks, Team-Members)
- **AI**: OpenCode CLI (Multi-Provider Support: Anthropic, Ollama, etc.)
- **Templates**: Jinja2
- **Streaming**: Server-Sent Events (SSE)
- **Bot**: python-telegram-bot, QR-Code Generation

## 🎨 UI-Routen

| Route | Beschreibung |
|-------|--------------|
| `/` | Dashboard - Agent-Übersicht & letzte Tasks |
| `/chat` | Chat mit individuellen Agents |
| `/orchestrator` | Orchestrator-Chat mit Task-Verteilung |
| `/tasks` | Task-Management mit Auto-Refresh |
| `/agents` | Agent-Verwaltung (Erstellen, Bearbeiten, Modell-Auswahl) |
| `/files` | Datei-Manager (Upload, Download, Agent Work-Folders, View) |
| `/emails` | Email-Interface (Senden, Empfangen, Vorlagen) |
| `/settings` | System-Einstellungen, Telegram QR-Code, Poller-Konfiguration |

## ⚙️ Konfiguration

### Agent-Modelle anpassen
Bearbeite `agent_config.json`:
```json
{
  "orchestrator": "anthropic/claude-3.7-sonnet",
  "budget_manager": "opencode/qwen2.5-coder:32b",
  "catering_manager": "anthropic/claude-3.5-sonnet"
}
```

### Email-Setup
Bearbeite `.env`:
```bash
EMAIL_ADDRESS=your@email.com
EMAIL_PASSWORD=your_app_password
EMAIL_IMAP_SERVER=imap.gmail.com
EMAIL_SMTP_SERVER=smtp.gmail.com
```

### Telegram-Konfiguration
Bearbeite `.env`:
```bash
TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_ALLOWED_USERS=123456789,987654321
TELEGRAM_BOT_USERNAME=your_bot_name_bot
```

Setup-Anleitung:
1. Erstelle Bot via [@BotFather](https://t.me/BotFather)
2. Hole deine User-ID via [@userinfobot](https://t.me/userinfobot)
3. QR-Code scannen auf `/settings` Seite

### Background-Threads
- **EmailPoller**: Prüft alle 2 Minuten auf neue Emails
- **TaskBeat**: Verarbeitet Tasks alle 10 Sekunden
- **TaskWorker**: Führt Agent-Tasks aus (Timeout: 10 Min)
- **OrchestratorBeat**: Prüft alle 30 Minuten auf blockierte Tasks ⭐ NEU
- **TelegramBot**: Polling für Telegram-Nachrichten (wenn konfiguriert)

## 📊 Performance

### Optimierungen
- ✅ Wissensdatenbank nicht im Prompt (on-demand via `@READ_KNOWLEDGE`)
- ✅ Model-Cache (1h TTL)
- ✅ Agent arbeiten in eigenen work-Verzeichnissen
- ✅ Timeout: 600 Sekunden (10 Min) für komplexe Tasks
- ✅ Task-Cleanup: Auto-Löschung nach 7 Tagen
- ✅ Persistente Tasks in SQLite-Datenbank
- ✅ Self-Learning Team-Management

### Geschätzte Ausführungszeiten
- Einfache Tasks: 30-60 Sekunden
- Komplexe Tasks: 2-5 Minuten
- Research-Tasks: 3-8 Minuten

## 🔒 Security

### Implementierte Maßnahmen
- ✅ XSS-Schutz: HTML-Escaping in allen Templates (orchestrator.html, chat.html)
- ✅ Email-Whitelist: Nur autorisierte Absender (diversityball.at Domain)
- ✅ Telegram-Whitelist: Nur autorisierte User-IDs
- ✅ Exception-Handling: Spezifische Exception-Typen mit Logging
- ✅ Request-Validierung: `.get()` mit Defaults
- ✅ Path Traversal Protection: Agent-Files nur aus eigenem work-Verzeichnis
- ✅ Session-basierte Auth: Flask-Sessions

### Empfehlungen für Produktion
- 🔐 HTTPS aktivieren (TLS/SSL)
- 🔐 Secrets in Umgebungsvariablen (nicht in Code)
- 🔐 CSP Headers setzen
- 🔐 Rate Limiting für API-Endpoints
- 🔐 WSGI Server verwenden (Gunicorn, uWSGI)

## 🐛 Debugging

### Logs prüfen
```bash
# Echtzeit-Logs
tail -f app_output.log

# Letzte 50 Zeilen
tail -50 app_output.log

# Nach Errors suchen
grep -i error app_output.log
```

### App-Status
```bash
# Läuft die App?
ps aux | grep "python3 app.py"

# Port 5000 belegt?
lsof -i :5000
```

## 📝 Entwicklung

### Code-Quality
- ✅ 72 Funktionen, 29 Routes
- ✅ Keine unused imports
- ✅ Spezifisches Exception-Handling
- ✅ Logging für alle kritischen Operationen

### Git-Workflow
```bash
# Status prüfen
git status

# Änderungen committen
git add .
git commit -m "feat: neue Funktion"

# Pushen
git push origin main
```

## 📚 Weitere Dokumentation

- `CHANGES.md` - Detaillierte Feature-Implementierungen
- `FEATURES.md` - Feature-Übersicht
- `QUICKSTART.md` - Schnellstart-Anleitung
- `.env.example` - Email-Konfiguration

## 🎓 Use Cases

### Event-Planung
1. Orchestrator empfängt Planungs-Anfrage
2. Erstellt Subtasks für Budget, Location, Catering
3. Agents arbeiten parallel
4. Orchestrator aggregiert Ergebnisse

### Email-basierte Tasks
1. Email kommt an (von Whitelist-Absender)
2. EmailPoller erstellt Task
3. TaskBeat weist Task zu passendem Agent
4. Agent arbeitet Task ab und antwortet per Email

### Neuer Team-Member (Self-Learning)
1. Email von unbekanntem @diversityball.at Absender
2. System erkennt: "Nicht in Team-DB!"
3. Orchestrator übernimmt automatisch
4. Begrüßt und bittet um Vorstellung (Name, Rolle, Verantwortlichkeiten)
5. Beantwortet auch die eigentliche Anfrage
6. Nutzt @ADD_TEAM_MEMBER zum Speichern
7. Zukünftig: Bessere Koordination durch bekannte Verantwortlichkeiten

### Orchestrator Beat Monitoring
1. Alle 30 Minuten: System-Check
2. Findet Tasks ohne Fortschritt (>2h pending)
3. Findet blockierte Tasks (>4h in_progress)
4. Fragt Orchestrator was zu tun ist
5. Orchestrator entscheidet ob Eskalation nötig
6. Bei Bedarf: @SEND_EMAIL an verantwortliches Team-Mitglied

### Wissensdatenbank-Abfrage
1. Agent braucht Info (z.B. Budget)
2. Nutzt `@READ_KNOWLEDGE Topic: Budget`
3. System extrahiert relevante Sektion
4. Agent erhält nur benötigte Informationen

## 🤝 Mitwirken

Dieses Projekt wurde entwickelt für den **Diversity-Ball Wien 2026**. 

## 📄 Lizenz

Dieses Projekt ist für internen Gebrauch und Event-Management entwickelt.

---

**Version**: 2.0.0  
**Letztes Update**: 21. Februar 2026  
**Status**: Production-Ready ✅  
**Neue Features**: Self-Learning Team-Management, Orchestrator Beat, Task-Persistierung, Telegram-Integration