Floke
4a765cbf71
- Updated readme.md with new step 3 audit details. - Updated market_intel_backend_plan.md with current status and achievements. - Fixed SerpAPI key file path in orchestrator. - Documented the transition to direct REST API calls and enhanced terminal UX.
113 lines
7.2 KiB
Markdown
113 lines
7.2 KiB
Markdown
# 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 (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.
|
||
|
||
## 5. Aktueller Status und Debugging-Protokoll (Stand: 2025-12-21 - Abend)
|
||
|
||
### Status: Deep Tech Audit voll funktionsfähig & Grounded!
|
||
|
||
Wir haben die Phase der reinen Infrastruktur-Einrichtung verlassen und ein intelligentes Recherche-System aufgebaut.
|
||
|
||
**Wichtigste Errungenschaften:**
|
||
- **Smart Grounding:** Implementierung der "Scout & Hunter"-Strategie. Die KI generiert nun pro Signal eine Such-Strategie, die gezielt über SerpAPI ausgeführt wird.
|
||
- **REST-API Bridge:** Umstellung auf direkte REST-Aufrufe an Gemini `v1` (Modell: `gemini-2.5-pro`), um Inkompatibilitäten der Python-Bibliotheken in der Docker-Umgebung zu umgehen.
|
||
- **Lookalike-Kategorisierung:** Konkurrenten werden nun präzise in Lokal, National und International unterteilt.
|
||
- **UX-Terminal:** Das UI zeigt nun echten Fortschritt während des Audits an, was die Transparenz massiv erhöht.
|
||
- **Abhängigkeits-Isolierung:** Das Backend wurde komplett von `helpers.py` und `config.py` entkoppelt, um das Image schlank zu halten und gspread-Konflikte zu vermeiden.
|
||
|
||
**Gelöste Probleme heute:**
|
||
- **404 Not Found:** Gelöst durch Wechsel auf direkten REST-Call und das korrekte Modell `gemini-2.5-pro`.
|
||
- **ModuleNotFoundError (gspread/openai):** Gelöst durch Autarkie der `market_intel_orchestrator.py` und dedizierte Requirements.
|
||
- **Halluzinierte Wettbewerber:** Gelöst durch Nutzung des ICP (Ideal Customer Profile) als Suchbasis anstatt des reinen Angebotstextes.
|
||
|
||
---
|
||
### Nächste Schritte:
|
||
1. **Stabilität:** Feinjustierung der SerpAPI-Abfragen, um noch präzisere Job-Snippets zu erhalten.
|
||
2. **Report-Export:** Optimierung des MD-Exports, um die neuen Beleg-Links ("Proof") prominent anzuzeigen.
|
||
3. **Campaign-Generation:** Implementierung von Schritt 4 (Hyper-personalisierte E-Mails basierend auf Audit-Fakten).
|
||
|