Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a54d8b9c4ed53d9a16abf9cc10ea90e82e2b12ba
Brancheneinstufung2/readme.md
Floke a54d8b9c4e [2ff88f42] multiplikation vorbereitet 
multiplikation vorbereitet
2026-02-19 20:59:04 +00:00

73 KiB
Raw Blame History

WICHTIGER HINWEIS FÜR ALLE BENUTZER UND BOTS (INSBESONDERE LLMs)

=================================================================

DIESE DATEI IST DIE ZENTRALE DOKUMENTATION FÜR DAS GESAMTE PROJEKT.

LÖSCHEN SIE UNTER KEINEN UMSTÄNDEN INHALTE AUS DIESER DATEI!

Das versehentliche Kürzen oder Überschreiben dieser Datei hat in der Vergangenheit wiederholt zu erheblichem Informationsverlust geführt.

REGELN:

1. NICHT LÖSCHEN: Entfernen Sie keine Abschnitte. Wenn Informationen veraltet sind, markieren Sie sie als "VERALTET", aber löschen Sie sie nicht.

2. NUR HINZUFÜGEN: Fügen Sie neue Informationen am Ende des relevanten Abschnitts oder in einem neuen Abschnitt hinzu.

3. VOR DEM COMMIT PRÜFEN: Überprüfen Sie vor jedem Commit mittels git diff, dass Sie nicht versehentlich große Teile der Datei gelöscht haben.

Ihre Mitarbeit zur Erhaltung dieser Dokumentation ist entscheidend für den Projekterfolg.

=================================================================

include_toc: true gitea: none

Projekt: Automatisierte Unternehmensbewertung & Lead-Generierung v2.2.1

1. Projektübersicht & Architektur

Dieses Projekt ist eine modulare "Lead Enrichment Factory", die darauf ausgelegt ist, Unternehmensdaten aus einem D365-CRM-System automatisiert anzureichern, zu analysieren und für Marketing- & Vertriebszwecke aufzubereiten.

Die Architektur ist in mehrere, klar voneinander getrennte Funktionseinheiten gegliedert, die im Folgenden detailliert beschrieben werden.

Architektur im Überblick

I. DIE STEUERUNGS-EBENE (API & Ausführung)
   └── app.py (Flask API Server, startet Jobs)
   └── brancheneinstufung2.py (Der zentrale Orchestrator / Kommandozeile)

II. DIE KERN-PRODUKTIONSLINIE (Datenanreicherung)
    └── data_processor.py (Der "Motor", führt die Arbeit aus)
        ├── google_sheet_handler.py (Spezialist für Google Sheets)
        ├── wikipedia_scraper.py (Spezialist für Wikipedia-Daten)
        ├── sync_manager.py (Spezialist für den D365-Abgleich)
        └── helpers.py (Der "Werkzeugkasten" für alle)

III. DIE MARKETING-PRODUKTIONSLINIE (Content-Erstellung)
     └── generate_marketing_text.py (Erstellt E-Mail-Texte)
         └── INPUT: marketing_wissen_final.yaml (Die Wissensbasis)

IV. DIE WISSENSBASIS-FABRIK (ETL-Pipelines zur Erstellung der Wissensbasis)
    ├── build_knowledge_base.py (Baut die Marketing-KB aus der config.py)
    ├── expand_knowledge_base.py (Erweitert die Marketing-KB)
    ├── extract_insights.py (Baut die Marketing-KB aus Word-Dokumenten)
    └── generate_knowledge_base.py (Erstellt einen Entwurf für die Marketing-KB)

V. DAS KLASSIFIZIERUNGS-SYSTEM (Job-Titel-Analyse)
   ├── contact_grouping.py (Klassifiziert Job-Titel)
   └── knowledge_base_builder.py (Baut die Wissensbasis FÜR die Klassifizierung)

VI. DAS STANDALONE-WERKZEUG
    └── company_deduplicator.py (Eigenständiger Duplikats-Check für externe und interne Listen)

VII. DIE STRATEGIE-SCHMIEDE (GTM Architect)
    └── gtm_architect_orchestrator.py (Strategie-Entwicklung)
        ├── gtm-architect/ (React Frontend)
        └── server.cjs (Node.js API-Bridge)

VIII. MARKETING AUTOMATION CORE (Company Explorer)
    └── Backend-Logik für hyper-personalisierte E-Mail-Texte (vertical x persona)
        ├── database.py (Neue 'Persona' Tabelle, angepasste 'MarketingMatrix')
        ├── scripts/seed_marketing_data.py (Befüllt 'Persona' mit Pains/Gains)
        ├── scripts/sync_notion_personas.py (Synchronisiert Personas aus Notion)
        └── scripts/generate_matrix.py (Generiert Texte für alle Vertical x Persona Kombinationen)

IX. DAS FUNDAMENT
     └── config.py (Einstellungen & Konstanten für ALLE)

2. Steuerung & Ausführung (Control & Execution)

Diese Ebene bildet die Schnittstelle zur Außenwelt und startet die verschiedenen Prozesse.

app.py (API Server)

Hauptfunktion

Das Modul app.py implementiert eine einfache Flask-Webanwendung, die als API-Endpunkt für das gesamte System dient. Es ermöglicht das Starten von langlaufenden Skripten (wie dem Duplikats-Check oder der Branchen-Neuklassifizierung) als asynchrone Hintergrundprozesse. Die Anwendung verwaltet diese Prozesse über eindeutige Job-IDs und bietet Endpunkte zum Starten von Aktionen und zum Abrufen des Status dieser Jobs. Dies ermöglicht eine lose Kopplung und die Steuerung des Systems durch externe Aufrufe, z.B. aus einem Frontend oder einem anderen Service.

Methodenbeschreibung

  • status_check(): Ein einfacher /status-Endpunkt (GET), der eine "ok"-Nachricht zurückgibt. Dient als Health-Check, um zu überprüfen, ob die Flask-Anwendung läuft.
  • setup_ngrok(): Eine Hilfsfunktion, die einen ngrok-Tunnel startet, um den lokalen Flask-Server über eine öffentliche URL erreichbar zu machen. Dies ist nützlich für das Testen und die Demonstration in Umgebungen ohne öffentliche IP.
  • run_script(): Der Hauptendpunkt /run-script (POST), der eine Aktion entgegennimmt (z.B. "run_duplicate_check"). Basierend auf der Aktion wird das entsprechende Python-Skript (duplicate_checker.py, brancheneinstufung2.py, etc.) als separater Hintergrundprozess gestartet. Für jeden gestarteten Prozess wird eine eindeutige Job-ID generiert und eine initiale Statusdatei im job_status-Verzeichnis erstellt.
  • get_status(): Ein /get-status-Endpunkt (GET), der den Inhalt aller im job_status-Verzeichnis gespeicherten JSON-Dateien ausliest. Dies ermöglicht es, den Fortschritt und den aktuellen Status aller gestarteten und abgeschlossenen Jobs abzufragen. Die Ergebnisse werden als JSON-Array zurückgegeben, wobei die neuesten Jobs zuerst aufgeführt sind.

brancheneinstufung2.py (Orchestrator / Kommandozeile)

Hauptfunktion

Das Skript brancheneinstufung2.py ist der zentrale Einstiegspunkt und Orchestrator für die Datenanreicherungs-Pipeline. Es dient nicht der direkten Implementierung der Verarbeitungslogik, sondern dem Parsen von Kommandozeilen-Argumenten, der Initialisierung von Handler-Klassen (GoogleSheetHandler, WikipediaScraper, DataProcessor, SyncManager) und dem Starten des vom Benutzer ausgewählten Verarbeitungsmodus. Das Skript ist hochgradig modular und delegiert die eigentliche Arbeit an die DataProcessor-Klasse.

Abhängigkeiten

  • Standardbibliotheken: logging, os, argparse, time, datetime.
  • Lokale Module:
    • config.py: Stellt globale Konfigurationsparameter und die Projektversion bereit.
    • helpers.py: Bietet Hilfsfunktionen, z.B. für das Erstellen von Log-Dateinamen und das Initialisieren des Branchenschemas.
    • google_sheet_handler.py: Kapselt die gesamte Kommunikation mit der Google Sheets API.
    • wikipedia_scraper.py: Stellt Methoden zum Suchen und Parsen von Wikipedia-Artikeln bereit.
    • data_processor.py: Enthält die Kernlogik für alle Datenverarbeitungsschritte.
    • sync_manager.py: Implementiert die Logik zum Abgleich von CRM-Exporten mit dem Google Sheet.

Wichtige Funktionen/Methoden

Die Logik des Skripts ist primär in der main()-Funktion enthalten und lässt sich in folgende Schritte unterteilen:

  1. Argumenten-Parsing: Mittels argparse wird die Kommandozeile ausgewertet. Der wichtigste Parameter ist --mode, der den auszuführenden Prozess festlegt (z.B. sync, full_run, reeval, predict_technicians). Weitere Parameter wie --limit oder --start_sheet_row erlauben eine feingranulare Steuerung der zu verarbeitenden Datenmenge.
  2. Interaktiver Modus: Wird kein --mode übergeben, startet ein interaktiver Modus, in dem der Benutzer aus einer Liste aller verfügbaren Modi auswählen kann.
  3. Initialisierung: Basierend auf dem gewählten Modus werden die notwendigen Klassen instanziiert. Für die meisten Anreicherungs-Modi wird ein DataProcessor-Objekt erstellt, das wiederum Instanzen des GoogleSheetHandler und WikipediaScraper erhält. Für den sync-Modus wird der SyncManager verwendet.
  4. Modus-Dispatching: Eine if/elif/else-Struktur leitet die Ausführung an die passende Methode weiter.
    • sync / simulate_sync: Ruft den SyncManager auf, um einen D365-Excel-Export mit dem Google Sheet abzugleichen.
    • full_run: Startet einen sequentiellen Anreicherungsprozess für Zeilen, die noch nicht verarbeitet wurden.
    • reeval: Verarbeitet Zeilen, die explizit für eine Neubewertung markiert wurden.
    • reclassify_branches: Führt eine Neubewertung der Branchenzuordnung für alle oder eine Teilmenge der Zeilen durch.
    • train_technician_model / predict_technicians: Steuert das Training und die Anwendung eines Machine-Learning-Modells zur Vorhersage von Techniker-Anzahlen.
    • Dynamische Aufrufe: Viele Modi (z.B. wiki_verify, website_scraping) werden dynamisch aufgerufen, indem Methoden des DataProcessor-Objekts ausgeführt werden, deren Namen dem Modus entsprechen (z.B. process_wiki_verify).
  5. Fehlerbehandlung und Logging: Das gesamte Skript ist von einem try...except...finally-Block umschlossen, der Fehler abfängt, protokolliert und sicherstellt, dass das Logging am Ende sauber beendet wird.

