Semantic Product Search

Semantic product search engine: instead of matching keywords, it understands the intent of the query (embeddings + similarity search) and uses an agent to generate a recommendation from the catalog. The catalog is exposed as an MCP server and consumed by a separate agent.

🚧 Project under active development. Currently in Phase 1 · Backend setup. The architecture, demo, and design decision sections will be completed later, once a functional end-to-end flow exists.

Stack

• API: FastAPI

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

• Local models: Ollama

• Observability: LangSmith

• Config / validation: Pydantic + Pydantic Settings

• Database: Postgres + pgvector (local development: SQLite)

• Package manager: uv

Related MCP server: Vertex AI Search for Commerce MCP Server

Project structure

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/

Local setup

Requirements: Python >= 3.12 and uv installed.

# 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

Environment variables

⚠️ Never log the values of API keys or any secrets (ANTHROPIC_API_KEY, LANGSMITH_API_KEY, etc.). If you need to debug Settings, print only the names of the fields that failed, not their values — this is what app/core/config.py does when validating at startup.

Roadmap

Development is organized in phases (see Notion board):

1. Backend setup

2. Catalog + embeddings

3. Semantic search

4. Reviews + comments

5. MCP server

6. Agent + recommendation

7. REST API + streaming

8. Optimization

9. Frontend + publication

Architecture and design decisions

Pending — documented in Phase 9 (PROD-32), once the project has an end-to-end flow to describe the diagram, demo, and decisions (caching, retrieval + re-ranking, etc.) with real context.