Brancheneinstufung2/lead-engine

Lead Engine: Multi-Source Automation v1.4 [31988f42]

🚀 Übersicht

Die Lead Engine ist ein spezialisiertes Modul zur autonomen Verarbeitung von B2B-Anfragen. Sie fungiert als Brücke zwischen dem E-Mail-Postfach und dem Company Explorer, um innerhalb von Minuten hochgradig personalisierte Antwort-Entwürfe auf "Human Expert Level" zu generieren.

🛠 Hauptfunktionen

1. Intelligenter E-Mail Ingest

• Multi-Source: Überwacht das Postfach info@robo-planet.de via Microsoft Graph API.
• Filter & Routing: Unterscheidet Anfragen von TradingTwins und dem Kontaktformular.
• Parsing: Spezialisierte HTML-Parser extrahieren strukturierte Daten (Firma, Kontakt, Bedarf).

2. Contact Research (LinkedIn Lookup)

• Automatisierung: Sucht via SerpAPI und Gemini 2.0 Flash nach der beruflichen Position.
• Ergebnis: Identifiziert Rollen (z.B. "CFO"), um den Tonfall anzupassen.

3. Company Explorer Sync & Monitoring

• Integration: Legt Accounts und Kontakte automatisch im CE an.
• Monitor: Hintergrund-Prozess (monitor.py) überwacht den Analyse-Status.
• Daten-Pull: Übernimmt Branche und Dossier in die lokale Lead-Datenbank.

4. Expert Response Generator

• KI-Engine: Gemini 2.0 Flash erstellt E-Mail-Entwürfe.
• Kontext: Kombiniert Lead-Daten + CE-Daten + Matrix-Argumente (Pains/Gains).

5. Trading Twins Autopilot (PRODUKTIV v2.1)

Der vollautomatische "Zero Touch" Workflow für Trading Twins Anfragen.

• Human-in-the-Loop: Elizabeta Melcer erhält eine Teams-Nachricht ("Approve/Deny").
• Feedback-Server: Ein integrierter FastAPI-Server (Port 8004) verarbeitet Klicks.
• Direct Calendar Booking (Micro-Service):
  • Logik: Prüft den Kalender von e.melcer auf echte Verfügbarkeit.
  • Raster: Termine starten nur im 15-Minuten-Takt (:00, :15, :30, :45).
  • Abstand: Bietet zwei Termine an, mit ca. 3 Stunden Pause dazwischen.
  • Buchung: Klick auf Link -> Server erstellt Outlook-Termin von info@ mit e.melcer als Teilnehmer.

🏗 Architektur

/app/lead-engine/
├── app.py                   # Streamlit Web-Interface
├── trading_twins_ingest.py  # E-Mail Importer (Graph API)
├── monitor.py               # Monitor + Trigger für Orchestrator
├── trading_twins/           # Autopilot Modul
│   ├── manager.py           # Orchestrator, FastAPI, Graph API Logic
│   ├── test_calendar_logic.py # Interner Test für Kalender-Zugriff
│   └── signature.html       # HTML-Signatur
└── db.py                    # Lokale SQLite Lead-Datenbank

🚨 Lessons Learned & Critical Fixes

1. Microsoft Graph API: Kalender-Zugriff

• Problem: debug_calendar.py scheiterte oft mit Invalid parameter.
• Ursache: URL-Encoding von Zeitstempeln (+ wurde zu Leerzeichen) und Mikrosekunden (7 Stellen statt 6).
• Lösung: Nutzung von requests(params=...) und Abschneiden der Mikrosekunden.
• Endpoint: /users/{email}/calendar/getSchedule (POST) ist robuster als /calendarView (GET).

2. Exchange AppOnly AccessPolicy (Buchungs-Workaround)

• Problem: Calendars.ReadWrite erlaubt einer App oft nicht, Termine in fremden Kalendern (e.melcer@) zu erstellen (403 Forbidden).
• Lösung: Der Termin wird im eigenen Kalender des Service-Accounts (info@) erstellt. Der Mitarbeiter (e.melcer@) wird als Teilnehmer hinzugefügt. Das umgeht die Policy.

3. Docker Environment Variables

• Problem: Skripte im Container fanden Credentials nicht, obwohl sie in .env standen.
• Lösung: Explizites load_dotenv ist in Standalone-Skripten (test_*.py) nötig. Im Hauptprozess (manager.py) reicht os.getenv, solange Docker Compose die Vars korrekt durchreicht.

🚀 Inbetriebnahme

# Neustart des Dienstes
docker-compose up -d --build --force-recreate lead-engine

# Manueller Test (intern)
docker exec lead-engine python /app/trading_twins/test_calendar_logic.py

Zugriff: https://floke-ai.duckdns.org/lead/ (Passwortgeschützt)

📝 Zukünftige Erweiterungen & Todos

Task: Race-Condition-Schutz bei Überbuchung

• Problem: Wenn mehrere Leads E-Mails mit denselben Terminvorschlägen erhalten, kann es zu "Race Conditions" kommen, bei denen mehrere Personen denselben Slot fast zeitgleich buchen.
• Lösung: Implementierung eines "Live-Checks" im Feedback-Server.
  1. Trigger: Ein Nutzer klickt auf einen Buchungslink.
  2. Aktion: Bevor der Termin im Kalender erstellt wird, sendet der Server eine erneute getSchedule-Anfrage an die Graph API für exakt diesen Zeit-Slot.
  3. Logik:
     • Slot frei: Der Termin wird wie geplant gebucht und der Job-Status auf booked gesetzt.
     • Slot belegt: Der Nutzer erhält eine freundliche Nachricht ("Dieser Termin wurde gerade vergeben."). Idealerweise werden ihm dynamisch zwei neue, freie Termine vorgeschlagen, die er direkt auf der Seite buchen kann.
• Ziel: Sicherstellen, dass der Kalender die "Single Source of Truth" ist und doppelte Buchungen zuverlässig verhindert werden.

Task: Integration der Buchungs-Seiten in WordPress

• Ziel: Eine nahtlose User Experience schaffen, bei der Termin-Bestätigungen auf der Haupt-Website (robo-planet.de) statt auf der direkten API-URL angezeigt werden.
• Phase 1 (Kurzfristig): Einbettung via iFrame
  • Umsetzung: Eine Seite in WordPress anlegen und die URL des Feedback-Servers (z.B. https://floke-ai.duckdns.org/feedback/book_slot/...) in einem iFrame laden.
  • Vorteil: Kein Programmieraufwand auf unserer Seite nötig, sofort umsetzbar.
• Phase 2 (Langfristig): Native API-Integration
  • Umsetzung: Die Links in der E-Mail führen direkt zu einer WordPress-Seite (z.B. robo-planet.de/termin-bestaetigen). Ein Skript auf dieser Seite ruft im Hintergrund unsere /book_slot API auf.
  • Vorteil: Perfekte Integration ins Corporate Design, volle Kontrolle über die Erfolgs- und Fehlermeldungen. Die API ist dafür bereits ausgelegt.

# Info-Postfach (App 1 - Schreiben)
INFO_Application_ID=...
INFO_Tenant_ID=...
INFO_Secret=...

# E.Melcer Kalender (App 2 - Lesen)
CAL_APPID=...
CAL_TENNANT_ID=...
CAL_SECRET=...

# URLs
TEAMS_WEBHOOK_URL=...
FEEDBACK_SERVER_BASE_URL=https://floke-ai.duckdns.org/feedback