diff --git a/market_intel_backend_plan.md b/market_intel_backend_plan.md new file mode 100644 index 00000000..f5bc692d --- /dev/null +++ b/market_intel_backend_plan.md @@ -0,0 +1,88 @@ +# 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. \ No newline at end of file diff --git a/n8n_migration_plan.md b/n8n_migration_plan.md deleted file mode 100644 index 019006e3..00000000 --- a/n8n_migration_plan.md +++ /dev/null @@ -1,93 +0,0 @@ -# Plan zur Migration des "General Market Intelligence" Skripts nach n8n (Hybrid-Ansatz) - -Dieses Dokument beschreibt den Plan zur Nachbildung der Funktionalität der React-Anwendung unter `/general-market-intelligence` als Backend-Logik in der Automatisierungsplattform n8n. - -## 1. Zielsetzung (Hybrid-Ansatz) - -Das Ziel ist die **Auslagerung der Kernlogik** (insbesondere der Gemini API-Aufrufe) aus der React-Anwendung in n8n-Workflows. Dies erhöht die **Transparenz, Kontrolle und Stabilität** der Ergebnisse. - -- Die **bestehende React-Anwendung bleibt als interaktives Frontend** für die Benutzerführung und Datenvisualisierung erhalten. -- **n8n fungiert als reines Backend-API**, das von der React-Anwendung aufgerufen wird, um die rechenintensiven Aufgaben auszuführen. - -Dieser Ansatz kombiniert das Beste aus beiden Welten: eine reaktionsschnelle, benutzerfreundliche Oberfläche und ein robustes, leicht anpassbares Backend. - -## 2. Analyse der Kernfunktionalität - -Die bestehende Anwendung führt fünf Hauptschritte aus, die nun als separate, aufrufbare n8n-Workflows modelliert werden: - -1. **Strategie-Erstellung:** Generiert eine Suchstrategie aus einem Strategie-Dokument und einer Referenz-URL. -2. **Lead-Identifizierung:** Findet ähnliche Unternehmen basierend auf der Referenz-URL. -3. **Manuelle Überprüfung:** **Dieser Schritt verbleibt vollständig im React-Frontend.** Die App zeigt die Liste an und ermöglicht die Kuratierung. -4. **Tiefenanalyse:** Analysiert die vom Nutzer kuratierte Liste von Unternehmen. -5. **Kampagnen-Erstellung:** Generiert personalisierte E-Mail-Entwürfe. - -## 3. Hybrid-Architektur: Zusammenspiel von React & n8n - -Die Kommunikation zwischen Frontend und Backend erfolgt über Webhooks: - -1. **n8n-Workflows als API-Endpunkte:** Jeder Kernprozess wird als eigener n8n-Workflow mit einem **Webhook-Trigger** erstellt. Dieser Trigger stellt eine einzigartige URL bereit, die auf Anfragen wartet. -2. **React-App als Client:** Die Funktionen in der `geminiService.ts`-Datei der React-App werden so angepasst, dass sie nicht mehr direkt die Gemini-API, sondern die entsprechenden n8n-Webhook-URLs aufrufen (mittels `fetch` oder `axios`). -3. **Datenfluss (Beispiel):** - - Der Nutzer lädt in der React-App eine Strategie-Datei hoch und klickt auf "Strategie erstellen". - - Die React-App sendet den Dateiinhalt und die Referenz-URL per `POST`-Request an den n8n-Webhook für die Strategie-Erstellung. - - Der n8n-Workflow wird ausgelöst, führt den Gemini-Call aus und sendet das Ergebnis (das `SearchStrategy`-JSON) als Antwort auf den Webhook-Request zurück. - - Die React-App empfängt die JSON-Antwort und zeigt dem Nutzer den nächsten Schritt an. - -## 4. Benötigte n8n-Workflows (API-Endpunkte) - -Die folgenden Workflows müssen in n8n erstellt werden, um die Logik aus `geminiService.ts` abzubilden. - ---- - -### Workflow 1: `generateSearchStrategy` - -- **Trigger:** `Webhook` (erwartet `POST`-Request) -- **Input (JSON Body):** `{ "referenceUrl": "...", "contextContent": "..." }` -- **Aktion:** - 1. Nimmt die Eingabedaten entgegen. - 2. Baut den Prompt für die Strategie-Generierung. - 3. Ruft den `Gemini`-Knoten auf. -- **Output:** `Respond to Webhook`-Knoten, der das `SearchStrategy` JSON-Objekt zurückgibt. - ---- - -### Workflow 2: `identifyCompetitors` - -- **Trigger:** `Webhook` (erwartet `POST`-Request) -- **Input (JSON Body):** `{ "referenceUrl": "...", "targetMarket": "..." }` -- **Aktion:** - 1. Baut den Prompt zur Identifizierung von Wettbewerbern. - 2. Ruft den `Gemini`-Knoten auf. -- **Output:** `Respond to Webhook`-Knoten, der die Liste der gefundenen Unternehmen als JSON-Array zurückgibt. - ---- - -### Workflow 3: `runFullAnalysis` - -Dieser Workflow führt die Tiefenanalyse für eine ganze Liste von Unternehmen durch. - -- **Trigger:** `Webhook` (erwartet `POST`-Request) -- **Input (JSON Body):** `{ "strategy": { ... }, "companies": [ { "name": "..." }, ... ] }` -- **Aktion:** - 1. Nutzt den `Loop Over Items`-Knoten, um über die `companies`-Liste zu iterieren. - 2. **Innerhalb des Loops:** Ruft für jedes Unternehmen den `Gemini`-Knoten mit dem Prompt für die Tiefenanalyse (`analyzeCompanyWithStrategy`) auf. - 3. Sammelt die Ergebnisse aller Iterationen. -- **Output:** `Respond to Webhook`-Knoten, der eine vollständige Liste von `AnalysisResult`-Objekten als JSON zurückgibt. - ---- - -### Workflow 4: `generateOutreachCampaign` - -- **Trigger:** `Webhook` (erwartet `POST`-Request) -- **Input (JSON Body):** `{ "companyData": { ... }, "knowledgeBase": "...", "referenceUrl": "..." }` -- **Aktion:** - 1. Baut den Prompt für die Erstellung der E-Mail-Kampagne. - 2. Ruft den `Gemini`-Knoten auf. -- **Output:** `Respond to Webhook`-Knoten, der die `EmailDraft`-Objekte als JSON-Array zurückgibt. - -## 5. Nächste Schritte - -1. **Umsetzung in n8n:** Erstellen der vier beschriebenen Workflows, beginnend mit `generateSearchStrategy`. -2. **Anpassung der React-App:** Modifizieren der `geminiService.ts`, um die `fetch`-Aufrufe auf die neuen n8n-Webhook-URLs umzuleiten. -3. **Konfiguration:** Die URLs der n8n-Webhooks müssen in der React-Anwendung als Umgebungsvariablen (`.env.local`) konfiguriert werden, um Flexibilität zwischen Entwicklungs- und Produktionsumgebungen zu gewährleisten. -4. **Sicherheit:** Absicherung der n8n-Webhooks, z.B. durch einen geheimen Header-Parameter, um unbefugte Aufrufe zu verhindern. diff --git a/readme.md b/readme.md index 0f14d8a8..782d9e1c 100644 --- a/readme.md +++ b/readme.md @@ -662,44 +662,44 @@ Diese Datei enthält eine Sammlung von globalen, wiederverwendbaren Hilfsfunktio ## 9. Standalone Tool: Market Intelligence App -### Funktionsweise +### Funktionsweise und Architektur -Das Skript ist eine mehrstufige Webanwendung, die als B2B-Marktanalyse- und Lead-Qualifizierungs-Tool dient. Es nutzt die Gemini-API, um basierend auf strategischen Dokumenten eines Unternehmens potenzielle Kunden zu finden, zu analysieren und personalisierte Ansprachen zu generieren. Der Prozess ist in mehrere logische Schritte unterteilt: +Das Market Intelligence Tool ist eine mehrstufige Webanwendung für die B2B-Marktanalyse und Lead-Qualifizierung. Es kombiniert eine interaktive React-Oberfläche mit einem robusten, faktenbasierten Python-Backend, um potenzielle Kunden zu finden, zu analysieren und personalisierte Ansprachen zu generieren. + +Der entscheidende Unterschied zur ursprünglichen Implementierung liegt im Backend-Ansatz: Statt direkter, potenziell inkonsistenter KI-Aufrufe aus dem Frontend wird ein kontrollierter, transparenter und auf echten Daten basierender Prozess eingesetzt, um die Qualität und Nachvollziehbarkeit der Ergebnisse massiv zu verbessern. + +#### Technische Umsetzung und Architektur + +Die Anwendung ist als Service in einem **Docker-Container** gekapselt und besteht aus drei Hauptkomponenten: + +1. **React-Frontend:** Die Benutzeroberfläche unter `general-market-intelligence/` bleibt der interaktive Arbeitsbereich für den Benutzer. Alle Eingaben und die Visualisierung der Ergebnisse finden hier statt. +2. **Node.js API-Brücke:** Ein minimaler Express.js-Server, der als Schnittstelle zwischen dem Frontend und der Python-Logik dient. Er nimmt die Anfragen der App entgegen und ruft das Python-Skript als sicheren Unterprozess auf. +3. **Python-Orchestrator (`market_intel_orchestrator.py`):** Das Herzstück des Systems. Dieses Skript führt die Kernlogik aus und ist nach dem Prinzip **"Grounding first"** konzipiert: + - **Web-Scraping als "Ground Truth":** Bevor eine KI-Analyse stattfindet, werden die relevanten Webseiten der Unternehmen (Referenzkunden, Zielunternehmen) gescrapt. Der extrahierte, bereinigte Text dient als unveränderliche Faktenbasis. + - **Gezielte KI-Analyse:** Die Gemini-API wird erst im zweiten Schritt aufgerufen. Sie erhält den extrahierten Website-Text als primären Kontext und die Anweisung, ihre Analyse (z.B. die Identifizierung digitaler Signale) ausschließlich auf diesen realen Daten zu basieren. + +Dieser Ansatz stellt sicher, dass die Ergebnisse nicht "halluziniert" sind, sondern auf den tatsächlichen Inhalten der Unternehmens-Websites beruhen, was zu konsistenteren und validierbareren Analysen führt. + +#### Der Analyse-Prozess im Überblick + +Der Prozess für den Benutzer bleibt weitgehend gleich, ist aber technisch solider untermauert: **Schritt 1: Input & Strategie-Erstellung** - -1. **Dateneingabe:** Der Benutzer startet, indem er zwei primäre Informationen bereitstellt: - * Ein **Strategie-Dokument** (eine Markdown-Datei wie `yamaichi_neu.md`). Dieses Dokument ist das Herzstück und enthält detaillierte Informationen über das eigene Angebot, die Zielgruppen (Unternehmen und Personas), deren Schmerzpunkte (Pain Points) und den Nutzen der eigenen Lösung. - * Die **URL eines Referenzkunden**. Diese URL dient als Kalibrierung, um ähnliche Unternehmen ("Lookalikes") zu finden. -2. **Strategie-Generierung:** Das Skript sendet den Inhalt des Strategie-Dokuments und die Referenz-URL an die Gemini-API (`generateSearchStrategy`). Die KI analysiert diese Informationen und erstellt eine "Suchstrategie". Diese Strategie ist ein JSON-Objekt, das drei Kernpunkte enthält: - * Eine kurze Zusammenfassung des Angebots. - * Ein detailliertes "Ideal Customer Profile" (ICP). - - Eine Liste von 3-5 spezifischen **"Digitalen Signalen"**. Das sind konkrete Merkmale, nach denen auf den Websites potenzieller Kunden gesucht werden soll (z.B. "verwendet eine bestimmte Technologie", "hat eine komplexe Retourenrichtlinie", "sucht Mitarbeiter mit bestimmten Skills"). +- **Dateneingabe:** Der Benutzer lädt ein **Strategie-Dokument** hoch und gibt die **URL eines Referenzkunden** an. +- **Backend-Prozess:** + 1. Das Python-Skript scrapt die Website des Referenzkunden, um eine Faktenbasis ("Ground Truth") zu schaffen. + 2. Die KI analysiert den Website-Inhalt im Kontext des Strategie-Dokuments und leitet daraus ein faktenbasiertes **"Ideal Customer Profile" (ICP)** und eine Liste hochrelevanter **"Digitaler Signale"** ab. **Schritt 2: Identifizierung & Überprüfung der Zielunternehmen** - -1. **Lead-Findung:** Basierend auf der Referenz-URL und einem definierten Zielmarkt (z.B. "Deutschland") fragt das Skript die Gemini-API (`identifyCompetitors`), eine Liste von ca. 10 Konkurrenten oder ähnlichen Unternehmen zu erstellen. -2. **Manuelle Überprüfung:** Die generierte Liste wird dem Benutzer angezeigt. Er hat die Möglichkeit, unpassende Unternehmen zu entfernen oder manuell weitere hinzuzufügen. +- **Lead-Findung:** Basierend auf der Referenz-URL wird eine Liste ähnlicher Unternehmen generiert. +- **Manuelle Überprüfung:** Der Benutzer kuratiert diese Liste im Frontend. **Schritt 3: Tiefenanalyse der Unternehmen (Audit)** +- **Backend-Prozess:** + 1. Für jedes Unternehmen auf der finalen Liste werden die relevanten Webseiten-Inhalte gescrapt. + 2. Die KI prüft für jedes Unternehmen das Vorhandensein der zuvor definierten "Digitalen Signale" **basierend auf dem gescrapten Text**. + 3. Die Ergebnisse werden zusammen mit einer Handlungsempfehlung aufbereitet. -1. **Iterative Analyse:** Für jedes Unternehmen auf der finalen Liste führt das Skript eine detaillierte Analyse durch (`analyzeCompanyWithStrategy`). -2. **Analyse-Prozess:** Für jedes einzelne Unternehmen wird ein neuer Aufruf an die Gemini-API gesendet. Die KI erhält den Firmennamen und die zuvor erstellte "Suchstrategie" als Anweisung. Sie führt dann folgende Aufgaben aus: - * **Firmographics:** Recherche von Basisdaten wie Umsatz und Mitarbeiterzahl. - * **Signal-Prüfung:** Überprüfung der Website des Unternehmens auf die definierten "Digitalen Signale". - * **Klassifizierung:** Einordnung des Unternehmens in Tiers (Größe) und Status (z.B. "Potenzieller Kunde", "Wettbewerber"). - * **Empfehlung:** Formulierung einer kurzen, prägnanten Handlungsempfehlung für den Vertrieb. - -**Schritt 4: Reporting** - -1. **Ergebnis-Darstellung:** Alle Analyseergebnisse werden in einer übersichtlichen Tabelle zusammengefasst und angezeigt. -2. **Export:** Der gesamte Bericht kann als Markdown-Datei heruntergeladen werden. - -**Schritt 5: Personalisierte Ansprache (Outreach)** - -1. **Kampagnen-Generierung:** Der Benutzer kann aus dem Report ein vielversprechendes Unternehmen auswählen, um eine personalisierte E-Mail-Kampagne zu erstellen. -2. **Kontext-Anreicherung:** Das Skript fragt nach einer "Wissensdatenbank" (typischerweise das gleiche Strategie-Dokument wie in Schritt 1). -3. **E-Mail-Entwurf:** Die KI (`generateOutreachCampaign`) erhält alle gesammelten Informationen über das Zielunternehmen, die Wissensdatenbank und den Referenzkunden. Basierend darauf erstellt sie drei hyper-personalisierte, sofort einsatzbereite E-Mail-Entwürfe, die auf verschiedene Personas (z.B. COO, HR-Leiter) zugeschnitten sind und die gefundenen "Digitalen Signale" als Aufhänger nutzen. -4. **Finalisierung:** Die Entwürfe können angesehen, bei Bedarf in andere Sprachen übersetzt und zur weiteren Verwendung kopiert werden. - -Zusammenfassend automatisiert das Skript den gesamten Prozess von der strategischen Planung über die Lead-Generierung und -qualifizierung bis hin zur Erstellung des ersten personalisierten Anschreibens. \ No newline at end of file +**Schritt 4 & 5: Reporting & Personalisierte Ansprache** +- **Ergebnis-Darstellung:** Die faktenbasierten Analyseergebnisse werden im Frontend angezeigt. +- **Kampagnen-Generierung:** Die KI nutzt die validierten "Digitalen Signale" als Aufhänger, um hyper-personalisierte und extrem treffsichere E-Mail-Entwürfe zu erstellen. \ No newline at end of file