From 57bd3e524a6717f1f190e4d5ab0004d9c212386a Mon Sep 17 00:00:00 2001 From: Floke Date: Fri, 7 Nov 2025 15:22:37 +0100 Subject: [PATCH] Docs: Add documentation for contact_grouping.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Beschreibt die Hauptfunktion und den Zweck des Moduls. - Dokumentiert die wichtigsten öffentlichen Methoden. --- readme.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 8c7a2d04..0492c47c 100644 --- a/readme.md +++ b/readme.md @@ -320,4 +320,58 @@ Das Modul `wikipedia_scraper.py` kapselt alle Interaktionen mit Wikipedia. Seine - `_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. \ No newline at end of file +- `_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.