Brancheneinstufung2/market_intel_backend_plan.md

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)

Wir stecken derzeit in einem hartnäckigen ImportError: cannot import name 'cygrpc' from 'grpc._cython' Fehler fest, der beim Starten des Python-Skripts (market_intel_orchestrator.py) auftritt.

Bisher unternommene Schritte zur Problemlösung:

1. Virtuelle Umgebung (.venv) erstellt: Um Paketkonflikte zu isolieren.
2. python3.11-venv installiert: Um venv unter Debian/Ubuntu zu ermöglichen.
3. requirements.txt bereinigt und Paketversionen gepinnt:
   • requests==2.28.2 und urllib3==1.26.18 (behob TypeError: 'type' object is not subscriptable).
   • typing-extensions==4.5.0 (behob AttributeError: module 'typing' has no attribute '_SpecialGenericAlias').
   • google-generativeai==0.4.0 (gepinnt, um Kompatibilität mit älteren google-api-core und grpcio zu erzwingen).
   • grpcio==1.54.2 und google-api-core==2.11.1 (gepinnt, sollte cygrpc beheben, hat es aber nicht).
4. gemini_api_key.txt geprüft: Sichergestellt, dass nur der reine API-Schlüssel enthalten ist.
5. Gemini-Modell gewechselt: Von gemini-1.5-flash zu gemini-pro, dann responseMimeType zu text/plain geändert (dies war eine Umgehung zur Diagnose, der 404 Not Found-Fehler trat weiterhin auf, was auf ein tieferes Autorisierungs- oder Kompilierungsproblem hindeutet).
6. Node.js API-Brücke (server.cjs) angepasst: Sichergestellt, dass der Python-Subprozess mit dem korrekten Venv-Interpreter und der PYTHONPATH gestartet wird (behob ModuleNotFoundError: No module named 'requests').
7. grpcio deinstalliert und Build-Tools installiert: build-essential und python3-dev wurden installiert, um eine Kompilierung von grpcio aus dem Quellcode zu ermöglichen.

Aktuelles Problem:

Der Fehler ImportError: cannot import name 'cygrpc' from 'grpc._cython' bleibt bestehen, selbst nach dem Versuch, grpcio neu zu kompilieren (der Kompilierungsschritt selbst konnte nicht vollständig durchgeführt werden).

Dieser Fehler ist ein Indikator dafür, dass die vor-kompilierten grpcio-Wheels nicht mit der spezifischen Systemumgebung (Python-Version, Betriebssystem, installierte Bibliotheken) kompatibel sind, oder dass die Kompilierung aus dem Quellcode fehlschlägt, weil immer noch eine Abhängigkeit oder ein Build-Tool auf Systemebene fehlt oder inkompatibel ist.

Mögliche nächste Schritte (manuell durch den Benutzer):

• Erneuter Versuch der grpcio-Kompilierung: Führen Sie den Befehl pip install --no-binary :all: grpcio==1.54.2 erneut aus. Beobachten Sie die Ausgabe genau auf Kompilierungsfehler. Der Prozess kann sehr lange dauern.
• Upgrade/Downgrade der Python-Version: Das Problem könnte mit Python 3.11 spezifisch sein. Ein Versuch mit Python 3.10 oder 3.9 könnte helfen, ist aber ein größerer Eingriff ins System.
• Docker-Ansatz vorziehen: Die sauberste und reproduzierbarste Lösung wäre, den gesamten Backend-Stack in einem Docker-Container zu betreiben. Innerhalb eines Dockerfiles können wir die Umgebung exakt steuern und die Installation der Abhängigkeiten von Grund auf neu aufbauen, was solche cygrpc-Probleme oft umgeht.