# Migration Report: Competitor Analysis Agent

## Status: Jan 11, 2026 - ✅ ROBUSTNESS UPGRADE COMPLETE

Die App ist unter `/ca/` voll funktionsfähig und verfügt nun über eine "Grounded Truth" Engine (Scraping + SerpAPI) sowie eine skalierbare **Map-Reduce Architektur**.

### 🚨 Vollständige Chronik der Fehler & Lösungen

1.  **Problem: 404 auf `/ca/`**
    *   **Ursache:** Der Container startete aufgrund von Syntaxfehlern nicht, was Nginx mit einem 404 (später 502) quittierte.

2.  **Problem: `SyntaxError: unterminated string literal` (Runde 1)**
    *   **Ursache:** Verwendung von `f"""..."""` für komplexe Prompts.
    *   **Lösung:** Umstellung auf `.format()`. **Wichtig:** Docker-Volumes synchronisierten nicht zuverlässig, was zu "Phantom-Fehlern" führte. Ein `build --no-cache` war nötig.

3.  **Problem: `ImportError: cannot import name 'Schema'`**
    *   **Ursache:** Uralte SDK-Version `google-generativeai==0.3.0` in `requirements.txt`.
    *   **Lösung:** Umstellung auf Dictionaries, später komplettes SDK-Upgrade.

4.  **Problem: `404 models/gemini-1.5-pro ... for API version v1beta`**
    *   **Ursache:** Das alte SDK nutzte veraltete Endpunkte.
    *   **Lösung:** Migration auf das moderne **`google-genai`** Paket (v1.x) und Nutzung des neuen `genai.Client`.

5.  **Problem: `TypeError: unexpected keyword argument 'client_options'`**
    *   **Analyse:** Obwohl das SDK in `requirements.txt` aktualisiert wurde, installierte Docker auf der Diskstation hartnäckig eine alte Version.
    *   **Lösung:** Erzwingen der Version `google-genai>=1.2.0`.

6.  **Problem: Das "Grounding Upgrade" & Die Syntax-Hölle (Runde 2)**
    *   **Aufgabe:** Einbau von echtem Web-Scraping und SerpAPI zur Qualitätssteigerung.
    *   **Fehler:** `SyntaxError: f-string: expecting '}'` in komplexen Listen-Generatoren (z.B. `c_sum`).
    *   **Ursache:** Python 3.11 erlaubt keine geschachtelten Anführungszeichen in F-Strings, wenn diese Backslashes oder komplexe Ausdrücke enthalten.
    *   **Lösung:** **RADIKALER VERZICHT auf F-Strings** in allen kritischen Logik-Bereichen. Umstellung auf einfache Schleifen und `.format()`.

7.  **Problem: `unterminated string literal (detected at line 203)`**
    *   **Ursache:** Einfache Anführungszeichen `'` in Kombination mit `\n` wurden im Container-Kontext falsch interpretiert.
    *   **Lösung:** **ULTIMATIVE SYNTAX:** Verwendung von **Triple Raw Quotes (`r"""..."""`)** für jeden einzelnen String, der Variablen oder Sonderzeichen enthält.

8.  **Problem: Analyse stoppt nach 5 Konkurrenten (Token Limit / Lazy LLM)**
    *   **Symptom:** Bei 9 Konkurrenten wurden nur die ersten 5 analysiert, der Rest fehlte.
    *   **Ursache:** Der riesige Prompt ("Analysiere alle 9...") überforderte das Kontext-Fenster oder führte zu Timeouts.
    *   **Lösung:** Umstellung auf **Map-Reduce**: Jeder Konkurrent wird in einem eigenen parallelen Task (`asyncio.gather`) analysiert. Erhöhung von `max_output_tokens` auf 8192.

9.  **Problem: `NameResolutionError` im Container**
    *   **Symptom:** Scraping schlug fehl ("Name or service not known").
    *   **Ursache:** Docker-Container nutzten den (instabilen) Host-DNS.
    *   **Lösung:** Explizites Setzen von Google DNS (`8.8.8.8`, `8.8.4.4`) in `docker-compose.yml`.

10. **Problem: `422 Unprocessable Entity` in Schritt 6 & 8**
    *   **Ursache:** Diskrepanz zwischen Frontend-Request (z.B. sendet `industries`) und Backend-Pydantic-Modell (erwartet `target_industries`).
    *   **Lösung:** Backend-Modelle exakt an die Frontend-Payloads angepasst.

11. **Problem: Leere Matrizen in der Conclusion**
    *   **Ursache:** Das LLM füllte das `availability`-Array nicht korrekt oder erfand eigene Produktnamen als Zeilenbeschriftung.
    *   **Lösung:** Extrem strikter Prompt ("KEINE Produktnamen", "GENAU einen Eintrag pro Kategorie") und detailliertes JSON-Schema.

12. **Problem: Blinde KI in Schritt 8 (Referenzen)**
    *   **Symptom:** Die Referenzanalyse lieferte nur generische, oft erfundene Branchen, anstatt echter Kunden.
    *   **Ursache:** Der Prompt bat die KI, "nach Referenzen zu suchen", ohne ihr eine Datengrundlage zu geben. Die KI hat halluziniert.
    *   **Lösung:** Implementierung einer **"Grounded" Referenz-Suche**.
    *   **Ergebnis:** Die Analyse basiert nun auf Fakten von der Webseite des Wettbewerbers.

13. **Problem: Informations-Overload (Text-Wüste)**
    *   **Symptom:** In Notion landeten hunderte Produkte und Landmines, aber man konnte nicht effektiv filtern (z.B. "Zeige alle Reinigungsroboter").
    *   **Lösung:** Einführung von **Semantic Clustering & Taxonomies**.
        *   Das Backend ordnet nun jedem Produkt eine feste Kategorie zu (z.B. *Cleaning*, *Logistics*).
        *   Jede Landmine erhält ein Themen-Tag (z.B. *Price*, *Support*, *Technology*).
    *   **Ergebnis:** Das Competitive Radar ist nun ein echtes BI-Tool. In Notion können nun "Board Views" nach Kategorien erstellt werden (Level 4 Relational Model).

### 🛡️ Die finale "Grounded" Architektur
... (Scraping/Map-Reduce etc. bleiben gleich) ...

### 📊 Relationaler Notion Import (Competitive Radar v3.0 - Level 4)
Um die Analyse-Ergebnisse optimal nutzbar zu machen, wurde ein intelligenter Import-Prozess nach Notion implementiert (`import_competitive_radar.py`).

*   **Architektur:** Vier vernetzte Datenbanken mit **semantischer Klassifizierung**:
    1.  **📦 Companies (Hub):** Stammdaten und strategische Zusammenfassung.
    2.  **💣 Landmines (Satellite):** Angriffsfragen, automatisch getaggt nach Themen:
        - *Price/TCO, Service/Support, Technology/AI, Performance, Trust/Reliability*.
    3.  **🏆 References (Satellite):** Echte Kundenprojekte (Grounded Truth).
    4.  **🤖 Products (Satellite):** Einzelne Produkte, klassifiziert nach Typ:
        - *Cleaning (Indoor/Outdoor), Transport/Logistics, Service/Gastro, Security, Software*.
*   **Dual-Way Relations:** Alle Datenbanken sind bidirektional verknüpft. Auf einer Produktkarte sieht man sofort den Hersteller; auf einer Herstellerkarte sieht man das gesamte (kategorisierte) Portfolio.

---
*Dokumentation aktualisiert am 11.01.2026 nach Implementierung der semantischen Klassifizierung (Level 4).*