Table of Contents

• Projekt: Automatisierte Unternehmensbewertung & Lead-Generierung v2.2.1
• 1. Projektübersicht & Architektur
• Architektur im Überblick
• 2. Steuerung & Ausführung (Control & Execution)
• app.py (API Server)
• Hauptfunktion
• Methodenbeschreibung
• brancheneinstufung2.py (Orchestrator / Kommandozeile)
• Hauptfunktion
• Wichtige Funktionen/Methoden
• 3. Kern-Produktionslinie: Datenanreicherung
• data_processor.py (Der "Motor")
• Hauptfunktion
• Methodenbeschreibung
• Spezialisten-Module
• google_sheet_handler.py (Spezialist für Google Sheets)
• Hauptfunktion
• Methodenbeschreibung
• wikipedia_scraper.py (Spezialist für Wikipedia)
• Hauptfunktion
• Methodenbeschreibung
• sync_manager.py (Spezialist für D365-Abgleich)
• Hauptfunktion
• Methodenbeschreibung
• 4. Marketing-Produktionslinie: Content-Erstellung
• generate_marketing_text.py (Marketing Text Engine)
• Hauptfunktion
• Methodenbeschreibung
• 5. ETL-Pipeline: Erstellung der Marketing-Wissensbasis
• build_knowledge_base.py
• expand_knowledge_base.py
• extract_insights.py
• generate_knowledge_base.py
• 6. Sub-System: Kontakt-Klassifizierung
• contact_grouping.py (Klassifizierer)
• Hauptfunktion
• Methodenbeschreibung
• knowledge_base_builder.py (Wissensbasis-Ersteller für Klassifizierung)
• Hauptfunktion
• 7. Standalone-Werkzeuge
• duplicate_checker_old.py (Duplikats-Check)
• Hauptfunktion
• Ablauf-Logik
• 8. Projekt-Fundament
• config.py (Zentrale Konfiguration)
• Hauptfunktion
• Methodenbeschreibung
• helpers.py (Globaler Werkzeugkasten)
• Hauptfunktion
• Methodenbeschreibung (Auszug)

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
    └── duplicate_checker_old.py (Eigenständiger Duplikats-Check)

VII. 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.

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).
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.
4. Modus-Dispatching: Eine if/elif/else-Struktur leitet die Ausführung an die passende Methode weiter (z.B. sync, full_run, reeval, dynamische Aufrufe von DataProcessor-Methoden).
5. Fehlerbehandlung und Logging: Das gesamte Skript ist von einem try...except...finally-Block umschlossen, der Fehler abfängt und protokolliert.

---

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.

Methodenbeschreibung

• setup(): Initialisiert den DataProcessor, lädt das Branchenschema und das ML-Modell.
• process_rows_sequentially(...): Führt den vollständigen, schrittweisen Anreicherungsprozess für einen definierten Bereich von Zeilen aus.
• process_reevaluation_rows(...): Führt den Anreicherungsprozess für Zeilen aus, die manuell für eine Neubewertung markiert wurden.
• process_website_scraping(...): Führt einen Batch-Prozess ausschließlich für das Scrapen von Websites durch.
• process_summarize_website(...): Führt einen Batch-Prozess zur Zusammenfassung von Website-Rohtexten mittels KI durch.
• process_branch_batch(...) / reclassify_all_branches(...): Führt eine (Neu-)Bewertung der Branchenzugehörigkeit im Batch-Verfahren durch.
• process_wiki_verify(...): Verifiziert in einem Batch-Prozess, ob ein Wikipedia-Artikel thematisch zum Unternehmen passt.
• process_find_wiki_serp(...): Sucht über eine Google-Suche nach einem passenden Wikipedia-Artikel für große Unternehmen.
• process_contact_search(...): Führt eine Suche nach LinkedIn-Kontakten für bestimmte Positionen durch.
• train_technician_model(): Trainiert ein Machine-Learning-Modell zur Vorhersage von Servicetechniker-Anzahlen.
• process_predict_technicians(...): Wendet das trainierte ML-Modell auf neue Zeilen an.

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. Es abstrahiert die Komplexität der gspread API und stellt eine robuste, wiederverwendbare Schnittstelle bereit.

