# Projekt: Automatisierte Unternehmensbewertung & Lead-Generierung v2.2.1

## 1. Projektübersicht

Dieses Repository enthält eine Suite von Python-Skripten zur automatisierten Anreicherung und Analyse von Unternehmensdaten. Das System ist modular aufgebaut und für den Betrieb in einem Docker-Container ausgelegt.

*   **`brancheneinstufung.py`:** Das Kernmodul zur Datenanreicherung (Web, Wikipedia, KI-Analyse).
*   **`duplicate_checker.py`:** Ein Modul zur intelligenten Duplikatsprüfung.
*   **`generate_marketing_text.py`:** Eine Engine zur Erstellung personalisierter Marketing-Texte.
*   **`app.py` & Docker:** Eine fernsteuerbare Schnittstelle via Google Sheets.

## 2. Aktueller Status: **KRITISCHER FEHLER (BLOCKER)**

Das gesamte System ist derzeit **nicht lauffähig**. Ein Inkompatibilitätsproblem zwischen dem bestehenden Code und der installierten Version der `openai`-Python-Bibliothek führt zu einem `ModuleNotFoundError` bei jedem Versuch, eine KI-Funktion aufzurufen. Dies verhindert jegliche Weiterentwicklung und Nutzung.

## 3. Nächster Schritt

**Priorität 1:** Behebung des `openai`-Abhängigkeitskonflikts. Die gewählte Strategie ist ein gezieltes Downgrade der `openai`-Bibliothek auf eine mit dem Code kompatible Version, um die Funktionalität schnellstmöglich wiederherzustellen.
planning.md (v2.2.1)
code
Markdown
# Projektplanung v2.2.1

## 1. Aktueller Stand
*   **[X] Architektur & Module:** Alle Kernmodule sind konzipiert und implementiert.
*   **[!] System-Blocker:** Ein Versionskonflikt der `openai`-Bibliothek legt das gesamte System lahm. Alle Funktionen, die auf die KI zugreifen, stürzen mit einem `ModuleNotFoundError` ab.

## 2. Strategischer Plan

**Phase 1: Stabilität wiederherstellen (Hotfix)**
*   **[ ]** **Schritt 1.1 (Analyse):** Überprüfung aller Code-Stellen, die `openai`-Fehlerklassen importieren oder verwenden, um den Umfang des Problems zu bestätigen.
*   **[ ]** **Schritt 1.2 (Downgrade):** Modifikation der `requirements.txt`, um die `openai`-Bibliothek auf eine stabile, kompatible Version (z.B. `0.28.0`) festzuschreiben.
*   **[ ]** **Schritt 1.3 (Anwendung):** Neubau des Docker-Images (`docker build`), um die Installation der korrekten Bibliotheksversion zu erzwingen.
*   **[ ]** **Schritt 1.4 (Validierung):** Durchführung eines Testlaufs (z.B. `reclassify_branches`), um zu bestätigen, dass der `ModuleNotFoundError` behoben ist und die KI-Aufrufe wieder funktionieren.

**Phase 2: Geplante Weiterentwicklung (nach Hotfix)**
*   **[ ]** Finalisierung des Duplikats-Checks.
*   **[ ]** Vervollständigung der Wissensbasis und Generierung aller Marketing-Texte.
*   **[ ]** (Zukünftig) Planung des Code-Refactorings, um die neue `openai` v1.x API zu unterstützen.

# Automatisierte Unternehmensbewertung & Lead-Generierung

**Version:** 2.1.0 (nach Implementierung des Sync-Moduls)

## Projektbeschreibung

Dieses Projekt automatisiert die Anreicherung von Unternehmensdaten aus einem D365-CRM-System. Es nutzt externe APIs (Google, Wikipedia, OpenAI) und Web-Scraping, um Stammdaten zu validieren, zu ergänzen und neue, marketing-relevante Informationen (z.B. FSM-Pitches) zu generieren. Die Verarbeitung und Speicherung der angereicherten Daten erfolgt in einem Google Sheet.

## Aktueller Status (August 2025)

