# Legacy Dokumentation: Monolithische Python-Skripte (v2.x)

**⚠️ HINWEIS:** Diese Dokumentation ist ein Archiv der ursprünglichen `readme.md`. Sie beschreibt die alte, skript-basierte Architektur (Abschnitte 1-8). Die Dokumentation für die aktiven Systeme (Company Explorer, Market Intelligence) wurde in die jeweiligen Unterordner verschoben.

---

## 1. Projektübersicht & Architektur (Alt)

Dieses Projekt war ursprünglich eine modulare "Lead Enrichment Factory" auf Basis von CLI-Skripten.

### Architektur im Überblick

```text
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)

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 (Legacy)

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

### `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.

----

## 8. Projekt-Fundament (Legacy)

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