# 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

```bash
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)

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

```bash
pytest -q
```