Kernlogik (data_processor.py)

Die Klasse DataProcessor ist das Herzstück der Anreicherungslogik und enthält alle Methoden zur schrittweisen Verarbeitung von Unternehmensdaten.

setup()

  • Zweck: Initialisiert den DataProcessor, indem das Ziel-Branchenschema geladen und das trainierte Machine-Learning-Modell für die Technikerschätzung in den Speicher geladen wird.
  • Input: Keine direkten Argumente, greift aber auf die Konfigurationsdateien (ziel_Branchenschema.csv, technician_decision_tree_model.pkl etc.) zu.
  • Output: Gibt True bei Erfolg zurück und setzt das interne Flag is_setup_complete. Bei Fehlern wird False zurückgegeben und das Skript beendet.

process_rows_sequentially(...)

  • Zweck: Führt den vollständigen, schrittweisen Anreicherungsprozess für einen definierten Bereich von Zeilen im Google Sheet aus. Dies ist der Hauptmodus für die initiale Verarbeitung neuer Daten.
  • Input: start_sheet_row (Startzeile), num_to_process (Anzahl der Zeilen), sowie boolesche Flags (process_wiki_steps, process_chatgpt_steps, etc.) zur Steuerung der auszuführenden Anreicherungsschritte.
  • Output: Die Methode hat keinen direkten Rückgabewert, aber ihr Seiteneffekt ist die Aktualisierung der verarbeiteten Zeilen im Google Sheet mit den angereicherten Daten.

process_reevaluation_rows(...)

  • Zweck: Führt den vollständigen Anreicherungsprozess gezielt für Zeilen aus, die im Google Sheet manuell mit einem 'x' in der "ReEval Flag"-Spalte markiert wurden. Vor der Neubewertung werden alle zuvor abgeleiteten Daten in der Zeile gelöscht.
  • Input: row_limit (maximale Anzahl zu verarbeitender Zeilen), clear_flag (ob das 'x'-Flag nach der Verarbeitung entfernt werden soll) und die booleschen Flags zur Schritt-Steuerung.
  • Output: Aktualisiert die markierten Zeilen im Google Sheet mit neu angereicherten Daten.

process_website_scraping(...)

  • Zweck: Führt einen Batch-Prozess ausschließlich für das Scrapen von Websites durch. Die Methode identifiziert Zeilen, in denen der "Website Scrape Timestamp" fehlt, und extrahiert parallel den Rohtext und die Meta-Details der jeweiligen Unternehmens-Websites.
  • Input: start_sheet_row, end_sheet_row, limit zur Eingrenzung des Verarbeitungsbereichs.
  • Output: Schreibt den extrahierten Rohtext, Meta-Details, einen Status zur URL-Prüfung und einen Zeitstempel in die entsprechenden Spalten im Google Sheet.

process_summarize_website(...)

  • Zweck: Führt einen Batch-Prozess zur Zusammenfassung von bereits extrahierten Website-Rohtexten mittels KI durch.
  • Input: start_sheet_row, end_sheet_row, limit. Die Methode verarbeitet Zeilen, bei denen der Rohtext vorhanden, aber die Zusammenfassung noch leer ist.
  • Output: Schreibt die KI-generierte Zusammenfassung in die Spalte "Website Zusammenfassung" im Google Sheet.

process_branch_batch(...) / reclassify_all_branches(...)

  • Zweck: Führt eine (Neu-)Bewertung der Branchenzugehörigkeit für einen Zeilenbereich im Batch-Verfahren durch. Die Methode sammelt relevante Informationen (CRM-Daten, Website-Zusammenfassung, Wikipedia-Inhalte) und sendet sie gebündelt an die KI, um eine effiziente und konsistente Brancheneinstufung zu erhalten.
  • Input: start_sheet_row, end_sheet_row, limit.
  • Output: Aktualisiert die Spalten zur KI-basierten Brancheneinstufung ("Chat Vorschlag Branche", Konfidenz, Begründung etc.) im Google Sheet.

process_wiki_verify(...)

  • Zweck: Verifiziert in einem Batch-Prozess, ob der in einer Zeile hinterlegte Wikipedia-Artikel thematisch zum Unternehmen passt. Nutzt KI, um die Konsistenz zu prüfen und ggf. einen passenderen Artikel vorzuschlagen.
  • Input: start_sheet_row, end_sheet_row, limit. Verarbeitet Zeilen, die eine Wiki-URL, aber noch keinen Verifizierungs-Timestamp haben.
  • Output: Schreibt das Ergebnis der KI-Prüfung (OK, X), eine Begründung und ggf. einen Alternativvorschlag in die entsprechenden Spalten im Google Sheet.

process_find_wiki_serp(...)

  • Zweck: Sucht für große Unternehmen (definiert über Mindestumsatz/-mitarbeiter), bei denen noch keine Wikipedia-URL bekannt ist, über eine Google-Suche (SerpAPI) nach einem passenden Wikipedia-Artikel.
  • Input: start_sheet_row, end_sheet_row, limit, min_employees, min_umsatz.
  • Output: Wenn eine passende URL gefunden wird, wird diese in die "Wiki URL"-Spalte eingetragen und die Zeile für eine Neubewertung (ReEval Flag) markiert.

process_contact_search(...)

  • Zweck: Führt eine Suche nach LinkedIn-Kontakten für bestimmte Positionen (z.B. Serviceleiter, IT-Leiter) bei den Unternehmen im Sheet durch.
  • Input: start_sheet_row, end_sheet_row, limit. Verarbeitet Zeilen, die noch keinen "Contact Search Timestamp" haben.
  • Output: Schreibt die Anzahl der gefundenen Kontakte pro Kategorie in die "Linked... gefunden"-Spalten und speichert detaillierte Kontaktinformationen in einem separaten "Contacts"-Tabellenblatt.

train_technician_model()

  • Zweck: Bereitet die vorhandenen Daten auf, trainiert ein Machine-Learning-Modell (RandomForest) zur Vorhersage von Servicetechniker-Anzahlen, führt ein Hyperparameter-Tuning durch und speichert das trainierte Modell sowie den zugehörigen Imputer als .pkl-Dateien.
  • Input: Keine direkten Argumente. Die Methode liest die Trainingsdaten aus dem konfigurierten Google Sheet.
  • Output: Erstellt und speichert die technician_decision_tree_model.pkl- und median_imputer.pkl-Dateien sowie eine JSON-Datei mit den verwendeten Features.

process_predict_technicians(...)

  • Zweck: Wendet das trainierte ML-Modell auf Zeilen an, für die noch keine Techniker-Schätzung vorliegt, aber die notwendigen Input-Features (Umsatz, Mitarbeiter, Branche) vorhanden sind.
  • Input: start_sheet_row, end_sheet_row, limit.
  • Output: Schreibt den vorhergesagten Techniker-Bucket (z.B. "Techniker_Klein (0-49)") in die Spalte "Geschaetzter Techniker Bucket".

3. Kern-Produktionslinie: Datenanreicherung

Dies ist das Herzstück der Fabrik, in dem die eigentliche Anreicherung der Unternehmensdaten stattfindet.

data_processor.py (Der "Motor")

Hauptfunktion

Die Klasse DataProcessor ist das Herzstück der Anreicherungslogik und enthält alle Methoden zur schrittweisen Verarbeitung von Unternehmensdaten. Sie wird vom Orchestrator (brancheneinstufung2.py) aufgerufen und nutzt verschiedene Spezialisten-Module, um ihre Aufgaben zu erfüllen.

Die Klasse DataProcessor ist das Herzstück der Anreicherungslogik und enthält alle Methoden zur schrittweisen Verarbeitung von Unternehmensdaten.

setup()

  • Zweck: Initialisiert den DataProcessor, indem das Ziel-Branchenschema geladen und das trainierte Machine-Learning-Modell für die Technikerschätzung in den Speicher geladen wird.
  • Input: Keine direkten Argumente, greift aber auf die Konfigurationsdateien (ziel_Branchenschema.csv, technician_decision_tree_model.pkl etc.) zu.
  • Output: Gibt True bei Erfolg zurück und setzt das interne Flag is_setup_complete. Bei Fehlern wird False zurückgegeben und das Skript beendet.

process_rows_sequentially(...)

  • Zweck: Führt den vollständigen, schrittweisen Anreicherungsprozess für einen definierten Bereich von Zeilen im Google Sheet aus. Dies ist der Hauptmodus für die initiale Verarbeitung neuer Daten.
  • Input: start_sheet_row (Startzeile), num_to_process (Anzahl der Zeilen), sowie boolesche Flags (process_wiki_steps, process_chatgpt_steps, etc.) zur Steuerung der auszuführenden Anreicherungsschritte.
  • Output: Die Methode hat keinen direkten Rückgabewert, aber ihr Seiteneffekt ist die Aktualisierung der verarbeiteten Zeilen im Google Sheet mit den angereicherten Daten.

process_reevaluation_rows(...)

  • Zweck: Führt den vollständigen Anreicherungsprozess gezielt für Zeilen aus, die im Google Sheet manuell mit einem 'x' in der "ReEval Flag"-Spalte markiert wurden. Vor der Neubewertung werden alle zuvor abgeleiteten Daten in der Zeile gelöscht.
  • Input: row_limit (maximale Anzahl zu verarbeitender Zeilen), clear_flag (ob das 'x'-Flag nach der Verarbeitung entfernt werden soll) und die booleschen Flags zur Schritt-Steuerung.
  • Output: Aktualisiert die markierten Zeilen im Google Sheet mit neu angereicherten Daten.

process_website_scraping(...)

  • Zweck: Führt einen Batch-Prozess ausschließlich für das Scrapen von Websites durch. Die Methode identifiziert Zeilen, in denen der "Website Scrape Timestamp" fehlt, und extrahiert parallel den Rohtext und die Meta-Details der jeweiligen Unternehmens-Websites.
  • Input: start_sheet_row, end_sheet_row, limit zur Eingrenzung des Verarbeitungsbereichs.
  • Output: Schreibt den extrahierten Rohtext, Meta-Details, einen Status zur URL-Prüfung und einen Zeitstempel in die entsprechenden Spalten im Google Sheet.

