# Plan: Umsetzung des "General Market Intelligence" Backends als Python-Service Dieses Dokument beschreibt den Plan zur Umsetzung der Backend-Logik für die React-Anwendung unter `/general-market-intelligence` als robusten, faktenbasierten Python-Service. Dieser Ansatz ersetzt die ursprüngliche Idee einer n8n-Migration. ## 1. Zielsetzung & Architektur-Entscheidung Das primäre Ziel ist die Schaffung eines **transparenten, kontrollierbaren und faktenbasierten Backend-Prozesses**. Die ursprüngliche Implementierung der React-App zeigte Schwankungen in der Ergebnisqualität und mangelnde Nachvollziehbarkeit, da die KI-Aufrufe nicht auf verifizierbaren Daten basierten ("Grounding"). Nach einer Analyse wurde entschieden, von einer n8n-basierten Lösung Abstand zu nehmen und stattdessen einen **dedizierten Python-Service** zu entwickeln. **Gründe für Python statt n8n:** - **Maximale Kontrolle & Transparenz:** Ein Python-Skript ermöglicht detailliertes Logging, schrittweises Debugging und die volle Kontrolle über jeden Aspekt der Logik – von Web-Scraping bis zu den API-Aufrufen. Dies ist entscheidend, um die Ergebnisqualität sicherzustellen. - **Nahtlose Projekt-Integration:** Das Python-Skript fügt sich perfekt in die bestehende, Python-basierte Projektstruktur ein und kann auf geteilte Module (`config.py`, `helpers.py`) zugreifen. - **Robuste Fehlerbehandlung:** Komplexe Fehler- und Wiederholungslogiken lassen sich in Python präziser und robuster implementieren als in einer visuellen Workflow-Engine. - **Vermeidung von Plattform-Limitierungen:** Wir umgehen technische Hürden wie die eingeschränkte REST-API der selbstgehosteten n8n-Version. ## 2. Architektur: React-Frontend mit Python-Backend Die Architektur besteht aus drei Kernkomponenten, die in einem Docker-Container gekapselt werden: 1. **React-Frontend (unverändert):** Die bestehende Anwendung in `/general-market-intelligence` bleibt die interaktive Benutzeroberfläche. 2. **Node.js API-Brücke (`server.js`):** Ein minimaler Express.js-Server, der im selben Verzeichnis wie die React-App läuft. Seine einzige Aufgabe ist es, HTTP-Anfragen vom Frontend entgegenzunehmen und sie sicher an das Python-Skript weiterzuleiten. 3. **Python-Orchestrator (`market_intel_orchestrator.py`):** Das Herzstück der Logik. Dieses Kommandozeilen-Skript ist zuständig für: - Web-Scraping zur Gewinnung von Rohdaten ("Ground Truth"). - Text-Extraktion und -Bereinigung. - Gezielte und "geerdete" Aufrufe an die Gemini-API. - Rückgabe der strukturierten Ergebnisse als JSON über die Konsole (stdout). **Deployment:** Der gesamte Backend-Service (Node.js-Brücke und Python-Skript) wird in einem **Docker-Container** verpackt, um eine konsistente, "immer online" verfügbare Umgebung zu schaffen. ## 3. Kernfunktionen als Python-Module Die Logik aus `geminiService.ts` wird in Python-Funktionen innerhalb von `market_intel_orchestrator.py` nachgebildet, wobei der Fokus auf Faktenbasiertheit liegt. --- ### Funktion 1: `generate_search_strategy` - **Trigger:** Aufruf durch die Node.js-Brücke mit `--mode generate_strategy`. - **Input:** `reference_url` und `context_content` (Strategie-Dokument). - **Prozess:** 1. **Scraping (Grounding):** Lädt den HTML-Inhalt der `reference_url`. 2. **Text-Extraktion:** Bereinigt das HTML zu sauberem Text. 3. **KI-Analyse:** Ruft die Gemini-API mit einem Prompt auf, der explizit anweist, die digitalen Signale aus dem **bereitgestellten Website-Text** und dem Strategie-Kontext abzuleiten. - **Output:** Gibt das `SearchStrategy`-JSON auf der Konsole aus. --- ### Funktion 2: `identify_competitors` - **Trigger:** Aufruf mit `--mode identify_competitors`. - **Input:** `reference_url` und `target_market`. - **Prozess:** 1. Ruft die Gemini-API mit einem Google-Search-Tool auf, um ähnliche Unternehmen zu finden. - **Output:** Gibt eine JSON-Liste der gefundenen Unternehmen aus. --- ### Funktion 3: `run_full_analysis` - **Trigger:** Aufruf mit `--mode run_analysis`. - **Input:** Eine Liste von Unternehmensnamen und die zuvor generierte Suchstrategie. - **Prozess:** 1. Iteriert über die Unternehmensliste. 2. **Für jedes Unternehmen:** - Sucht die offizielle Website (z.B. über SerpAPI). - Scrapt die relevanten Seiten basierend auf den `targetPageKeywords` der digitalen Signale. - Ruft die Gemini-API auf, um die Signale basierend auf dem **gescrapten Inhalt** zu bewerten. - **Output:** Gibt eine Liste von `AnalysisResult`-Objekten aus. --- ### Funktion 4: `generate_outreach_campaign` - **Trigger:** Aufruf mit `--mode generate_outreach`. - **Input:** `company_data` (ein `AnalysisResult`-Objekt), `knowledge_base` (Strategie-Dokument) und `reference_url`. - **Prozess:** 1. Baut den Prompt für die Erstellung der E-Mail-Kampagne, wobei die **faktenbasierten `dynamicAnalysis`-Ergebnisse** als Kern der Personalisierung dienen. 2. Ruft die Gemini-API auf. - **Output:** Gibt die `EmailDraft`-Objekte als JSON-Array aus. ## 4. Nächste Schritte 1. **Implementierung (Python):** Erstellen der Datei `market_intel_orchestrator.py` und Implementierung der oben genannten Funktionen. 2. **Implementierung (Node.js):** Erstellen der `server.js` als API-Brücke im React-Projekt. 3. **Anpassung (React):** Modifizieren der `geminiService.ts`, um die Aufrufe an die lokale API-Brücke (`/api/...`) statt direkt an die Gemini-API zu senden. 4. **Containerisierung (Docker):** Erstellen eines `Dockerfile`, das die Python- und Node.js-Umgebung aufsetzt und den Service startet. 5. **Testen:** Umfassendes Testen des gesamten End-to-End-Flows. ## 5. Aktuelle Probleme und Debugging-Protokoll (Stand: 2025-12-21) ### Status: End-to-End-Test erfolgreich, nächster Fehler identifiziert. Wir haben erfolgreich eine Docker-Umgebung eingerichtet, die das hartnäckige `ImportError: cannot import name 'cygrpc' from 'grpc._cython'`-Problem löst. Die Kommunikationskette von der React-App über die Node.js-Brücke zum Python-Skript im Docker-Container funktioniert. **Aktueller Fehler (behoben am 2025-12-21):** - **Fehler:** `TypeError: GenerationConfig.__init__() got an unexpected keyword argument 'response_mime_type'` - **Ursache:** Die gepinnte, ältere Version der `google-generativeai`-Bibliothek (`0.4.0`) unterstützt diesen Parameter nicht, der in einem früheren Debugging-Schritt hinzugefügt wurde. - **Lösung:** Der Parameter `generation_config` wurde aus dem `model.generate_content`-Aufruf in `market_intel_orchestrator.py` entfernt. ### Nächster Schritt (für die nächste Sitzung): 1. Die neuesten Code-Änderungen pullen (`git pull`). 2. Das Docker-Image neu bauen, um die Korrektur zu übernehmen: `docker build -t market-intel-backend .` 3. Den alten Container stoppen/entfernen und den neuen starten: `docker run -p 3001:3001 --name market-intel-backend-instance market-intel-backend` 4. Den React-Dev-Server starten und den End-to-End-Test erneut durchführen. --- ### Debugging-Historie (gelöste Probleme) - **Problem:** `externally-managed-environment` im Docker-Build. - **Lösung:** Expliziter Pfad zum `pip`-Executable der venv im `Dockerfile` (`/app/.venv/bin/pip install ...`). - **Problem:** `ImportError: cannot import name 'cygrpc' from 'grpc._cython'`. - **Lösungsversuche:** 1. Version-Pinning von `requests`, `urllib3`, `typing-extensions`, `grpcio`, `google-api-core`, `google-generativeai`. (Erfolglos) 2. Deinstallation und Neu-Kompilierung von `grpcio` aus dem Quellcode. (Erfolglos in der lokalen Umgebung) - **Finale Lösung:** Umstieg auf eine vollständig gekapselte **Docker-Umgebung**, in der die Installation der Python-Pakete in einer sauberen und kontrollierten Umgebung von Grund auf neu erfolgt. - **Problem:** `TypeError: 'type' object is not subscriptable`. - **Lösung:** Version von `urllib3` und `requests` auf `1.26.18` bzw. `2.28.2` gepinnt. - **Problem:** `AttributeError: module 'typing' has no attribute '_SpecialGenericAlias'`. - **Lösung:** Version von `typing-extensions` auf `4.5.0` gepinnt. - **Problem:** `ModuleNotFoundError: No module named 'requests'`. - **Lösung:** `PYTHONPATH` im `spawn`-Befehl in `server.cjs` explizit gesetzt. - **Problem:** `net::ERR_CONNECTION_REFUSED` in der React-App. - **Lösung:** API-URL in `geminiService.ts` von `localhost` auf `window.location.hostname` umgestellt. - **Problem:** `require is not defined in ES module scope` in Node.js. - **Lösung:** `server.js` in `server.cjs` umbenannt und `package.json` angepasst. - **Problem:** Diverse Python-Umgebungsprobleme (`ensurepip`, `apt`-Pakete). - **Lösung:** `python3-venv`, `build-essential`, `python3-dev` installiert und eine virtuelle Umgebung (`venv`) eingerichtet.