Backend - Brand Product Search Engine (RAG API)

FastAPI service exposing the product catalog through:

• Browse - plain listing endpoints (/api/brands, /api/brands/{brand}/products)
• Search - pgvector semantic similarity search, no LLM (/api/search)
• Chat - full RAG: retrieval + local Ollama generation (/api/chat)
• Admin - trigger brand ingestion in the background (/api/catalog/generate)

Full setup, architecture, and troubleshooting steps are in the project documentation (docs/). This file is just a fast local reference.

Quick start

One-click (Windows)

Double-click start_backend.bat. It picks up venv\Scripts\python.exe if present (else falls back to system python), starts/creates the catalog_rag_postgres Docker container from docker-compose.yml, launches Ollama in the background if it's installed but not running, seeds sample data if needed, then starts uvicorn on port 8000.

Manual

cd backend
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env               # then edit DB_PASSWORD etc.

# Option A: already have a Postgres+pgvector catalog from the old project?
#   Just point .env at it (DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASSWORD) - done.
# Option B: starting fresh locally?
docker compose -f docker-compose.yml up -d
python scripts/seed_sample_data.py     # loads bundled sample catalogs instantly

uvicorn app.main:app --reload --port 8000

Then open http://localhost:8000/docs for interactive API docs, or run the frontend (../frontend/README.md) to use the React UI.

Pulling the local LLM (one-time)

ollama pull qwen2.5:1.5b
ollama serve   # if not already running as a service

Project layout

backend/
├── app/
│   ├── main.py                  # FastAPI app + router wiring
│   ├── infrastructure/settings.py
│   ├── api/
│   │   ├── schemas.py           # Pydantic models
│   │   ├── job_store.py         # in-memory background-job tracker
│   │   └── routers/             # health, brands, search, chat, catalog
│   ├── core/
│   │   ├── catalog_engine.py    # discovery + enrichment + image pipeline
│   │   └── ingestion.py         # thin wrapper used by API + CLI
│   └── services/
│       ├── embeddings_service.py  # sentence-transformers (lazy-loaded)
│       ├── ollama_service.py      # local LLM calls (catalog + RAG answers)
│       ├── vector_store.py        # pgvector reads/writes/SEMANTIC SEARCH
│       ├── rag_service.py         # RAG orchestration (NEW)
│       ├── image_search.py / s3_service.py / price_estimator.py / brand_registry.py
├── cli/ingest_brand.py           # CLI: ingest one brand end-to-end
├── scripts/seed_sample_data.py   # load bundled sample catalogs (no LLM needed)
├── data/seed_catalogs/*.json     # bundled sample catalogs (Parle, Cadbury, ...)
└── requirements.txt

Running tests

pytest -q