Semantic Product Search

Buscador semántico de productos: en vez de matchear keywords, entiende la intención de la query (embeddings + similarity search) y usa un agente para generar una recomendación sobre el catálogo. El catálogo se expone como servidor MCP y es consumido por un agente separado.

🚧 Proyecto en desarrollo activo. Actualmente en Fase 1 · Setup backend. Las secciones de arquitectura, demo y decisiones de diseño se completarán más adelante, cuando exista un flujo end-to-end funcional.

Stack

• API: FastAPI

• Agente / orquestación: LangChain + LangChain Anthropic (Claude)

• Modelos locales: Ollama

• Observabilidad: LangSmith

• Config / validación: Pydantic + Pydantic Settings

• Base de datos: Postgres + pgvector (en desarrollo local: SQLite)

• Gestor de paquetes: uv

Related MCP server: Product MCP Server

Estructura del proyecto

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/

Setup local

Requisitos: Python >= 3.12 y uv instalado.

# 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

Variables de entorno

⚠️ Nunca loguees los valores de las API keys ni de ningún secreto (ANTHROPIC_API_KEY, LANGSMITH_API_KEY, etc.). Si necesitas debuggear Settings, imprime únicamente los nombres de los campos que fallaron, no sus valores — así lo hace app/core/config.py al validar al arranque.

Roadmap

El desarrollo está organizado en fases (ver tablero de Notion):

1. Setup backend

2. Catálogo + embeddings

3. Búsqueda semántica

4. Reviews + comentarios

5. Servidor MCP

6. Agente + recomendación

7. REST API + streaming

8. Optimización

9. Frontend + publicación

Arquitectura y decisiones de diseño

Pendiente — se documenta en la Fase 9 (PROD-32), una vez el proyecto tenga un flujo end-to-end para poder describir el diagrama, la demo y las decisiones (caché, retrieval + re-ranking, etc.) con contexto real.