process_summarize_website(...)

  • Zweck: Führt einen Batch-Prozess zur Zusammenfassung von bereits extrahierten Website-Rohtexten mittels KI durch.
  • Input: start_sheet_row, end_sheet_row, limit. Die Methode verarbeitet Zeilen, bei denen der Rohtext vorhanden, aber die Zusammenfassung noch leer ist.
  • Output: Schreibt die KI-generierte Zusammenfassung in die Spalte "Website Zusammenfassung" im Google Sheet.

process_branch_batch(...) / reclassify_all_branches(...)

  • Zweck: Führt eine (Neu-)Bewertung der Branchenzugehörigkeit für einen Zeilenbereich im Batch-Verfahren durch. Die Methode sammelt relevante Informationen (CRM-Daten, Website-Zusammenfassung, Wikipedia-Inhalte) und sendet sie gebündelt an die KI, um eine effiziente und konsistente Brancheneinstufung zu erhalten.
  • Input: start_sheet_row, end_sheet_row, limit.
  • Output: Aktualisiert die Spalten zur KI-basierten Brancheneinstufung ("Chat Vorschlag Branche", Konfidenz, Begründung etc.) im Google Sheet.

process_wiki_verify(...)

  • Zweck: Verifiziert in einem Batch-Prozess, ob der in einer Zeile hinterlegte Wikipedia-Artikel thematisch zum Unternehmen passt. Nutzt KI, um die Konsistenz zu prüfen und ggf. einen passenderen Artikel vorzuschlagen.
  • Input: start_sheet_row, end_sheet_row, limit. Verarbeitet Zeilen, die eine Wiki-URL, aber noch keinen Verifizierungs-Timestamp haben.
  • Output: Schreibt das Ergebnis der KI-Prüfung (OK, X), eine Begründung und ggf. einen Alternativvorschlag in die entsprechenden Spalten im Google Sheet.

process_find_wiki_serp(...)

  • Zweck: Sucht für große Unternehmen (definiert über Mindestumsatz/-mitarbeiter), bei denen noch keine Wikipedia-URL bekannt ist, über eine Google-Suche (SerpAPI) nach einem passenden Wikipedia-Artikel.
  • Input: start_sheet_row, end_sheet_row, limit, min_employees, min_umsatz.
  • Output: Wenn eine passende URL gefunden wird, wird diese in die "Wiki URL"-Spalte eingetragen und die Zeile für eine Neubewertung (ReEval Flag) markiert.

process_contact_search(...)

  • Zweck: Führt eine Suche nach LinkedIn-Kontakten für bestimmte Positionen (z.B. Serviceleiter, IT-Leiter) bei den Unternehmen im Sheet durch.
  • Input: start_sheet_row, end_sheet_row, limit. Verarbeitet Zeilen, die noch keinen "Contact Search Timestamp" haben.
  • Output: Schreibt die Anzahl der gefundenen Kontakte pro Kategorie in die "Linked... gefunden"-Spalten und speichert detaillierte Kontaktinformationen in einem separaten "Contacts"-Tabellenblatt.

train_technician_model()

  • Zweck: Bereitet die vorhandenen Daten auf, trainiert ein Machine-Learning-Modell (RandomForest) zur Vorhersage von Servicetechniker-Anzahlen, führt ein Hyperparameter-Tuning durch und speichert das trainierte Modell sowie den zugehörigen Imputer als .pkl-Dateien.
  • Input: Keine direkten Argumente. Die Methode liest die Trainingsdaten aus dem konfigurierten Google Sheet.
  • Output: Erstellt und speichert die technician_decision_tree_model.pkl- und median_imputer.pkl-Dateien sowie eine JSON-Datei mit den verwendeten Features.

process_predict_technicians(...)

  • Zweck: Wendet das trainierte ML-Modell auf Zeilen an, für die noch keine Techniker-Schätzung vorliegt, aber die notwendigen Input-Features (Umsatz, Mitarbeiter, Branche) vorhanden sind.
  • Input: start_sheet_row, end_sheet_row, limit.
  • Output: Schreibt den vorhergesagten Techniker-Bucket (z.B. "Techniker_Klein (0-49)") in die Spalte "Geschaetzter Techniker Bucket".

Spezialisten-Module

google_sheet_handler.py (Spezialist für Google Sheets)

Hauptfunktion

Das Modul google_sheet_handler.py dient als zentraler Wrapper für sämtliche Interaktionen mit dem Google Sheet, das als primärer Datenspeicher für das Projekt fungiert. Es abstrahiert die Komplexität der gspread API und stellt eine robuste, wiederverwendbare Schnittstelle für Lese- und Schreibvorgänge bereit. Die Klasse GoogleSheetHandler kapselt die Verbindungslogik, die Authentifizierung über Service-Accounts und bietet Methoden für spezifische Datenmanipulationen.

Methodenbeschreibung

  • __init__(self, sheet_url=None): Der Konstruktor initialisiert den Handler. Er übernimmt optional eine sheet_url. Wenn keine URL angegeben wird, greift er auf den Wert aus der config.py zurück.

  • load_data(self): Stellt die Verbindung zum Google Sheet her (falls noch nicht geschehen) und lädt den gesamten Inhalt des Haupt-Arbeitsblatts in den internen Speicher der Klasse. Diese Methode ist mit einem Retry-Decorator versehen, um bei temporären Netzwerkproblemen robust zu sein.

  • get_sheet_as_dataframe(self, sheet_name): Liest ein spezifisches Arbeitsblatt (über sheet_name identifiziert) aus dem Google Sheet und gibt dessen Inhalt als Pandas DataFrame zurück. Dies ist nützlich für datenanalytische Aufgaben.

  • append_rows(self, sheet_name, values): Fügt eine oder mehrere neue Zeilen am Ende eines bestimmten Arbeitsblatts an. values ist dabei eine Liste von Listen (jede innere Liste repräsentiert eine Zeile).

  • clear_and_write_data(self, sheet_name, data): Löscht den gesamten Inhalt eines Arbeitsblatts und schreibt anschließend neue Daten hinein. Dies ist nützlich, um ein Sheet vollständig zu synchronisieren.

  • batch_update_cells(self, update_data): Führt eine Stapelverarbeitung von Zell-Updates durch. Diese Methode ist wesentlich performanter als einzelne Zell-Updates, da sie mehrere Änderungen in einer einzigen API-Anfrage bündelt.

  • get_main_sheet_name(self): Gibt den Namen des Haupt-Arbeitsblatts (typischerweise 'Tabelle1') zurück.

wikipedia_scraper.py (Spezialist für Wikipedia)

Hauptfunktion

Das Modul wikipedia_scraper.py kapselt alle Interaktionen mit Wikipedia. Seine Hauptaufgabe ist es, für ein gegebenes Unternehmen den relevantesten Wikipedia-Artikel zu finden, diesen zu validieren und anschließend strukturierte Daten wie den Unternehmenssitz, die Branche, den Umsatz und die Mitarbeiterzahl aus dem Artikel zu extrahieren. Es verwendet eine "Google-First"-Strategie, bei der die SerpAPI zur Identifizierung des wahrscheinlichsten Artikels genutzt wird, bevor eine detaillierte, faktenbasierte Validierung erfolgt.

Methodenbeschreibung

  • __init__(self, user_agent=None): Initialisiert den Scraper, setzt die Sprache für die wikipedia-Bibliothek (typischerweise 'de') und konfiguriert eine requests.Session mit einem benutzerdefinierten User-Agent für HTTP-Anfragen.

  • serp_wikipedia_lookup(self, company_name, lang='de'): Nutzt die SerpAPI, um eine Google-Suche nach dem offiziellen Wikipedia-Artikel eines Unternehmens durchzuführen. Dies ist der erste und wichtigste Schritt, um einen Kandidaten-Artikel zu finden.

  • search_company_article(self, company_name, ...): Orchestriert den gesamten Such- und Validierungsprozess. Ruft zuerst serp_wikipedia_lookup auf, um eine URL zu erhalten. Anschließend wird der gefundene Artikel geladen und mit der internen Methode _validate_article auf Relevanz geprüft.

  • _validate_article(self, page, company_name, ...): Führt eine faktenbasierte Überprüfung eines Wikipedia-Artikels durch. Anstatt sich nur auf den Titel zu verlassen, prüft die Methode harte Kriterien wie die Übereinstimmung der Website-Domain (aus den Weblinks des Artikels) oder des Unternehmenssitzes (aus der Infobox).

  • extract_company_data(self, url_or_page): Die zentrale Extraktionsmethode. Nimmt eine URL oder ein wikipedia.page-Objekt entgegen und extrahiert daraus strukturierte Daten. Sie parst die Infobox des Artikels, um Werte für Branche, Umsatz, Mitarbeiter und Sitz zu finden, und extrahiert zusätzlich den Einleitungstext sowie die Kategorien.

  • _extract_infobox_value(self, soup, target): Eine interne Hilfsmethode, die gezielt nach Schlüsselwörtern (z.B. "Branche", "Umsatz") in der Infobox eines Artikels sucht und den zugehörigen Wert extrahiert und normalisiert.

  • _parse_sitz_string_detailed(self, raw_sitz_string_input): Eine spezialisierte Hilfsmethode, die versucht, aus dem oft unstrukturierten Textfeld für den Unternehmenssitz die Stadt und das Land zu trennen und zu normalisieren.

sync_manager.py (Spezialist für D365-Abgleich)

Hauptfunktion

Das Modul sync_manager.py ist für den robusten und intelligenten Datenabgleich zwischen einem D365 Excel-Export und dem Google Sheet verantwortlich. Es implementiert einen "Full-Sync"-Mechanismus, der neue, geänderte und potenziell zu archivierende Datensätze identifiziert. Der Manager stellt sicher, dass das Google Sheet die aktuellsten Informationen aus dem D365-Export widerspiegelt, wobei definierte Regeln für die Datenpriorisierung und Konfliktlösung angewendet werden.