*   **Systemstabilität:** Das System ist nach der Behebung von Inkompatibilitäten mit der OpenAI-Bibliothek stabil und voll lauffähig.
*   **Daten-Import:** Ein robuster, intelligenter Synchronisations-Mechanismus (`sync_manager.py`) wurde implementiert. Er gleicht einen vollständigen D365-Excel-Export mit dem Google Sheet ab, aktualisiert Stammdaten nach definierten Fachregeln und markiert Datätze für die Neu-Anreicherung.
*   **Kernfunktionen:** Datenanreicherung (Wikipedia, Website-Scraping) und KI-basierte Analysen (Brancheneinstufung, Text-Zusammenfassungen) sind operational.
*   **Nächster Schritt:** Implementierung des Daten-Exports aus dem Google Sheet zur Aktualisierung des D365-Systems.

## Duplicate Checker (duplicate_checker_old.py)

### Hauptfunktion
Das Skript `duplicate_checker_old.py` (Version 2.15) ist ein spezialisiertes Werkzeug zur Identifizierung von potenziellen Duplikaten zwischen zwei Unternehmenslisten in Google Sheets: einer Matching-Liste (`Matching_Accounts`) und einer Referenz-CRM-Liste (`CRM_Accounts`). Es verwendet einen gewichteten, heuristischen Algorithmus, um für jeden Eintrag in der Matching-Liste den wahrscheinlichsten Treffer im CRM-Bestand zu finden und bewertet diesen mit einem numerischen Score.

### 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
1.  **Initialisierung**: Das Skript richtet das Logging ein, lädt API-Schlüssel (optional für SerpAPI) und initialisiert den `GoogleSheetHandler`.
2.  **Daten laden**: Die Daten aus den beiden Google Sheets (`CRM_Accounts` und `Matching_Accounts`) werden in Pandas DataFrames geladen.
3.  **SerpAPI-Fallback (Optional)**: Für Einträge in der Matching-Liste ohne Website wird versucht, über die SerpAPI eine URL zu finden. Das Vertrauen in die gefundene URL wird bewertet (`hoch`, `mittel`, `niedrig`).
4.  **Normalisierung**: Unternehmensnamen, Domains, Orte und Länder in beiden DataFrames werden standardisiert (z.B. Kleinschreibung, Entfernung von Rechtsformzusätzen).
5.  **Index-Erstellung**: Zur Optimierung der Suche werden mehrere "Blocking"-Indizes aus den CRM-Daten erstellt:
    - Ein `domain_index` für schnelle Suchen über die Website-Domain.
    - Ein `token_index` für die Suche nach einzelnen Namensbestandteilen.
    - Eine `token_freq` Zählung, um seltene und damit aussagekräftige Namensbestandteile zu identifizieren.
6.  **Iteratives Matching**: Das Skript durchläuft jeden Datensatz der Matching-Liste:
    a. **Kandidatenauswahl**: Anstatt jeden Eintrag mit der gesamten CRM-Liste zu vergleichen, wird eine kleine, relevante Untergruppe von Kandidaten ausgewählt. Die Auswahl erfolgt priorisiert: zuerst über Domain-Übereinstimmung, dann über den seltensten Namens-Token und zuletzt über einen allgemeinen Prefilter.
    b. **Scoring**: Jeder Kandidat wird mit dem aktuellen Matching-Datensatz verglichen. Die Funktion `calculate_similarity` berechnet einen Score basierend auf einer gewichteten Formel, die Namensähnlichkeit, Domain-Match, Standortübereinstimmung, Boni und Strafen berücksichtigt.
    c. **Bester Treffer**: Der Kandidat mit dem höchsten Score wird als potenzielles Duplikat ausgewählt.
7.  **Ergebnis-Aggregation**: Die Ergebnisse (bester Treffer, Score, Begründung der Bewertung) werden gesammelt.
8.  **Daten zurückschreiben**: Die Matching-Liste wird um die Ergebnisspalten (`Match`, `Score`, `Match_Grund`) erweitert und vollständig in das Google Sheet `Matching_Accounts` zurückgeschrieben. Ein lokales CSV-Backup wird ebenfalls erstellt.

## brancheneinstufung2.py

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

## Hilfsfunktionen (helpers.py)

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

## google_sheet_handler.py

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

### 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.
## knowledge_base_builder.py

### 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-Regel 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.
## contact_grouping.py

### 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.
## sync_manager.py

### 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.
## config.py

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