Assistente de E-commerce Conversacional com Recuperação Híbrida
Juadsuarezsan/conversational-ecommerce-assistant
Busca híbrida + carrinho + refund logic em LangGraph para e-commerce de verdade
Ver no GitHubAgent em Python que implementa um assistente de compras conversacional para catálogos de 50K+ produtos (Rappi, Mercado Livre, Amazon). Combina recuperação híbrida (BM25 + embeddings densos + RRF + reranking), gerenciamento de carrinho stateful e escalação inteligente via LangGraph e Claude. Inclui pipeline de dados, múltiplos bancos vetoriais (Qdrant, pgvector, Chroma) e avaliação com RAGAS em 100 casos rotulados.
Instalação
npx convez-ai Juadsuarezsan/conversational-ecommerce-assistant1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Implementar camada conversacional em plataformas de compras (Rappi, MercadoLibre, Amazon)
- Recuperação semântica + keyword em catálogos grandes com reranking
- Gerenciamento de cart e lógica de reembolso com escalação a humano
- Benchmark de bancos vetoriais (Qdrant vs pgvector vs Chroma) em retrieval
Veredito

Projeto exemplar de retrieval + agentic IA em escala real. Ainda em planejamento, mas a arquitetura é sólida (hybrid search, reranking, multi-turn) e bem documentada para uso em e-commerce. Ideal para quem quer estudar ou clonar um assistente conversacional production-ready com eval robusta.
README
A tradução para o português deste README ainda está na fila.
Project 01 — Conversational E-commerce Assistant
Hybrid retrieval (BM25 + dense + RRF) + reranking + multi-turn LangGraph agent over a 50K-product catalog. Customer asks in natural language, manages cart, requests refund. The system decides when to escalate to human.
Industrial use case: Rappi, Mercado Libre, Walmart, Instacart, Amazon — conversational shopping.
What this project does
A real conversational layer over a real product catalog. The customer types in natural English (or Spanish), the system understands what they want, finds it across 50K products, manages their cart, handles refund logic, and escalates to a human when the model isn't confident enough. Every retrieval and every routing decision is measured against a 100-case hand-labeled eval set.
Architecture
Customer query
│
▼
[Intent Router] Claude with structured output (Pydantic)
│ classifies: product_search | cart_op | order_status | refund | escalate
│
├──► [Hybrid Retriever]
│ ├─ BM25 on product_name + aisle + department
│ ├─ Dense vector search in Qdrant (voyage-3 embeddings)
│ ├─ Reciprocal Rank Fusion → top 20
│ └─ Cohere Rerank v3 → top 5
│
├──► [Structured Retriever] SQL on Postgres
│ └─ filters: price, category, dietary, availability
│
├──► [Cart Manager] Pydantic stateful models
│ └─ add, remove, update_quantity, view, clear
│
├──► [Refund Handler]
│ └─ policy: if value > $100 OR sensitive category → escalate
│
└──► [Synthesizer] Claude
└─ response with product_id citations
Status
Planned. This README is the brief for Claude Code. The implementation plan follows the spec at /docs/portafolio_specs.md (Proyecto 1).
Roadmap to v1.0.0
- Data pipeline —
scripts/download_instacart.pypulls Kaggle dataset, builds processed parquet - Vector ingestion — embed product_name + aisle + department with voyage-3, index into Qdrant + pgvector + Chroma in parallel
- Hybrid retrieval module — BM25 (rank-bm25) + dense + RRF fusion
- Reranking — Cohere Rerank v3 wrapper with local fallback (
ms-marco-MiniLM-L-6-v2) - LangGraph agent — Intent Router → Retriever → Cart/Refund handlers → Synthesizer
- Eval set — 100 hand-labeled queries (30 lookup, 30 semantic, 20 comparative, 20 multi-turn)
- RAGAS evaluation — Faithfulness, Answer Relevance, Context Precision, Context Recall
- Vector DB benchmark — table comparing Qdrant vs pgvector vs Chroma on Precision@5, Recall@10, nDCG@10, p95 latency, $/1K queries
- Static demo — self-contained
demo/index.htmlwith 7 pre-baked queries, lives in this repo and works on GitHub Pages - Observability — LangSmith traces public, ≥30 example links in README
- Definition of Done — all 12 universal blocks + this project's 7 specific items pass
Stack (locked)
| Layer | Technology |
|---|---|
| Vector store (primary) | Qdrant 1.11+ via Docker |
| Vector stores (compared) | pgvector 0.7+, Chroma 0.5+ |
| Embeddings | Voyage AI voyage-3 ($0.12 / M tokens) or sentence-transformers/all-MiniLM-L6-v2 (local, free) |
| Reranking | Cohere Rerank v3 (rerank-english-v3.0, $1 / 1K queries) or cross-encoder/ms-marco-MiniLM-L-6-v2 (local) |
| Hybrid search | rank-bm25 (sparse) + dense + RRF |
| LLM | Claude Sonnet 4.5 (claude-sonnet-4-5) via Anthropic API |
| Orchestration | LangGraph 0.2+ StateGraph |
| State | PostgreSQL 16 (carts, orders, audit) |
| Session cache | Redis 7 with configurable TTL |
| Frontend | Static HTML demo (demo/index.html) — Claude-design aesthetic |
| Eval framework | RAGAS 0.2+ |
Quickstart (target — not yet runnable)
cd 01-ecommerce-assistant/
# 1. Download dataset (~200 MB, requires Kaggle CLI)
python scripts/download_instacart.py
# 2. Bring up infra
docker compose up -d # postgres + qdrant + redis
# 3. Ingest products into all 3 vector DBs
python -m src.ingestion.index_products --all-stores
# 4. Run evaluations
python -m src.eval.benchmark_vectordbs # table per store
python -m src.eval.ragas_eval # RAG quality metrics
# 5. Open the demo (static, no backend needed)
start demo/index.html # or `open` on macOS, `xdg-open` on Linux
# To get LIVE inference (instead of pre-baked), also start the API:
uvicorn src.api.main:app --port 8000
Definition of Done — project-specific
- Eval set of 100 hand-labeled queries with
product_idground truth and relevance scores 1-3 - Benchmark of 3 vector DBs reported with full metrics table in README
- Ablation: BM25-only vs dense-only vs hybrid (with and without reranking) reported
- Static demo deployed (
demo/index.html) with 7 pre-baked queries - Multi-turn conversation of ≥6 turns demonstrated in a GIF embedded in README
- Escalation policy documented in
docs/decisions.md - LangSmith public trace gallery linked from README
Plus the 12 universal blocks of the Definition of Done in /docs/portafolio_specs.md.
License
MIT.