Semantic Product Search

Semantische Produktsuche: Statt Keywords zu matchen, versteht sie die Intention der Query (Embeddings + Similarity Search) und nutzt einen Agenten, um eine Empfehlung über den Katalog zu generieren. Der Katalog wird als MCP-Server bereitgestellt und von einem separaten Agenten konsumiert.

🚧 Projekt in aktiver Entwicklung. Derzeit in Phase 1 · Backend-Setup. Die Abschnitte zu Architektur, Demo und Designentscheidungen werden später vervollständigt, sobald ein funktionsfähiger End-to-End-Fluss existiert.

Stack

• API: FastAPI

• Agent / Orchestrierung: LangChain + LangChain Anthropic (Claude)

• Lokale Modelle: Ollama

• Observability: LangSmith

• Konfiguration / Validierung: Pydantic + Pydantic Settings

• Datenbank: Postgres + pgvector (bei lokaler Entwicklung: SQLite)

• Paketmanager: uv

Related MCP server: Vertex AI Search for Commerce MCP Server

Projektstruktur

app/
  main.py           # entrypoint de la API
  api/routes.py      # rutas HTTP
  catalog/           # ingesta + modelos de datos del catálogo
  search/             # embeddings + similarity search
  reviews/
  mcp_server/         # servidor MCP (expone el catálogo/búsqueda como tools)
  agent/               # agente que consume el MCP y arma la recomendación
  core/
    config.py         # settings (variables de entorno)
    db.py              # conexión a Postgres/pgvector
  models/
    schemas.py         # modelos Pydantic compartidos
tests/

Lokales Setup

Voraussetzungen: Python >= 3.12 und uv installiert.

# Instalar dependencias
uv sync

# Configurar variables de entorno
cp .env.example .env
# completar ANTHROPIC_API_KEY y LANGSMITH_API_KEY en .env

# Correr el entrypoint
uv run python -m app.main

Umgebungsvariablen

⚠️ Protokolliere niemals die Werte von API-Keys oder anderen Geheimnissen (ANTHROPIC_API_KEY, LANGSMITH_API_KEY, usw.). Wenn du Settings debuggen musst, gib nur die Namen der fehlgeschlagenen Felder aus, nicht ihre Werte — so macht es app/core/config.py bei der Validierung beim Start.

Roadmap

Die Entwicklung ist in Phasen organisiert (siehe Notion-Board):

1. Backend-Setup

2. Katalog + Embeddings

3. Semantische Suche

4. Bewertungen + Kommentare

5. MCP-Server

6. Agent + Empfehlung

7. REST-API + Streaming

8. Optimierung

9. Frontend + Veröffentlichung

Architektur und Designentscheidungen

Ausstehend — wird in Phase 9 (PROD-32) dokumentiert, sobald das Projekt einen End-to-End-Fluss hat, um das Diagramm, die Demo und die Entscheidungen (Caching, Retrieval + Re-Ranking, usw.) mit echtem Kontext beschreiben zu können.