# 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

```bash
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.*