frankenbot/QUICKSTART.md

🚀 Quick Start - Neue Features

1️⃣ Streaming-UI (Sofort verfügbar)

Wie verwendet man es

1. Gehe zur Seite → /orchestrator
2. Gib eine Anfrage ein (z.B. "Tell me about Diversity Ball")
3. Klick auf "Live-Antwort anfordern" (neuer Button)
4. Beobachte die Live-Updates:
   • ⏳ "Agent arbeitet..." - Status
   • 🤖 Agent-Name wird angezeigt
   • Schrittweise Antwort-Chunks erscheinen
   • ✓ "Verarbeitung abgeschlossen"

Unterschied zu "Klassisch senden"

• Live-Antwort: Server-Sent Events (SSE) Streaming

  • Echte Echtzeit Updates
  • Bessere UX bei langen Antworten
  • Timeout: 300 Sekunden (5 Minuten)

• Klassisch senden: POST Form

  • Traditionelle Request-Response
  • Wartet auf komplette Antwort
  • Alte Methode weiterhin verfügbar

---

2️⃣ Email-Integration

Minimal Setup (Gmail - 5 Minuten)

Schritt 1: 2FA aktivieren

Google Account → Sicherheit → "Bestätigung in zwei Schritten" aktivieren

Schritt 2: App-Passwort generieren

Gehe zu: https://myaccount.google.com/apppasswords
- Wähle: "Mail" + "Windows"
- Kopiere 16-Zeichen Passwort

Schritt 3: Umgebungsvariablen setzen

export IMAP_SERVER=imap.gmail.com
export SMTP_SERVER=smtp.gmail.com
export EMAIL_ADDRESS=deine-email@gmail.com
export EMAIL_PASSWORD=app-passwort-hier
export IMAP_PORT=993
export SMTP_PORT=587

Schritt 4: Starte App neu

python3 app.py

Schritt 5: Gehe zu /emails

http://localhost:5000/emails

Feature-Übersicht

📬 Emails empfangen

• Automatisch letzte 10 Emails laden
• Subject, From, Date, Preview anzeigen
• Klick auf Email → Modal mit Body-Text
• Lazy Loading (Body wird nur beim Klick geladen)

✉️ Emails versenden

• Neue Email-Form im linken Panel
• An, Betreff, Nachricht ausfüllen
• "Versenden" Button
• Success/Error Message nach Versand

⚙️ Status-Display

• Green Badge: "✓ Konfiguriert | Email: deine@email.com"
• Orange Alert: Konfiguration erforderlich
• Anleitung direkt in der UI

---

📋 Konfiguration

.env Datei (Alternative)

# Option 1: .env Datei erstellen
cp .env.example .env

# Option 2: Bearbeite .env mit deinen Credentials
nano .env
# oder
cat > .env << EOF
IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
EMAIL_ADDRESS=deine-email@gmail.com
EMAIL_PASSWORD=app-passwort
IMAP_PORT=993
SMTP_PORT=587
EOF

Andere Provider

Outlook/Office365:

IMAP_SERVER=imap-mail.outlook.com
SMTP_SERVER=smtp-mail.outlook.com

Yahoo:

IMAP_SERVER=imap.mail.yahoo.com
SMTP_SERVER=smtp.mail.yahoo.com

---

🧪 Tests

# Teste dass alles funktioniert
python3 test_features.py

# Output:
# ✓ PASS: Imports
# ✓ PASS: App Syntax
# ✓ PASS: Email Config
# ✓ PASS: Templates
# ✓ PASS: SSE Support

---

📚 Datei-Referenz

Datei	Änderung	Beschreibung
app.py	✏️ Geändert	+Email-Funktionen, +SSE-Route, Timeout 300s
templates/orchestrator.html	✏️ Geändert	+Streaming-Button, +JavaScript Handler
templates/emails.html	📄 Neu	Email-Management UI
.env.example	📄 Neu	Email-Config Template
FEATURES.md	📄 Neu	Detaillierte Feature-Doku
CHANGES.md	📄 Neu	Alle Änderungen gelistet
Alle anderen Templates	✏️ Geändert	+Email Navigation Link

---

❓ FAQs

F: Funktioniert Streaming auch ohne Email-Config?

A: Ja! Streaming und Email sind unabhängig. Streaming funktioniert sofort, Email benötigt Config.

F: Kann ich mehrere Email-Accounts verwenden?

A: Aktuell nur einer. Könnte erweitert werden (siehe FEATURES.md → Nächste Schritte).

F: Sicherheit - Wo werden Passwörter gespeichert?

A: Nur in Umgebungsvariablen/.env. Nicht im Code, nicht in der Datenbank. SSL/TLS für alle Verbindungen.

F: Was passiert wenn Email-Config fehlt?

A: /emails zeigt orange Alert mit Setup-Anleitung. Rest der App funktioniert normal.

F: Ist das Streaming wirklich "live"?

A: Ja! Server-Sent Events mit 50-Zeichen Chunks. Sie sehen Antwort während sie generiert wird.

F: Können Anhänge/Attachments empfangen/gesendet werden?

A: Aktuell nicht. Ist aber einfach zu erweitern (siehe FEATURES.md → Nächste Schritte).

---

🔧 Troubleshooting

Email-Login schlägt fehl (Gmail)

Error: [AUTH] Application-specific password required
↓
Lösung: 2FA muss aktiviert sein
Gehe zu: https://myaccount.google.com/apppasswords

IMAP-Connection Timeout

Error: Socket timeout
↓
Lösung: Firewall/ISP blockiert Port 993
Versuche: VPN oder anderen Provider (Outlook, Yahoo)

Streaming zeigt Fehler im Browser-Console

Error: fetch failed
↓
Lösung: 
1. App muss laufen (python3 app.py)
2. URL muss richtig sein (http://localhost:5000)
3. Prompt darf nicht leer sein

Templates nicht gefunden (404)

Error: TemplateNotFound: emails.html
↓
Lösung: Stelle sicher dass templates/emails.html existiert
ls -la templates/emails.html

---

📞 Support

Schaue dir an:

1. FEATURES.md - Detaillierte Feature-Dokumentation
2. CHANGES.md - Alle Code-Änderungen
3. test_features.py - Funktionalitäts-Tests
4. app.py - Source Code mit Kommentaren

---

✅ Checkliste für Setup

• Teste Streaming-UI (gehe zu /orchestrator)
• Lese .env.example (verstehe Email-Config)
• Aktiviere Gmail 2FA (wenn Gmail verwendet)
• Generiere App-Passwort
• Setze Umgebungsvariablen
• Starte App neu: python3 app.py
• Gehe zu /emails und teste Send/Receive
• Laufe test_features.py zum Validieren

---

Viel Spaß mit den neuen Features! 🎉