Methodenbeschreibung

  • _normalize_text_for_comparison(self, text: str) -> str: Eine interne Hilfsmethode, die Text normalisiert, um irrelevante Whitespace-Unterschiede zu ignorieren und so präzisere Vergleiche zu ermöglichen.

  • __init__(self, sheet_handler, d365_export_path): Der Konstruktor initialisiert den SyncManager mit einem GoogleSheetHandler-Objekt und dem Pfad zum D365 Excel-Export. Es definiert auch die Spaltenzuordnungen zwischen D365 und Google Sheet (d365_to_gsheet_map) sowie die Regeln, welche Spalten bei Konflikten Priorität haben (d365_wins_cols, smart_merge_cols).

  • _load_data(self): Lädt und bereitet die Daten aus dem D365 Excel-Export und dem Google Sheet vor. Diese Methode ist robust gegenüber "verschmutzten" Headern im Google Sheet und stellt sicher, dass beide Datensätze in einem konsistenten Format für den Abgleich vorliegen. Sie identifiziert auch neue und bestehende IDs.

  • run_sync(self): Orchestriert den gesamten Synchronisationsprozess. Nach dem Laden der Daten identifiziert es neue Accounts, aktualisiert bestehende Accounts gemäß den definierten Regeln (D365-Werte überschreiben GSheet-Werte für bestimmte Spalten, Smart-Merge für andere) und sammelt Statistiken über die durchgeführten Änderungen und Konflikte. Alle Änderungen werden in Batches an das Google Sheet gesendet.

  • debug_sync(self, debug_id=None): Bietet einen Debug-Modus für den Synchronisationsprozess. Ohne debug_id wird eine allgemeine Statistik über neue, bestehende und gelöschte IDs ausgegeben. Mit einer spezifischen debug_id führt es eine Tiefenanalyse für einen einzelnen Datensatz durch, zeigt Rohdaten und verarbeitete Daten und vergleicht kritische Felder.

  • simulate_sync(self, debug_id=None): Führt eine "Trockenlauf"-Simulation des Synchronisationsprozesses durch, ohne tatsächlich Daten im Google Sheet zu ändern. Es generiert einen detaillierten Bericht über alle potenziellen Änderungen, Updates und Konflikte, die im Falle eines echten Laufs auftreten würden. Dies ist nützlich zur Vorabprüfung und Fehleranalyse.

4. Marketing-Produktionslinie: Content-Erstellung

Diese Produktionslinie nutzt die angereicherten Daten, um direkt verwertbaren Marketing-Content zu erstellen.

generate_marketing_text.py (Marketing Text Engine)

Hauptfunktion

Das Modul generate_marketing_text.py ist eine spezialisierte Engine zur automatischen Erstellung von hochgradig personalisierten Marketing-Texten. Es kombiniert eine strukturierte Wissensbasis (marketing_wissen_final.yaml) mit der Leistungsfähigkeit eines großen Sprachmodells (LLM), um für jede Kombination aus Zielbranche und Ansprechpartner-Position maßgeschneiderte Textbausteine für E-Mail-Kampagnen zu generieren. Das Skript ist so konzipiert, dass es nur neue, noch nicht existierende Textkombinationen erstellt und diese an ein Google Sheet anhängt, um die Effizienz zu maximieren.

Methodenbeschreibung

  • call_openai_with_retry(prompt, max_retries=3, delay=5): Eine robuste Wrapper-Funktion für Aufrufe an die OpenAI API. Sie implementiert eine Wiederholungslogik mit exponentiellem Backoff, um bei temporären API-Fehlern oder Netzwerkproblemen stabil zu bleiben.

  • build_prompt(branch_name, branch_data, position_name, position_data): Diese Funktion baut dynamisch den "Master-Prompt" für die KI zusammen. Sie integriert kontextbezogene Informationen wie die Herausforderungen (Pain Points) der Zielbranche und der spezifischen Ansprechpartner-Position. Eine wichtige Logik hierbei ist die dynamische Auswahl von Referenzkunden: Sind branchenspezifische Referenzen in der Wissensbasis vorhanden, werden diese verwendet; andernfalls greift die Funktion auf eine allgemeine Liste von Fallback-Referenzen zurück.

  • main(specific_branch=None): Die Haupt-Orchestrierungsfunktion des Skripts.

    1. Initialisierung: Richtet das Logging ein, lädt API-Schlüssel und die Wissensbasis aus der YAML-Datei.
    2. Laden bestehender Texte: Stellt eine Verbindung zum Google Sheet (OUTPUT_SHEET_NAME) her und lädt alle bereits generierten Textkombinationen, um doppelte Generierungen zu vermeiden.
    3. Generierungs-Loop: Iteriert über alle möglichen Kombinationen von Branchen und Positionen aus der Wissensbasis.
    4. Überspringen-Logik: Prüft für jede Kombination, ob sie bereits im Google Sheet vorhanden ist. Wenn ja, wird sie übersprungen.
    5. Text-Generierung: Für neue Kombinationen wird der build_prompt aufgerufen, um den Prompt zu erstellen, und call_openai_with_retry, um die Textbausteine (Betreff, Einleitung, Referenz-Block) als JSON-Objekt zu generieren.
    6. Ergebnisse anhängen: Alle neu generierten Texte werden gesammelt und am Ende des Prozesses in einem einzigen Batch-Aufruf an das Google Sheet angehängt, um die Anzahl der API-Aufrufe an Google zu minimieren.

5. ETL-Pipeline: Erstellung der Marketing-Wissensbasis

Dieser Bereich enthält alle Skripte, die als ETL-Pipelines (Extract, Transform, Load) dienen, um die zentrale Wissensbasis (marketing_wissen.yaml) aus verschiedenen Quellen zu erstellen und zu pflegen.

build_knowledge_base.py

Hauptfunktion

Das Modul build_knowledge_base.py ist dafür verantwortlich, eine umfassende Wissensbasis für die Marketing-Text-Generierung zu erstellen. Es nutzt die in config.py definierten Brancheninformationen, um mittels KI für jede Branche ein detailliertes Dossier zu erstellen. Aus diesem Dossier werden dann strukturierte Daten wie eine Zusammenfassung, operative "Pain Points" und branchenspezifische Schlüsselbegriffe extrahiert. Das Endergebnis ist eine einzelne YAML-Datei (marketing_wissen_final.yaml), die als "Single Source of Truth" für die Textgenerierung dient.

Methodenbeschreibung

  • call_openai_with_retry(prompt, is_extraction=False, ...): Eine Wrapper-Funktion für OpenAI-API-Aufrufe, die eine Wiederholungslogik für den Fall von Fehlern implementiert. Sie kann sowohl für die Generierung von Freitext als auch für die Extraktion von strukturierten JSON-Daten konfiguriert werden.

  • generate_research_prompt(branch_name, branch_info): Erstellt einen Prompt für die KI, um ein detailliertes Branchen-Dossier zu generieren. Der Prompt wird mit Kontext aus der config.py angereichert, einschließlich der Branchendefinition und Beispielunternehmen, um eine hohe Relevanz sicherzustellen.

  • generate_extraction_prompt(dossier_content): Erstellt einen zweiten Prompt, der die KI anweist, aus dem zuvor generierten Dossier-Text strukturierte Informationen zu extrahieren. Der Fokus liegt hierbei auf operativen "Pain Points", die für den Außendienst relevant sind.

  • main(branches_to_process=None): Die Hauptfunktion, die den gesamten Prozess orchestriert:

    1. Initialisierung: Lädt die API-Schlüssel und bereitet die Grundstruktur der Wissensbasis vor, einschließlich vordefinierter "Pain Points" für verschiedene Ansprechpartner-Positionen.
    2. Branchen-Selektion: Verarbeitet entweder alle in config.py definierten Branchen oder eine spezifische Auswahl, die über Kommandozeilen-Argumente übergeben wird.
    3. Dossier-Generierung: Für jede ausgewählte Branche wird generate_research_prompt aufgerufen und ein Dossier von der KI erstellt. Dieses wird zur Nachvollziehbarkeit als Textdatei im industries-Ordner gespeichert.
    4. Daten-Extraktion: Das generierte Dossier wird verwendet, um mit generate_extraction_prompt die strukturierten Daten (Zusammenfassung, Pain Points, Schlüsselbegriffe) zu extrahieren.
    5. Zusammenführung: Die extrahierten Daten werden zusammen mit den Referenzkunden aus der config.py in die Wissensbasis-Struktur eingefügt.
    6. Speichern: Die vollständige, angereicherte Wissensbasis wird am Ende des Prozesses in die finale YAML-Datei (marketing_wissen_final.yaml) geschrieben.

expand_knowledge_base.py

Hauptfunktion

Das Modul expand_knowledge_base.py dient dazu, eine bestehende Wissensbasis (marketing_wissen.yaml) gezielt zu erweitern. Es identifiziert, welche Branchen aus der zentralen Konfiguration (config.py) noch in der Wissensbasis fehlen, und generiert für diese fehlenden Branchen die entsprechenden Einträge. Der Prozess ist identisch mit dem von build_knowledge_base.py: Es wird ein KI-gestütztes Dossier erstellt, aus dem dann strukturierte Daten extrahiert und in die Wissensbasis integriert werden. Das Ergebnis wird in einer neuen, kompletten Datei (marketing_wissen_komplett.yaml) gespeichert.

Methodenbeschreibung

  • call_openai_with_retry(prompt, is_extraction=False, ...): Eine Wrapper-Funktion für OpenAI-API-Aufrufe mit Wiederholungslogik, die sowohl Freitext-Generierung als auch JSON-Extraktion unterstützt.

  • generate_research_prompt(branch_name): Erstellt einen Prompt für die KI, um ein Branchen-Dossier zu einem gegebenen Branchennamen zu erstellen.

  • generate_extraction_prompt(dossier_content): Erstellt einen Prompt, um aus einem generierten Dossier-Text strukturierte Daten (Zusammenfassung, Pain Points, Schlüsselbegriffe) im JSON-Format zu extrahieren.

  • main(branches_to_process=None): Die Hauptfunktion, die den Erweiterungsprozess steuert:

    1. Initialisierung: Lädt API-Schlüssel und die existierende Basis-Wissensdatei (marketing_wissen.yaml).
    2. Delta-Ermittlung: Vergleicht die Liste aller Branchen aus config.py mit den bereits in der Wissensbasis vorhandenen Branchen, um die Liste der zu bearbeitenden, fehlenden Branchen zu ermitteln.
    3. Gezielte Verarbeitung: Iteriert ausschließlich über die fehlenden Branchen (oder eine über Kommandozeilen-Argumente spezifizierte Teilmenge).
    4. Dossier-Generierung & Extraktion: Führt für jede neue Branche den zweistufigen Prozess aus: Zuerst wird das Dossier generiert und als Textdatei gespeichert, danach werden die strukturierten Daten extrahiert.
    5. Aktualisierung: Fügt die neu extrahierten Daten zur in-memory-Version der Wissensbasis hinzu.
    6. Speichern: Schreibt die erweiterte und nun vollständige Wissensbasis in eine neue Zieldatei (marketing_wissen_komplett.yaml).

extract_insights.py

Hauptfunktion