Methodenbeschreibung

• __init__(self, sheet_url=None): Initialisiert den Handler.
• load_data(self): Lädt den gesamten Inhalt des Haupt-Arbeitsblatts in den internen Speicher.
• get_sheet_as_dataframe(self, sheet_name): Gibt ein spezifisches Arbeitsblatt als Pandas DataFrame zurück.
• append_rows(self, sheet_name, values): Fügt neue Zeilen am Ende eines Arbeitsblatts an.
• clear_and_write_data(self, sheet_name, data): Löscht ein Arbeitsblatt und schreibt neue Daten hinein.
• batch_update_cells(self, update_data): Führt eine performante Stapelverarbeitung von Zell-Updates durch.

wikipedia_scraper.py (Spezialist für Wikipedia)

Hauptfunktion

Das Modul wikipedia_scraper.py kapselt alle Interaktionen mit Wikipedia. Seine Hauptaufgabe ist es, den relevantesten Artikel zu finden, zu validieren und strukturierte Daten daraus zu extrahieren.

Methodenbeschreibung

• __init__(self, user_agent=None): Initialisiert den Scraper.
• serp_wikipedia_lookup(self, company_name, lang='de'): Nutzt die SerpAPI, um eine Google-Suche nach dem Wikipedia-Artikel durchzuführen.
• search_company_article(self, company_name, ...): Orchestriert den gesamten Such- und Validierungsprozess.
• _validate_article(self, page, company_name, ...): Führt eine faktenbasierte Überprüfung eines Artikels durch.
• extract_company_data(self, url_or_page): Die zentrale Extraktionsmethode, die strukturierte Daten aus der Infobox und dem Text parst.
• _extract_infobox_value(self, soup, target): Interne Hilfsmethode zur gezielten Suche in der Infobox.
• _parse_sitz_string_detailed(self, raw_sitz_string_input): Spezialisierte Hilfsmethode, um Stadt und Land aus dem Sitz-String zu extrahieren.

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.

Methodenbeschreibung

• __init__(self, sheet_handler, d365_export_path): Initialisiert den Manager mit Spaltenzuordnungen und Konfliktlösungsregeln.
• _load_data(self): Lädt und bereitet die Daten aus beiden Quellen für den Abgleich vor.
• run_sync(self): Orchestriert den gesamten Synchronisationsprozess und führt die Änderungen aus.
• debug_sync(self, debug_id=None): Bietet einen Debug-Modus zur Tiefenanalyse einzelner Datensätze.
• simulate_sync(self, debug_id=None): Führt eine "Trockenlauf"-Simulation des Syncs durch, ohne Daten zu ändern.

---

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 LLM.

Methodenbeschreibung

• call_openai_with_retry(...): Robuste Wrapper-Funktion für OpenAI-API-Aufrufe.
• build_prompt(...): Baut dynamisch den "Master-Prompt" für die KI zusammen, inklusive Pain Points und Referenzkunden.
• main(specific_branch=None): Die Haupt-Orchestrierungsfunktion, die bestehende Texte lädt, neue Kombinationen identifiziert, Texte generiert und die Ergebnisse in einem Batch an das Google Sheet anhängt.

---

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

Erstellt eine umfassende Wissensbasis, indem es die in config.py definierten Brancheninformationen nutzt, um mittels KI für jede Branche ein detailliertes Dossier zu erstellen und daraus strukturierte Daten zu extrahieren.

expand_knowledge_base.py

Dient dazu, eine bestehende Wissensbasis gezielt zu erweitern, indem es fehlende Branchen aus der config.py identifiziert und die entsprechenden Einträge generiert.

extract_insights.py

Ein Werkzeug zur automatisierten Erstellung einer Wissensbasis aus unstrukturierten Word-Dokumenten (.docx).

