Files

Floke 6a7d56a9c9 feat(competitor-analysis): Fix 404, SDK compatibility, and update docs

Resolved multiple issues preventing the 'competitor-analysis' app from running and serving its frontend:

1.  **Fixed Python SyntaxError in Prompts:** Corrected unterminated string literals and ensure proper multi-line string formatting (using .format() instead of f-strings for complex prompts) in .
2.  **Addressed Python SDK Compatibility (google-generativeai==0.3.0):**
    *   Removed  for  and  by adapting the orchestrator to pass JSON schemas as direct Python dictionaries, as required by the older SDK version.
    *   Updated  with detailed guidance on handling / imports and dictionary-based schema definitions for older SDKs.
3.  **Corrected Frontend Build Dependencies:** Moved critical build dependencies (like , , ) from  to  in .
    *   Updated  to include this  pitfall, ensuring frontend build tools are installed in Docker.
4.  **Updated Documentation:**
    *   : Added comprehensive lessons learned regarding  dependencies, Python SDK versioning (specifically  and  imports for ), and robust multi-line prompt handling.
    *   : Integrated specific details of the encountered errors and their solutions, making the migration report a more complete historical record and guide.

These changes collectively fix the 404 error by ensuring the Python backend starts correctly and serves the frontend assets after a successful build.

2026-01-10 09:10:00 +00:00

4.5 KiB

Raw Blame History

Migration Report: Competitor Analysis Agent

Status: Jan 09, 2026

The competitor-analysis application has been successfully migrated to the local Docker stack and integrated into the gemini-gateway (Nginx).

1. Vorgehen (Process)

Dateistruktur:
- Erstellung des Verzeichnisses competitor-analysis-app/.
- Kopie aller Dateien aus dem Original-Verzeichnis.
Frontend-Anpassung:
- vite.config.ts: base: './' gesetzt, um korrektes Routing unter dem Sub-Pfad /ca/ zu ermöglichen.
- geminiService.ts: Direkte Aufrufe an @google/genai entfernt. Alle Funktionen nutzen nun fetch() an den neuen Python-Backend-Endpunkt /api/....
Backend-Orchestrator (Python/FastAPI):
- Erstellung von competitor_analysis_orchestrator.py.
- Portierung aller Prompts und Schemata aus dem TypeScript-Code in Python (Pydantic & Google Generative AI SDK).
- Implementierung einer robusten JSON-Parsing-Logik (parse_json_response), die Markdown-Blöcke entfernt und inkonsistente LLM-Antworten korrigiert.
- Implementierung einer Modell-Kandidaten-Liste (gemini-1.5-pro mit Fallback), um regionale Verfügbarkeit sicherzustellen.
- Integration von StaticFiles, um das fertig gebaute Frontend direkt über den Python-Server auszuliefern.
Docker-Integration:
- Dockerfile: Multi-Stage Build (Node.js zum Bauen, Python zum Ausführen).
- docker-compose.yml: Neuer Service competitor-analysis hinzugefügt, inklusive Volume-Mounts für API-Keys und Live-Debugging des Orchestrators.
- nginx-proxy.conf: Routing für /ca/ konfiguriert.

2. Next Steps

Persistenz: Aktuell werden Analysen nur im App-State (RAM) gehalten. Eine Anbindung an die SQLite-Datenbank (ähnlich wie beim b2b-app) wäre sinnvoll, um Analysen zu speichern und später wieder aufzurufen.
Fehlermanagement: Verfeinerung der Error-Handler im Frontend, um spezifische Backend-Fehler (z.B. API-Limits) besser anzuzeigen.
Weitere Schritte im Orchestrator: Implementierung der verbleibenden Steps (4-8), falls diese noch nicht vollständig in Python abgebildet sind (derzeit sind Step 1, 2, 3, 4, 5, 6, 7 und 8 bereits im Code vorbereitet oder implementiert).

3. Lessons Learned

Python SDK-Versionskonflikte (google-generativeai==0.3.0): Das im Projekt verwendete Python SDK (google-generativeai Version 0.3.0) ist nicht mit neueren API-Schnittstellen kompatibel.
- ImportError: cannot import name 'Schema' from 'google.generativeai.types' und ImportError: cannot import name 'Content' from 'google.generativeai.types' treten auf, da diese Klassen in dieser SDK-Version an diesen Importpfaden nicht existieren oder anders implementiert sind.
- Lösung: Schemata müssen direkt als Python-Dictionaries an die generation_config übergeben werden. Alle Importe für Schema und Content müssen entfernt werden.
Frontend Build (package.json devDependencies): Build-Tools wie vite, @vitejs/plugin-react und typescript müssen in den dependencies der package.json stehen, nicht in devDependencies. Andernfalls schlägt npm install im Docker-Build fehl, was zu einem leeren oder fehlenden dist-Ordner und einem 404-Fehler des Python-Servers führt.
Syntaxfehler in mehrzeiligen Prompts (f-strings): Besonders bei älteren Python-Versionen und komplexen mehrzeiligen Prompts mit f-strings können subtile Fehler (z.B. falsch platzierte Anführungszeichen oder unbeabsichtigter deutscher Text in englischen Prompts) zu SyntaxError: unterminated string literal führen.
- Lösung: Die robusteste Methode ist, mehrzeilige Prompts als Liste von Strings zu definieren und mit "\n".join() zusammenzufügen.
SDK-Unterschiede: Das Python SDK (google-generativeai) verhält sich bei der Schema-Validierung strikter als die JS-Variante. Prompts mussten leicht angepasst werden, um sicherzustellen, dass die AI wirklich valides JSON liefert.
Vite Base Path: Ohne base: './' in vite.config.ts schlagen alle Asset-Requests fehl, wenn die App hinter einem Proxy unter /ca/ läuft.
Double JSON Trap: LLMs neigen dazu, JSON in Markdown zu packen. Der Backend-Orchestrator muss dies proaktiv bereinigen, bevor json.loads() aufgerufen wird.
Proxy-Routing: Der Trailing Slash in Nginx (proxy_pass http://.../) ist kritisch, damit die Pfade innerhalb der App korrekt aufgelöst werden.

Dokumentation erstellt am 09.01.2026