Das Modul extract_insights.py ist ein Werkzeug zur automatisierten Erstellung einer Wissensbasis aus unstrukturierten Word-Dokumenten (.docx). Es liest Branchenanalysen aus einem spezifizierten Ordner, sendet deren Inhalt an eine KI und extrahiert gezielt strukturierte Informationen wie operative "Pain Points", branchenspezifische Fachbegriffe und eine Management-Zusammenfassung. Diese extrahierten Daten werden in einer einzigen, strukturierten YAML-Datei (marketing_wissen_v1.yaml) zusammengefasst, die als Grundlage für weitere Marketing-Automatisierungen dient.

Methodenbeschreibung

  • call_openai_with_retry(prompt, ...): Eine robuste Wrapper-Funktion für OpenAI-API-Aufrufe, die eine Wiederholungslogik bei Fehlern implementiert.

  • read_docx_content(filepath): Eine Hilfsfunktion, die eine .docx-Datei einliest und deren gesamten Textinhalt, einschließlich Absätzen und Tabellen, als einzelnen String zurückgibt.

  • extract_yaml_from_response(response_text): Eine wichtige Bereinigungsfunktion, die sicherstellt, dass aus der oft mit Markdown-Formatierungen (```yaml ... ```) versehenen KI-Antwort nur der reine YAML-Code extrahiert wird, um Parsing-Fehler zu vermeiden.

  • generate_extraction_prompt(content, data_to_extract): Erstellt hochspezialisierte Prompts für die KI. Je nachdem, welche Information extrahiert werden soll (pain_points, key_terms oder summary), wird der KI eine andere Rolle und ein anderer Auftrag zugewiesen, um die Qualität und Relevanz der extrahierten Daten zu maximieren.

  • main(): Die Hauptfunktion, die den gesamten ETL-Prozess (Extract, Transform, Load) steuert:

    1. Initialisierung: Lädt die API-Schlüssel und prüft, ob der Quellordner mit den Word-Dokumenten existiert.
    2. Dokumenten-Loop: Iteriert über alle .docx-Dateien im Quellordner.
    3. Text-Extraktion: Liest den Inhalt jedes Dokuments mit read_docx_content.
    4. Iterative KI-Extraktion: Führt für jedes Dokument drei separate KI-Aufrufe durch (einen für "Pain Points", einen für "Key Terms" und einen für "Summary"), um die Genauigkeit zu erhöhen.
    5. Daten-Aggregation: Sammelt die extrahierten und geparsten YAML-Daten für jede Branche in einer zentralen knowledge_base-Struktur.
    6. Speichern: Schreibt die finale, aggregierte Wissensbasis in die marketing_wissen_v1.yaml-Datei.

generate_knowledge_base.py

Hauptfunktion

Das Modul generate_knowledge_base.py ist ein KI-gestütztes Skript zur Erstellung eines ersten Entwurfs für eine Marketing-Wissensbasis (marketing_wissen_entwurf.yaml). Es generiert zwei Kernbestandteile:

  1. Branchen-Pain-Points: Für eine vordefinierte Liste von Fokusbranchen werden die spezifischen operativen Herausforderungen im Außendienst identifiziert.
  2. Positions-Fokus: Für eine Liste von typischen Ansprechpartner-Positionen wird deren jeweiliger strategischer Fokus in Bezug auf Serviceprozesse formuliert.

Das Skript nutzt spezialisierte Prompts, um die KI in die Rolle eines Branchenexperten oder Vertriebs-Coaches zu versetzen und so qualitativ hochwertige, relevante Inhalte zu generieren. Das Ergebnis dient als Grundlage, die manuell überprüft und verfeinert werden kann.

Methodenbeschreibung

  • call_openai_with_retry(prompt, ...): Eine Standard-Wrapper-Funktion für OpenAI-API-Aufrufe mit integrierter Wiederholungslogik, um die Stabilität bei Netzwerk- oder API-Problemen zu gewährleisten.

  • generate_pain_points_prompt(branch_name): Erstellt einen detaillierten Prompt, der die KI anweist, sich in die Rolle eines Top-Strategieberaters zu versetzen. Der Prompt enthält einen "Chain of Thought"-Abschnitt, der die KI anleitet, über typische Aufgaben und Probleme im Außendienst der jeweiligen Branche nachzudenken, bevor sie die finalen "Pain Points" formuliert. Das Ausgabeformat wird strikt als YAML-Liste vorgegeben.

  • generate_position_focus_prompt(position_name): Erstellt einen Prompt, der die KI als erfahrenen B2B-Vertriebs-Coach positioniert. Die Aufgabe ist es, einen einzigen, prägnanten Satz zu formulieren, der den Hauptfokus einer bestimmten Ansprechpartner-Rolle (z.B. CFO, IT-Leiter) zusammenfasst.

  • main(): Die Hauptfunktion, die den gesamten Generierungsprozess steuert:

    1. Initialisierung: Lädt die API-Schlüssel und definiert die zu bearbeitenden Fokusbranchen und Positionen.
    2. Branchen-Verarbeitung: Iteriert durch die Liste der FOKUS_BRANCHEN, ruft für jede Branche generate_pain_points_prompt auf und sendet den Prompt an die KI. Die Antwort wird geparst und in der knowledge_base-Struktur gespeichert.
    3. Positions-Verarbeitung: Iteriert durch die Liste der POSITIONEN, generiert mit generate_position_focus_prompt den entsprechenden Prompt und lässt die KI den Fokus-Satz formulieren.
    4. Speichern: Schreibt die gesammelten Daten in die Zieldatei marketing_wissen_entwurf.yaml, die als Arbeitsgrundlage für die finale Wissensbasis dient.

6. Sub-System: Kontakt-Klassifizierung

Dies ist ein eigenständiges System innerhalb des Projekts, das sich ausschließlich mit der Analyse und Kategorisierung von Job-Titeln befasst.

contact_grouping.py (Klassifizierer)

Hauptfunktion

Das Modul contact_grouping.py ist für die automatische Klassifizierung von Jobtiteln in vordefinierte Abteilungen zuständig. Es nutzt eine mehrstufige Logik, die auf einer Kombination aus regelbasierten Mappings (exakte Treffer und Keyword-Regeln) und einer KI-gestützten Klassifizierung basiert. Das Ziel ist es, die Jobtitel von Kontakten aus einem Google Sheet (Matching_Positions) einer passenden Abteilung zuzuordnen, wobei auch der Unternehmensbranche-Kontext berücksichtigt wird.

Methodenbeschreibung

  • __init__(self): Initialisiert die ContactGrouper-Klasse und bereitet die internen Variablen für die Wissensbasis vor.

  • load_knowledge_base(self): Lädt die zuvor erstellten Wissensbasis-Dateien (exact_match_map.json und keyword_rules.json) in den Speicher. Diese Dateien enthalten die Regeln für die regelbasierte Zuordnung. Außerdem generiert es Beispiele für den KI-Prompt aus der geladenen Wissensbasis.

  • _load_json(self, file_path): Eine interne Hilfsmethode zum sicheren Laden und Parsen von JSON-Dateien.

  • _normalize_text(self, text): Eine interne Hilfsmethode zur Normalisierung von Texten (Kleinschreibung, Leerzeichen entfernen).

  • _generate_ai_examples(self): Generiert einen Teil des KI-Prompts, der Beispiele für typische Jobtitel pro Abteilung enthält. Dies hilft der KI, die Klassifizierungsaufgabe besser zu verstehen.

  • _find_best_match(self, job_title, company_branch): Die Kernlogik für die regelbasierte Zuordnung. Sie versucht zuerst einen exakten Match des job_title zu finden. Wenn dies fehlschlägt, werden Keyword-Regeln angewendet, wobei die company_branch zur Verfeinerung der Zuordnung genutzt wird. Prioritäten der Abteilungen werden bei mehreren Treffern berücksichtigt.

  • _get_ai_classification(self, contacts_to_classify): Sendet eine Liste von Jobtiteln, die nicht regelbasiert zugeordnet werden konnten, an die OpenAI API zur KI-gestützten Klassifizierung. Der Prompt enthält die gültigen Abteilungen und generierte Beispiele, um die KI-Antwort zu steuern. Die Ergebnisse werden als Dictionary zurückgegeben.

  • _append_learnings_to_source(self, gsh, new_mappings_df): Hängt neue, von der KI erfolgreich klassifizierte Jobtitel und deren Abteilungen an das Quell-Sheet (CRM_Jobtitles) an, um die Wissensbasis kontinuierlich zu erweitern.

  • process_contacts(self): Die Hauptmethode, die den gesamten Kontakt-Klassifizierungsprozess steuert:

    1. Lädt die Kontaktdaten aus dem TARGET_SHEET_NAME Google Sheet.
    2. Führt die regelbasierte Zuordnung (_find_best_match) für alle Jobtitel durch.
    3. Identifiziert Jobtitel, die nicht regelbasiert zugeordnet werden konnten (DEFAULT_DEPARTMENT).
    4. Sendet diese unklassifizierten Jobtitel in Batches an die KI (_get_ai_classification) zur weiteren Klassifizierung.
    5. Aktualisiert die Department-Spalte im DataFrame mit den KI-Ergebnissen.
    6. Hängt neue KI-Erkenntnisse an das Lern-Quell-Sheet an (_append_learnings_to_source).
    7. Schreibt die finalen, klassifizierten Daten zurück in das TARGET_SHEET_NAME Google Sheet.

knowledge_base_builder.py (Wissensbasis-Ersteller für Klassifizierung)

Hauptfunktion

Das Modul knowledge_base_builder.py ist dafür verantwortlich, eine Wissensbasis für die automatische Zuordnung von Jobtiteln zu Abteilungen zu erstellen. Es verarbeitet eine Liste von Jobtiteln und deren zugehörigen Abteilungen und Branchen aus einem Google Sheet. Das Skript generiert zwei Haupt-Artefakte:

  1. Exaktes Mapping (exact_match_map.json): Eine einfache Zuordnung von exakten, normalisierten Jobtiteln zu ihrer dominantesten Abteilung.
  2. Keyword-Regeln (keyword_rules.json): Eine Sammlung von Regeln, die Schlüsselwörter pro Abteilung identifiziert und optional branchenspezifische Anforderungen für die Zuordnung hinzufügen, basierend auf der Häufigkeit von Branchen innerhalb der Abteilung.

Das Ziel ist es, die automatische und präzise Klassifizierung neuer, unbekannter Jobtitel zu ermöglichen.

