Ecommerce Catalog Agent

A conversational AI agent that answers product questions over an online store's catalog. It understands natural-language queries, finds matching products via hybrid search, and always reports live price and availability validated against the database.

Built as a tool-calling (ReAct) agent with a strict trust boundary: the model decides what to say and which products to show, but code owns the customer-facing numbers — so a hallucinated or injected price can never reach the user.

Features

• Hybrid retrieval — BM25 (keyword) + vector embeddings (semantic) + Reciprocal Rank Fusion + cross-encoder reranking. Catches word forms and synonyms that exact matching misses (e.g. "взуття для бігу" → running shoes).
• Filter-first — hard constraints (price, stock) are applied in SQL to build the candidate set before semantic ranking, avoiding the classic "top-k then filter → zero results" trap.
• Two sources of truth — PostgreSQL is authoritative for volatile fields (price/stock); the vector index is a search cache only. Price and stock are re-fetched live before every answer.
• Structured-output contract — the agent finishes by calling present_results with product SKUs + prose; price/stock are filled by code from live SQL. The model has no field to write a number into → containment against hallucination and prompt injection ("attacker needs capability, not just instruction").
• Bounded agent loop — independent stoppers (max iterations, token budget, latency) plus deterministic, score-based escalation to a human operator (on the reranker confidence, never the model's self-report).
• Conversation memory — per-session history for multi-turn context.
• Custom MCP server — the catalog tools are exposed over the Model Context Protocol, so one contract serves the agent, an internal copilot, and Claude Desktop.
• Multi-channel — a FastAPI /chat service, a Telegram bot via n8n (webhook), and a standalone aiogram bot (long-polling).
• Eval harness — a golden set scored with Recall@K / MRR to catch retrieval regressions with numbers, not vibes.

Architecture

  Customer channels  (Telegram / web / Claude Desktop)
            │
        [n8n]  webhook intake + routing ── low confidence ──► human operator
            │
        [FastAPI /chat]  models warmed at startup
            │
        [ReAct agent loop]  bounded: max_iter / budget / latency
            │   parse → retrieve → validate → respond
            ▼
        [catalog tools]  (also exposed as a custom MCP server)
          search_products  → hybrid BM25 + vector + rerank, filter-first
          get_live_price / check_stock  → live SQL
            │
   PostgreSQL (price/stock = truth)   +   Chroma (search cache)
            ▲
   n8n schedule: XML feed → parse → upsert → re-embed

Tech stack

Python · FastAPI · OpenAI (LiteLLM-swappable) · PostgreSQL · Chroma · BM25 · sentence-transformers · cross-encoder reranker · custom MCP server · n8n · aiogram

Quick start

pip install -r requirements.txt
cp .env.example .env            # fill OPENAI_API_KEY + PG_*

# create the schema, load the sample feed (builds the hybrid index)
psql -d catalog -f schema.sql
python ingest.py

# ask from the CLI
python agent.py "червоні кросівки до 2000 в наявності"

# or run the HTTP service
uvicorn api:app --port 8000     # → http://localhost:8000/docs

# or the Telegram bot (set TELEGRAM_BOT_TOKEN in .env)
python bot.py

Project layout

File	What
agent.py	ReAct agent loop, bounded stoppers, structured-output contract
retrieval.py	hybrid retrieval (BM25 + vector + RRF + cross-encoder) + confidence scores
catalog_tools.py	read-only catalog tools + structured get_facts for live validation
server.py	the catalog tools exposed as a custom MCP server
api.py	FastAPI /chat service (per-session memory, warmup at startup)
bot.py	standalone Telegram bot (aiogram, long-polling)
ingest.py	XML feed → PostgreSQL + rebuild the hybrid index
eval.py	retrieval eval on a golden set (Recall@K / MRR)
n8n/workflow.json	Telegram → /chat → reply + escalation routing

Design notes

• Why hybrid, not pure vector — vector search alone can't honor exact filters (price/stock) or exact tokens (SKUs, model codes); BM25 + structured SQL cover what embeddings miss.
• Why the vector index is never the source of price/stock — it's rebuilt on a schedule, so its copy of volatile fields is stale by design; the answer always re-validates against SQL.
• Why MCP — the catalog tools are reused across consumers (the agent, an internal copilot, Claude Desktop): one contract, many clients.

---

The sample catalog and prompts are in Ukrainian; the agent replies in the customer's language.