generate_knowledge_base.py

Ein KI-gestütztes Skript zur Erstellung eines ersten Entwurfs für eine Marketing-Wissensbasis, das Branchen-Pain-Points und den Fokus von Ansprechpartner-Positionen generiert.

---

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

Dieses Modul ist für die automatische Klassifizierung von Jobtiteln in vordefinierte Abteilungen zuständig. Es nutzt eine mehrstufige Logik aus regelbasierten Mappings und KI-gestützter Klassifizierung.

Methodenbeschreibung

• load_knowledge_base(self): Lädt die spezifische Wissensbasis für die Jobtitel-Zuordnung.
• _find_best_match(self, job_title, company_branch): Die Kernlogik für die regelbasierte Zuordnung.
• _get_ai_classification(self, contacts_to_classify): Sendet unklassifizierte Titel zur KI-basierten Klassifizierung.
• _append_learnings_to_source(...): Erweitert die Wissensbasis kontinuierlich mit neuen KI-Erkenntnissen.
• process_contacts(self): Die Hauptmethode, die den gesamten Klassifizierungsprozess steuert.

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

Hauptfunktion

Dieses Modul ist dafür verantwortlich, die spezifische Wissensbasis für die Jobtitel-Klassifizierung zu erstellen. Es generiert ein exaktes Mapping (exact_match_map.json) und Keyword-Regeln (keyword_rules.json) aus einer Liste von Beispielen.

---

7. Standalone-Werkzeuge

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

duplicate_checker_old.py (Duplikats-Check)

Hauptfunktion

Das Skript duplicate_checker_old.py ist ein spezialisiertes Werkzeug zur Identifizierung von potenziellen Duplikaten zwischen zwei Unternehmenslisten in Google Sheets. Es verwendet einen gewichteten, heuristischen Algorithmus, um den wahrscheinlichsten Treffer zu finden und zu bewerten.

Ablauf-Logik

1. Initialisierung & Daten laden: Richtet Logging ein und lädt die Daten aus den beiden Google Sheets.
2. Normalisierung & Index-Erstellung: Standardisiert Unternehmensnamen und erstellt Indizes zur Optimierung der Suche.
3. Iteratives Matching: Durchläuft jeden Datensatz der Matching-Liste, wählt eine kleine, relevante Untergruppe von Kandidaten aus und berechnet einen Ähnlichkeits-Score.
4. Ergebnis-Aggregation & Rückschreiben: Sammelt die besten Treffer und schreibt die Ergebnisse zurück in das Google Sheet.

---

8. Projekt-Fundament

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

config.py (Zentrale Konfiguration)

Hauptfunktion

Dient als zentrale Konfigurationsdatei für das gesamte Projekt. Es bündelt alle globalen Einstellungen, Dateipfade, API-Schlüssel-Pfade, Schwellenwerte und Mappings.

Methodenbeschreibung

• normalize_for_mapping(text): Eine interne Hilfsfunktion zur aggressiven Normalisierung von Strings.
• Config Klasse: Enthält statische Attribute für Version, URLs, Timeouts, Schwellenwerte, Batch-Größen, Mappings und API-Schlüssel-Pfade. Bietet Methoden zum Laden der API-Schlüssel.
• Globale Konstanten: COLUMN_ORDER und COLUMN_MAP definieren die exakte Struktur des Google Sheets.

helpers.py (Globaler Werkzeugkasten)

Hauptfunktion

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

Methodenbeschreibung (Auszug)

• Decorators: retry_on_failure(func) für robuste API-Aufrufe mit exponentiellem Backoff.
• Logging & Token Counting: token_count(...), create_log_filename(...).
• Text-, String- & URL-Utilities: simple_normalize_url(...), normalize_company_name(...), extract_numeric_value(...), etc.
• API Wrappers & Externe Dienste: call_openai_chat(...), summarize_website_content(...), serp_website_lookup(...), etc.
• Website Scraping & Validierung: get_website_raw(...), is_valid_wikipedia_article_url(...).