Methodenbeschreibung

  • setup_logging(): Eine Hilfsfunktion, die das Logging für das Skript konfiguriert und sicherstellt, dass alle Ausgaben sowohl in eine Datei als auch in die Konsole geschrieben werden.

  • build_knowledge_base(): Dies ist die Hauptfunktion des Moduls, die den gesamten Prozess der Wissensbasiserstellung orchestriert:

    1. Daten laden: Stellt eine Verbindung zum konfigurierten Google Sheet (definiert in SOURCE_SHEET_NAME) her und lädt die Daten in einen Pandas DataFrame.
    2. Datenbereinigung: Entfernt Zeilen mit fehlenden oder leeren Jobtiteln/Abteilungen und normalisiert die Jobtitel für konsistente Vergleiche.
    3. Exaktes Mapping: Gruppiert die Jobtitel nach ihrer normalisierten Form und ermittelt die am häufigsten (modal) vorkommende Abteilung, um eine direkte 1:1-Zuordnung zu erstellen. Das Ergebnis wird als JSON-Datei (exact_match_map.json) gespeichert.
    4. Keyword-Regeln erstellen: Für jede Abteilung werden die häufigsten und aussagekräftigsten Schlüsselwörter aus den zugehörigen Jobtiteln extrahiert. Dabei werden eine vordefinierte Liste von Stoppwörtern und generischen Begriffen ignoriert. Diese Regeln erhalten eine Priorität basierend auf DEPARTMENT_PRIORITIES.
    5. Branchenspezifische Anpassung: Optional wird geprüft, ob eine Abteilung stark mit einer bestimmten Branchengruppe (definiert in BRANCH_GROUP_RULES) korreliert. Wenn eine hohe Spezifität (> BRANCH_SPECIFICITY_THRESHOLD) und genügend Datenpunkte vorhanden sind, wird diese Branchenanforderung zur Keyword-Rule hinzugefügt. Das Ergebnis wird als JSON-Datei (keyword_rules.json) gespeichert.
    6. Fehlerbehandlung: Robuste Fehlerbehandlung für Datei-I/O und Datenladen aus Google Sheets.

7. Standalone-Werkzeuge

Dieser Bereich enthält Skripte, die als eigenständige Werkzeuge für spezifische Aufgaben konzipiert sind.

company_deduplicator.py (Duplikats-Check)

Hauptfunktion

Das Skript company_deduplicator.py (ehemals duplicate_checker_old.py) ist ein spezialisiertes Werkzeug zur Identifizierung von potenziellen Unternehmens-Duplikaten. Es operiert in zwei Modi:

  1. Externer Vergleich: Identifiziert Duplikate zwischen einer externen Liste (Matching_Accounts) und der internen CRM-Liste (CRM_Accounts). Dies ist die ursprüngliche Funktionalität.
  2. Interne Deduplizierung: Findet Duplikate innerhalb der CRM_Accounts-Liste, gruppiert diese und markiert sie zur weiteren Bearbeitung.

Es verwendet einen gewichteten, heuristischen Algorithmus, um Ähnlichkeiten zu bewerten und nutzt bekannte Unternehmenshierarchien (Parent Account), um Falsch-Positive zu reduzieren.

Meeting Assistant (Transcription Tool)

Ein lokaler Micro-Service zur Transkription und Analyse von Audio-Dateien (Meetings, Calls, Interviews). Nutzt Gemini 2.0 Flash für kostengünstige, hochqualitative Ergebnisse.

  • Dokumentation: TRANSCRIPTION_TOOL.md
  • Funktionen: Upload (MP3/WAV), Automatisches Chunking (FFmpeg), Transkription mit Timestamps.
  • Zugriff: Über das Dashboard /tr/.

import_competitive_radar.py (Competitor Import)

Hauptfunktion

Dieses Skript dient dem einmaligen Import von Wettbewerbsanalyse-Daten aus einer JSON-Datei in die Notion-Datenbanken. Es liest eine spezifische JSON-Datei (analysis_robo-planet.de-4.json), die die Ergebnisse einer externen Analyse enthält, und legt die entsprechenden Einträge für Unternehmen, Produkte und deren Verknüpfungen in Notion an. Das Skript ist zustandsbewusst, d.h. es prüft vor dem Anlegen, ob ein Eintrag bereits existiert, um Duplikate zu vermeiden.

Neue Features (Interne Deduplizierung)

  • Zwei-Modi-Betrieb: Das Skript fragt beim Start interaktiv ab, ob ein externer Vergleich oder eine interne Deduplizierung durchgeführt werden soll.
  • Gruppierung & ID-Zuweisung: Im internen Modus werden gefundene Duplikatspaare zu Clustern zusammengefasst (z.B. wenn A=B und B=C, dann ist A,B,C eine Gruppe). Jede Gruppe erhält eine eindeutige ID (z.B. Dup_0001), die in eine neue Spalte Duplicate_ID im CRM_Accounts-Sheet geschrieben wird.
  • Nutzung von Unternehmenshierarchien: Das Skript liest die Spalte Parent Account aus dem CRM_Accounts-Sheet. Bekannte Eltern-Kind-Beziehungen werden automatisch von der Duplikatsprüfung ausgeschlossen, was die Genauigkeit erheblich verbessert.
  • Handlungsempfehlungen: Findet das Skript eine Duplikatsgruppe, in der bei keinem der Mitglieder ein Parent Account gepflegt ist, wird dies in einer neuen Spalte Duplicate_Hint vermerkt. Dies dient als Hinweis, dass hier möglicherweise eine Hierarchie im CRM nachgepflegt werden sollte.

Abhängigkeiten

  • pandas: Zur Datenmanipulation und -analyse.
  • thefuzz: Für Fuzzy-String-Vergleiche zur Bewertung der Namensähnlichkeit.
  • gspread, oauth2client: Für die Interaktion mit der Google Sheets API.
  • Lokale Module:
    • helpers.py: Stellt Normalisierungsfunktionen (normalize_company_name, simple_normalize_url) und eine optionale Web-Suche (serp_website_lookup) bereit.
    • config.py: Zentralisiert Konfigurationswerte und API-Schlüssel.
    • google_sheet_handler.py: Kapselt die Logik für den Zugriff auf Google Sheets.

Konfiguration

Die Logik des Skripts wird durch mehrere Konstanten am Anfang der Datei gesteuert:

  • Sheet-Namen: CRM_SHEET_NAME und MATCHING_SHEET_NAME.
  • Score-Schwellenwerte: SCORE_THRESHOLD (Standard: 80) und SCORE_THRESHOLD_WEAK (95), ein strengerer Wert für Treffer ohne starke Indikatoren wie Domain- oder Standortübereinstimmung.
  • Penalties: CITY_MISMATCH_PENALTY (30) und COUNTRY_MISMATCH_PENALTY (40) werden vom Score abgezogen, wenn Standorte voneinander abweichen.
  • Prefiltering: PREFILTER_MIN_PARTIAL (70) und PREFILTER_LIMIT (30) zur Vorauswahl potenzieller Kandidaten, um die Performance zu verbessern.
  • Stop-Wörter: STOP_TOKENS_BASE und CITY_TOKENS (dynamisch generiert) enthalten Begriffe, die bei Namensvergleichen ignoriert werden, um die Signalqualität zu erhöhen.

Ablauf-Logik (Gekürzt)

  1. Modus-Auswahl: Das Skript fragt den Benutzer nach dem gewünschten Modus (Extern vs. Intern).
  2. Initialisierung & Daten laden: Richtet das Logging ein und lädt die relevanten Google Sheets. Im internen Modus wird auch die Parent Account-Spalte geladen.
  3. Normalisierung & Index-Erstellung: Unternehmensnamen, Domains, Orte und Parent Accounts werden standardisiert. Zur Optimierung der Suche werden "Blocking"-Indizes (z.B. für Domains und Namens-Tokens) erstellt.
  4. Matching-Prozess:
    • Extern: Jeder Eintrag aus Matching_Accounts wird mit Kandidaten aus CRM_Accounts verglichen.
    • Intern: Jeder Eintrag aus CRM_Accounts wird mit nachfolgenden Kandidaten aus derselben Liste verglichen, wobei bekannte Hierarchien übersprungen werden.
  5. Scoring & Gruppierung: Kandidatenpaare werden bewertet. Im internen Modus werden Paare über dem Schwellenwert zu Gruppen zusammengefasst.
  6. Daten zurückschreiben:
    • Extern: Die Ergebnisse (Match, Score) werden in das Matching_Accounts-Sheet geschrieben.
    • Intern: Die Duplicate_ID und Duplicate_Hint werden in neue Spalten im CRM_Accounts-Sheet geschrieben.

To-Dos & Nächste Schritte

  • Scoring-Schwellenwert erhöhen: Der SCORE_THRESHOLD von 80 ist für die interne Deduplizierung zu niedrig und sollte auf 95 oder höher angehoben werden, um Falsch-Positive zu reduzieren.
  • Stop-Wort-Liste erweitern: Die STOP_TOKENS_BASE-Liste um generische Branchenbegriffe wie 'energy', 'services', 'group', 'solutions' etc. erweitern.
  • Scoring-Logik anpassen: Die Gewichtung sollte angepasst werden, sodass eine hohe Namensähnlichkeit in Kombination mit einem Standort-Match stärker bewertet wird.
  • Debugging-Log verbessern: Die Log-Ausgabe für gefundene Paare sollte die komplette Scoring-Zusammensetzung ausgeben, um die Analyse von Ergebnissen zu erleithert.

8. Projekt-Fundament

Diese Module stellen grundlegende Funktionen und Konfigurationen für das gesamte Projekt bereit.

config.py (Zentrale Konfiguration)

Hauptfunktion

Das Modul config.py dient als zentrale Konfigurationsdatei für das gesamte Projekt "Automatisierte Unternehmensbewertung". Es bündelt alle globalen Einstellungen, Dateipfade, API-Schlüssel-Pfade, Schwellenwerte und Mappings, die von verschiedenen Modulen im Projekt verwendet werden. Durch die Zentralisierung der Konfiguration wird die Wartbarkeit und Anpassbarkeit des Systems erheblich verbessert.

