docs: Umfassendes README-Update mit allen Features

- Multi-Agent Orchestrierung System beschrieben - Alle Features dokumentiert (Chat, Tasks, Email, Memory, etc.) - Agent-Kommandos (@ASK_ORCHESTRATOR, @CREATE_SUBTASK, etc.) - Projekt-Struktur und Technologie-Stack - Installation, Konfiguration, Debugging - Security-Maßnahmen und Performance-Optimierungen - Use Cases und Entwickler-Dokumentation
2026-02-21 12:38:34 +01:00 · 2026-02-21 12:38:34 +01:00 · 4c123d5f0f
commit 4c123d5f0f
parent ca820d20db
1 changed files with 311 additions and 38 deletions
--- a/README.md
+++ b/README.md
@ -1,59 +1,332 @@
-# Agenten Orchestrierung - Flask Webanwendung
+# Frankenbot - Multi-Agent Event-Management-System

-Eine Flask-basierte Webanwendung zur Verwaltung und Orchestrierung von Agenten.
+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**.

-## Features
+## 🎯 Überblick

- **Dashboard**: Übersicht aller verfügbaren Agenten und letzte Tasks
- **Chat**: Interaktive Kommunikation mit ausgewählten Agenten
- **Tasks**: Task-Verwaltung mit Status-Verfolgung (pending/in_progress/completed)
- **Dateien**: Datei-Upload und Verwaltung
+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.

-## Installation
+## ✨ Haupt-Features

-1. Installieren Sie die erforderlichen Abhängigkeiten:
+### 🤖 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
+- **Automatische Task-Verarbeitung**: TaskBeat verarbeitet Tasks alle 10 Sekunden
+- **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
+
+### 📁 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
+
+## 🚀 Installation
+
+### Voraussetzungen
 ```bash
-pip install flask
+# Python 3.10+
+python --version
+
+# OpenCode CLI (für Agent-Ausführung)
+opencode --version
 ```

-## Starten der Anwendung
-
+### 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 ist dann unter http://localhost:5000 erreichbar.
+Die Anwendung läuft dann auf: **http://localhost:5000**

-## Verfügbare Agenten
+### Agent-Kommandos

-| Agent | Beschreibung |
-|-------|---------------|
-| Researcher | Recherchiert Informationen im Web |
-| Location Manager | Verwaltet Veranstaltungsorte |
-| Catering Manager | Organisiert Verpflegung |
-| Program Manager | Koordiniert Programmabläufe |
-| Document Editor | Bearbeitet Dokumente |
-| Tax Advisor | Berät zu steuerlichen Fragen |
-| Musik Rechte Advisor | Berät zu Musikrechten |
-| Zusammenfasser | Erstellt Zusammenfassungen |
+Agents können folgende Kommandos in ihren Antworten verwenden:

-## Routen
+#### 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
+```

- `/` - Dashboard
- `/chat` - Chat mit Agenten
- `/tasks` - Task Verwaltung
- `/files` - Datei Verwaltung
+#### Subtask erstellen
+```
+@CREATE_SUBTASK
+Task: Location-Vertrag prüfen
+Requirements: Rechtliche Prüfung der Mietbedingungen
+@END
+```

-## Technologie
+#### Wissensdatenbank durchsuchen
+```
+@READ_KNOWLEDGE
+Topic: Budget
+@END
+```

- Flask 3.x
- Bootstrap 5
- Session-basierte Chat-Verwaltung
- Lokaler Datei-Upload
+#### 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
+```

-## Hinweise
+## 🗂️ Projekt-Struktur

- Dateien werden im `uploads/` Verzeichnis gespeichert
- Chat-Verlauf wird session-basiert gespeichert (max. 20 Einträge)
- Tasks werden im Speicher gehalten (nicht persistent)
+```
+frankenbot/
+├── app.py                          # Haupt-Flask-App (2128 Zeilen)
+├── agent_config.json               # Agent-Modell-Zuweisungen
+├── diversityball_knowledge.md      # Event-Wissensdatenbank
+├── email_journal.db                # SQLite-Datenbank (Emails)
+│
+├── 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)
+- **AI**: OpenCode CLI (Multi-Provider Support)
+- **Templates**: Jinja2
+- **Streaming**: Server-Sent Events (SSE)
+
+## 🎨 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) |
+| `/emails` | Email-Interface (Senden, Empfangen, Vorlagen) |
+
+## ⚙️ 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
+```
+
+### 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)
+
+## 📊 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
+
+### 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
+- ✅ Email-Whitelist: Nur autorisierte Absender
+- ✅ Exception-Handling: Spezifische Exception-Typen mit Logging
+- ✅ Request-Validierung: `.get()` mit Defaults
+- ✅ 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
+
+### 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**: 1.0.0  
+**Letztes Update**: Februar 2026  
+**Status**: Production-Ready ✅