Methodenbeschreibung

  • normalize_for_mapping(text): Eine Hilfsfunktion, die einen String aggressiv für Mapping-Zwecke normalisiert, indem er in Kleinbuchstaben umgewandelt, getrimmt und alle nicht-alphanumerischen Zeichen entfernt werden. Diese Funktion wird intern von der Config-Klasse verwendet.

  • Config Klasse:

    • Attribute: Enthält statische Attribute wie VERSION, LANG, SHEET_URL, MAX_RETRIES, RETRY_DELAY, REQUEST_TIMEOUT, SIMILARITY_THRESHOLD, DEBUG, WIKIPEDIA_SEARCH_RESULTS, HTML_PARSER, TOKEN_MODEL, USER_AGENT.
    • Batching & Parallelisierung: Konfigurationen für die Batch-Verarbeitung und Parallelisierung, z.B. PROCESSING_BATCH_SIZE, OPENAI_BATCH_SIZE_LIMIT, MAX_SCRAPING_WORKERS.
    • Plausibilitäts-Schwellenwerte: Definiert numerische Schwellenwerte für Plausibilitätsprüfungen von Umsatz- und Mitarbeiterzahlen, z.B. PLAUSI_UMSATZ_MIN_WARNUNG, PLAUSI_RATIO_UMSATZ_PRO_MA_MIN.
    • Länder-Codes Mapping (COUNTRY_CODE_MAP): Ein Dictionary, das D365-Ländercodes in die im Google Sheet verwendeten Langformen übersetzt.
    • Branchen-Gruppen Mapping (BRANCH_GROUP_MAPPING): Eine "Single Source of Truth" für alle Branchen, angereichert mit Definitionen, Beispielen und D365-Branch-Details.
    • API-Schlüssel (API_KEYS): Ein Dictionary, das die geladenen API-Schlüssel speichert.
    • load_api_keys() (Klassenmethode): Lädt API-Schlüssel aus den konfigurierten Dateipfaden (API_KEY_FILE, SERP_API_KEY_FILE, GENDERIZE_API_KEY_FILE) und setzt den OpenAI API-Schlüssel global.
    • _load_key_from_file(filepath) (Statische Methode): Eine interne Hilfsfunktion zum sicheren Laden eines API-Schlüssels aus einer angegebenen Datei.

  • COLUMN_ORDER: Eine globale Liste, die die exakte und garantierte Reihenfolge aller Spalten im Google Sheet definiert. Dies dient als "Single Source of Truth" für alle Index-Berechnungen.

  • COLUMN_MAP: Ein globales Dictionary, das detaillierte Mappings für jede Spalte im Google Sheet bereitstellt, einschließlich des Spaltentitels (z.B. "A", "B") und des 0-basierten Index.

  • DEALFRONT AUTOMATION CONFIGURATION: Spezifische Konfigurationen für die Dealfront-Automatisierung, einschließlich DEALFRONT_CREDENTIALS_FILE, DEALFRONT_LOGIN_URL, DEALFRONT_TARGET_URL und TARGET_SEARCH_NAME.

helpers.py (Globaler Werkzeugkasten)

Diese Datei enthält eine Sammlung von globalen, wiederverwendbaren Hilfsfunktionen, die in verschiedenen Modulen des Projekts verwendet werden.

Decorators

retry_on_failure(func)
  • Zweck: Ein Decorator, der eine Funktion bei bestimmten, temporären Fehlern (z.B. Netzwerkprobleme, API-Rate-Limits) automatisch mehrmals ausführt. Er verwendet eine exponentielle Backoff-Strategie, um die Wartezeit zwischen den Versuchen zu erhöhen.
  • Input: Eine Funktion, die dekoriert werden soll.
  • Output: Das Ergebnis der dekorierten Funktion oder löst eine Ausnahme aus, wenn alle Wiederholungsversuche fehlschlagen.

Logging & Token Counting

token_count(text, model=None)
  • Zweck: Zählt die Anzahl der Tokens in einem gegebenen Text. Verwendet die tiktoken-Bibliothek für eine genaue Zählung, falls verfügbar, andernfalls schätzt sie die Anzahl basierend auf Leerzeichen.
  • Input: text (der zu analysierende String), model (optional, das zu verwendende KI-Modell).
  • Output: Eine Ganzzahl, die die Anzahl der Tokens darstellt.
create_log_filename(mode)
  • Zweck: Erstellt einen standardisierten, zeitgestempelten Dateinamen für Log-Dateien.
  • Input: mode (ein String, der den aktuellen Ausführungsmodus beschreibt, z.B. 'full_run').
  • Output: Ein String, der den vollständigen Pfad zur Log-Datei enthält (z.B. Log/2025-11-07_10-30_v221_Modus-full_run.txt).

Text-, String- & URL-Utilities

simple_normalize_url(url)
  • Zweck: Bereinigt und normalisiert eine URL auf ihre Kern-Domain (z.B. https://www.beispiel.de/path -> beispiel.de).
  • Input: url (ein String mit einer URL).
  • Output: Ein normalisierter Domain-String oder "k.A." bei ungültiger Eingabe.
normalize_string(s)
  • Zweck: Standardisiert einen String, indem Umlaute (ä -> ae) und gängige Sonderzeichen ersetzt werden.
  • Input: s (ein beliebiger String).
  • Output: Der normalisierte String.
clean_text(text)
  • Zweck: Bereinigt einen Text von unerwünschten Artefakten, die typischerweise beim Scrapen von Websites oder Wikipedia auftreten (z.B. [1], [Bearbeiten], überflüssige Leerzeichen).
  • Input: text (ein String).
  • Output: Der bereinigte Text.
normalize_company_name(name)
  • Zweck: Normalisiert einen Firmennamen, indem gängige Rechtsformzusätze (GmbH, AG, etc.) und andere generische Begriffe entfernt werden, um Vergleiche zu erleichtern.
  • Input: name (ein Firmenname als String).
  • Output: Der normalisierte Firmenname in Kleinbuchstaben.
extract_numeric_value(raw_value, is_umsatz=False)
  • Zweck: Extrahiert und normalisiert einen numerischen Wert aus einem unstrukturierten String. Kann Einheiten wie "Mio.", "Mrd." oder "Tsd." interpretieren und in einen Basiswert umrechnen.
  • Input: raw_value (ein String, z.B. "ca. 250 Mio. EUR"), is_umsatz (ein Flag, das die Umrechnung für Umsätze steuert, z.B. Rückgabe in Millionen).
  • Output: Ein String mit der normalisierten Zahl (z.B. "250") oder "k.A.".

API Wrappers & Externe Dienste

call_openai_chat(...)
  • Zweck: Eine zentrale Wrapper-Funktion für Aufrufe an die OpenAI Chat-API. Kapselt die Authentifizierung, die Fehlerbehandlung und den eigentlichen API-Aufruf.
  • Input: prompt (der an die KI gesendete Text), temperature (steuert die Kreativität der Antwort), model (das zu verwendende KI-Modell).
  • Output: Der von der KI generierte Antwort-Text als String.
summarize_website_content(raw_text, company_name)
  • Zweck: Nutzt die KI, um den Rohtext einer Website zu analysieren und eine strukturierte Zusammenfassung des Geschäftsmodells und des Potenzials für Field Service Management (FSM) zu erstellen.
  • Input: raw_text (der Inhalt der Website), company_name (Name des Unternehmens).
  • Output: Ein formatierter String, der das Geschäftsmodell, das FSM-Potenzial und Belegsätze enthält.
evaluate_branche_chatgpt(...)
  • Zweck: Führt eine KI-basierte Brancheneinstufung für ein einzelnes Unternehmen durch. Sendet ein Unternehmensprofil und ein vordefiniertes Branchenschema an die KI.
  • Input: company_name, website_summary, wiki_absatz.
  • Output: Ein Dictionary mit der vorgeschlagenen "Branche", "Konfidenz" und "Begruendung".
evaluate_branches_batch(companies_data)
  • Zweck: Führt die Brancheneinstufung für eine Liste von Unternehmen in einem einzigen API-Aufruf durch, um die Effizienz zu steigern.
  • Input: companies_data (eine Liste von Dictionaries, die Unternehmensprofile enthalten).
  • Output: Eine Liste von Dictionaries mit den Ergebnissen für jedes Unternehmen.
generate_fsm_pitch(...)
  • Zweck: Generiert einen hochpersonalisierten, einleitenden Satz für eine Marketing-E-Mail (FSM-Pitch), basierend auf den gesammelten Unternehmensdaten.
  • Input: Diverse Unternehmensdaten wie Name, Branche, Zusammenfassungen und Mitarbeiter-/Technikerzahlen.
  • Output: Ein einzelner, prägnanter Satz als String.
serp_website_lookup(company_name)
  • Zweck: Verwendet die SerpAPI (Google-Suche), um die offizielle Website eines Unternehmens zu finden. Filtert dabei unzuverlässige Quellen wie soziale Medien oder Nachrichtenportale heraus.
  • Input: company_name.
  • Output: Die normalisierte URL der gefundenen Website oder "k.A.".
search_linkedin_contacts(...)
  • Zweck: Führt eine gezielte Google-Suche über die SerpAPI durch, um LinkedIn-Profile von Mitarbeitern in bestimmten Positionen (z.B. "Serviceleiter") bei einem Unternehmen zu finden.
  • Input: company_name, website, position_query (z.B. "Leiter Kundendienst"), crm_kurzform.
  • Output: Eine Liste von Dictionaries, die die gefundenen Kontakte mit Namen, Position und LinkedIn-URL enthalten.

Website Scraping & Validierung

get_website_raw(url, ...)
  • Zweck: Lädt den reinen Textinhalt von einer Webseite. Die Funktion ist gehärtet, um mit verschiedenen Fehlern (SSL, Timeout, Connection Errors) umzugehen und versucht, Cookie-Banner intelligent zu entfernen.
  • Input: url (die zu scrapende URL).
  • Output: Der extrahierte Text der Website als String oder ein Fehlerhinweis (z.B. "k.A. (Timeout)").
is_valid_wikipedia_article_url(url)
  • Zweck: Überprüft, ob eine gegebene URL tatsächlich auf einen existierenden Wikipedia-Artikel verweist und nicht auf eine "Seite existiert nicht"-Seite.
  • Input: url (die zu prüfende Wikipedia-URL).
  • Output: True, wenn der Artikel existiert, andernfalls False.

9. Konsolidierte Architektur & Web-Anwendungen

Um die verschiedenen Werkzeuge zugänglicher und wartbarer zu machen, wurden der B2B Marketing Assistant und das Market Intelligence Tool in einer einzigen, Docker-basierten Architektur konsolidiert. Diese neue Struktur bietet einen zentralen, passwortgeschützten Einstiegspunkt und optimiert sowohl die Entwicklung als auch den Betrieb.

Architektur im Überblick

Die konsolidierte Lösung besteht aus fünf Haupt-Containern, die von docker-compose.yml gesteuert werden:

  1. Proxy (Nginx):

    • Zentraler Einstiegspunkt: Der Proxy lauscht auf Port 8090 und ist der einzige von außen erreichbare Punkt.

    • Passwortschutz: Sichert den gesamten Zugriff mit HTTP Basic Authentication (Benutzer: admin, Passwort: gemini).

    • Routing: Leitet Anfragen an die richtigen Anwendungs-Container weiter:

      • / -> Dashboard (Landingpage)

      • /b2b/ -> B2B Marketing Assistant

      • /market/ -> Market Intelligence Tool

      • /gtm/ -> GTM Architect

  2. Dashboard:

    • Eine simple Nginx-Instanz, die eine statische HTML-Seite (dashboard/index.html) ausliefert.

    • Diese Seite dient als Landingpage und verlinkt auf die drei untergeordneten Anwendungen.

  3. B2B Marketing Assistant (b2b-app):

    • Ein Docker-Container, der das React-Frontend und die dazugehörige Node.js/Python-Backend-Logik enthält.

    • Erreichbar über das Unterverzeichnis /b2b/.

  4. Market Intelligence (market-frontend & market-backend):

    • Diese Anwendung bleibt in Frontend- und Backend-Container aufgeteilt, wird aber nun ebenfalls über den zentralen Proxy unter /market/ geroutet.

  5. GTM Architect (gtm-app):

    • Ein Docker-Container, der das React-Frontend und die dazugehörige Node.js/Python-Backend-Logik kapselt.
    • Erreichbar über das Unterverzeichnis /gtm/.

Vorteile dieser Architektur

  • Zentraler & Sicherer Zugriff: Nur ein Port muss freigegeben werden, und der Zugang ist einheitlich geschützt.

  • Einfache Skalierbarkeit: Die einzelnen Komponenten sind voneinander entkoppelt und können unabhängig voneinander aktualisiert werden.

  • Optimierte Builds: Durch die Verwendung von .dockerignore und Python-Basis-Images werden die Build-Zeiten verkürzt und die Image-Größen reduziert.

  • Effiziente Entwicklung: Die Python-Skripte (*.py) werden als Volumes eingebunden ("Sideloading"). Änderungen am Python-Code erfordern daher keinen kompletten Docker-Rebuild, sondern nur einen Neustart des Containers.

10. Deployment & Entwicklung

Produktions-Deployment

Für den dauerhaften Betrieb auf einem Server (z.B. Synology Diskstation) wird die gesamte Anwendung mit einem einzigen Befehl gestartet.

  1. Stellen Sie sicher, dass Docker und Docker Compose installiert sind.

  2. Navigieren Sie in das Hauptverzeichnis des Projekts.

  3. Starten Sie den gesamten Stack:

    
docker-compose up -d --build

    Der --build-Parameter ist nur beim ersten Start oder nach Änderungen an den Dockerfiles oder Frontend-Komponenten (z.B. App.tsx) notwendig.

Zugriff

  • Marketing & Intelligence Hub: Die zentrale Landingpage ist unter http://<Server-IP>:8090 erreichbar.

  • B2B Marketing Assistant: Direkt erreichbar unter http://<Server-IP>:8090/b2b/.

  • Market Intelligence Tool: Direkt erreichbar unter http://<Server-IP>:8090/market/.

  • GTM Architect: Direkt erreichbar unter http://<Server-IP>:8090/gtm/.

Entwicklung & Sideloading

Dank des Volume-Mountings für die Python-Skripte ist die Entwicklung sehr effizient:

  1. Ändern Sie den Python-Code in b2b_marketing_orchestrator.py, market_intel_orchestrator.py oder gtm_architect_orchestrator.py.

  2. Starten Sie den betroffenen Container neu, damit die Änderungen wirksam werden:

    
# Für den B2B Assistant

docker-compose restart b2b-app



# Für das Market Intelligence Backend

docker-compose restart market-backend

# Für den GTM Architect
docker-compose restart gtm-app

Ein zeitaufwändiger docker-compose build ist nur bei Änderungen am Frontend-Code, an den Dockerfilen oder an den requirements.txt/package.json-Dateien notwendig.

API-Authentifizierung (Company Explorer)

Der company-explorer Dienst erfordert nun eine HTTP Basic Authentication für alle API-Endpunkte (/api/*). Dies dient dem internen Zugriffsschutz.

Um den Dienst zu nutzen, müssen folgende Umgebungsvariablen in der docker-compose.yml (oder in einer .env-Datei, wenn diese konfiguriert ist) gesetzt werden:

services:
  company-explorer:
    # ... andere Konfigurationen ...
    environment:
      API_USER: "IhrBenutzername" # Legen Sie hier Ihren gewünschten Benutzernamen fest
      API_PASSWORD: "IhrSicheresPasswort" # Legen Sie hier Ihr gewünschtes sicheres Passwort fest

Stellen Sie sicher, dass Sie diese Werte vor dem Start des company-explorer Dienstes festlegen. Nach dem Aktualisieren der docker-compose.yml müssen Sie den Dienst neu starten:

docker-compose restart company-explorer

11. Market Intelligence: Funktionsweise v2.2 (Update Dez. 2025)

Das "Market Intelligence Tool" wurde in Version 2.2 massiv überarbeitet, um robuster und präziser zu arbeiten.

Neue Features

  1. Robuste Audit-Strategie (Graceful Fallback):

    • Bisher führten blockierte Webseiten (403 Forbidden, Timeouts) zum Abbruch der Analyse.
    • Neu: Wenn der Scraper blockiert wird, schaltet das System automatisch in einen "Digital Footprint Mode". Es analysiert dann Snippets aus der Google-Suche (Tech-Stack-Spuren, Job-Postings, News), um trotzdem eine Bewertung abzugeben. Der Status wird transparent als "Website Access Denied - Relying on External Signals" gekennzeichnet.

  2. Präzisere Lookalike-Suche:

    • Die KI wurde neu instruiert, strikt zwischen dem "Jäger" (Context/Hochgeladener Report) und der "Beute" (Referenzkunde/URL) zu unterscheiden.
    • Die Suche nach "Lookalikes" basiert nun explizit auf dem Geschäftszweck des Referenzkunden, nicht auf dem Angebot des Nutzers.

  3. Erweiterter Report:

    • Der finale Report enthält nun drei neue, strategische Sektionen:
      • Search Strategy ICP: Detaillierte Beschreibung des idealen Kundenprofils basierend auf der Analyse.
      • Digital Signals: Konkrete digitale Indikatoren (z.B. "Nutzt MS Teams", "Sucht Projektleiter"), auf die geachtet wurde.
      • Target Pages: Eine Liste der wichtigsten Unterseiten auf der Ziel-Website (z.B. Karriere, Über uns) für die Recherche.

Technische Verbesserungen

  • URL Auto-Fix: URLs ohne https:// werden automatisch korrigiert.
  • Modern User-Agent: Der Scraper gibt sich als moderner Chrome-Browser aus, um Blockaden zu minimieren.
  • Frontend-Integration: Die neuen Datenfelder werden nahtlos im React-Frontend und im Markdown-Export angezeigt.

12. Infrastructure & Operations

DNS & Connectivity

Um eine stabile Erreichbarkeit der Dienste zu gewährleisten, wurde eine Docker-basierte DynDNS-Lösung implementiert.

  • DuckDNS & Monitoring Setup: Dokumentation zur Einrichtung des duckdns Updaters und des dns-monitor Sidecars, um Verbindungsprobleme und Caching-Fehler zu beheben.

13. Funktionsweise im Detail

Analyse-Tiefe der "Digital Signals" im Market Intelligence Tool

Die Identifizierung von digitalen Signalen bei Zielunternehmen erfolgt über einen pragmatischen, zweistufigen Prozess, um ein Gleichgewicht zwischen analytischer Tiefe und Performance zu gewährleisten:

  1. Vollständiges Parsen der Unternehmens-Homepage:

    • Die Haupt-URL des zu analysierenden Unternehmens wird einmalig vollständig gecrawlt. Der extrahierte Text (homepage_text) dient dem Sprachmodell als grundlegender Kontext, um das Geschäftsmodell und die Kernaussagen des Unternehmens zu verstehen.

  2. Analyse von Suchergebnis-Snippets für Signale:

    • Für die gezielte Suche nach spezifischen Signalen (z.B. eingesetzte Konkurrenzprodukte, offene Stellen, strategische Initiativen) wird die SerpAPI (Google-Suche) genutzt.
    • Wichtig: Die in den Suchergebnissen gefundenen Ziel-URLs werden nicht erneut besucht und geparst. Stattdessen werden ausschließlich der Titel (title) und der von der Suchmaschine generierte Textschnipsel (snippet) als "Beweismittel" (evidence) an das Sprachmodell übergeben.
    • Dieser Ansatz ist ein bewusster Kompromiss: Er ist extrem schnell und kosteneffizient, da er aufwändiges Crawling vermeidet. Die Snippets sind in der Regel aussagekräftig genug, um das Vorhandensein eines Signals mit hoher Wahrscheinlichkeit zu validieren.

Zukünftige Erweiterung: Detaillierte Analyse von Stellenausschreibungen

Als eine zukünftige, sehr wertvolle Erweiterung ist die detaillierte, automatisierte Analyse von Stellenausschreibungen vorgemerkt.

  • Strategischer Mehrwert:
    • Einblick in die Wirtschaftslage: Die Art und Anzahl der offenen Stellen (z.B. Vertrieb vs. Entwicklung vs. Verwaltung) kann Aufschluss über die aktuelle Wachstums-, Konsolidierungs- oder Krisenphase eines Unternehmens geben.
    • IT-Landkarte & Tech-Stack: Insbesondere IT-Stellenanzeigen sind eine Goldgrube für Technographic-Daten. Sie listen oft explizit die eingesetzten Programmiersprachen, Frameworks, Datenbanken, ERP-Systeme (z.B. SAP, D365) und Cloud-Anbieter auf. Dies erlaubt eine einzigartig detaillierte Erstellung der "IT-Landkarte" eines Zielunternehmens.
  • Herausforderung:
    • Der technische Aufwand für ein robustes System, das Karriereseiten findet, die verschiedenen Job-Portale parst und die relevanten Informationen extrahiert, ist immens.
  • Status:
    • Diese Erweiterung wird für eine spätere Entwicklungsphase vorgemerkt und sollte aufgrund der Komplexität in einem klar abgegrenzten, überschaubaren Rahmen umgesetzt werden.
Reference in New Issue View Git Blame Copy Permalink