# ProcureMind (PR-AGENT) — Project overview

This document describes **what this codebase is for**, **which technologies it uses**, and **how the pieces fit together**. It complements the short setup notes in the root `README.md`.

---

## 1. Purpose

**ProcureMind** is a **procurement assistant demo**: a chat-style web app that helps users describe what they need in natural language, **match that need to a structured catalogue** (UNSPSC-style commodity codes), **fill in a dynamic form** for the chosen item, and **preview purchase requisition (PR) line items**.

Typical user journey:

1. User describes a need (for example, office chairs or laptops) in the chat.
2. The backend uses an **LLM with tools** to search a **local SQLite catalogue** (full-text search). The model never invents codes; it only picks from tool results.
3. The UI may show **one best match**, **several candidates to choose from**, or **“not found”** with guidance.
4. After a commodity is selected, the app loads or generates a **form schema** for that code, collects answers, and can **build PR rows** for review/export.

It is aimed at **demos, pilots, and Hugging Face Spaces** — not a full enterprise procurement system (no ERP integration, approvals, or real vendor catalogs in this repo).

---

## 2. Technology stack

| Layer | Technology | Role |
|--------|------------|------|
| **Frontend** | React 18, TypeScript | SPA: chat thread, cards, forms, tables |
| **Frontend build** | Vite 5 | Dev server, HMR, production bundle |
| **Styling** | Tailwind CSS 3, PostCSS, Autoprefixer | Layout and components |
| **Backend** | Python 3.11, FastAPI, Uvicorn | JSON REST API under `/api` |
| **AI** | OpenAI Python SDK (`openai`) | Chat completions + **function/tool calling** (default model configurable, often `gpt-4o-mini`) |
| **Data / catalogue** | SQLite + **FTS5** (full-text index) | Searchable UNSPSC-derived catalogue |
| **ETL** | Pandas, openpyxl | Build `unspsc.db` from Excel (`server/build_db.py`) |
| **Production (Space / Docker)** | Docker multi-stage, **nginx** | Serves static React build; **reverse-proxies** `/api/` to Uvicorn on port 8000; listens on **7860** (Hugging Face convention) |

**Environment:** `OPENAI_API_KEY` is required for real LLM behavior. Optional: `OPENAI_MODEL`, `UNSPSC_DB_PATH`, `UNSPSC_XLSX_PATH` (see README).

---

## 3. How it works (architecture)

### 3.1 High-level diagram

```text
Browser (React)
    │  HTTP: /api/chat, /api/form-schema/…, /api/build-pr
    ▼
FastAPI (server/main.py)
    ├── run_agent()     → OpenAI + tools → search_catalog / get_commodity (SQLite)
    ├── get_or_create_schema() → form fields for commodity (may call OpenAI)
    └── build_pr_rows() → structured PR line rows from form answers
    ▼
SQLite (data/unspsc.db) — built from data/unspsc-english*.xlsx
```

**Local development:** Vite proxies `/api` to `http://127.0.0.1:8000` (see `vite.config.ts`).

**Docker / Hugging Face:** nginx serves the built SPA and forwards `/api/` to Uvicorn (see `nginx.conf`, `docker/start.sh`).

### 3.2 Main API surface (`server/main.py`)

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/health` | GET | Liveness check |
| `/api/chat` | POST | User message (and optional locked commodity code); returns JSON for UI (status, summary, candidates, analysis rows, errors) |
| `/api/form-schema/{commodity_code}` | GET | JSON schema for dynamic procurement form for that code |
| `/api/build-pr` | POST | Builds PR line rows from commodity code + dynamic field values + delivery options |

### 3.3 Agent (`server/agent.py`)

- **System prompt** defines ProcureMind rules: search with short phrases, retry searches, return `found` / `choose` / `not_found`, never invent codes.
- **Tools** expose catalogue operations (for example `search_catalog`, `get_commodity`) so the model reads the DB **only through defined functions**.
- If `OPENAI_API_KEY` is missing, the API returns a structured error instead of calling OpenAI.

### 3.4 Catalogue (`server/catalog.py`, `server/build_db.py`)

- Excel input follows a known UNSPSC export layout; `build_db` creates SQLite tables and an **FTS5** index for keyword search.
- Runtime queries use FTS + helpers (tokenization, stopwords) so long user sentences are turned into searchable queries.

### 3.5 Frontend (`src/`)

- **`App.tsx`** orchestrates chat state, thread items (analysis cards, disambiguation, forms), PR preview, and modals.
- **`src/api/chat.ts`** and **`src/api/form.ts`** call the backend (optional `VITE_API_BASE` for non-default API origin).

---

## 4. Repository layout (short)

| Path | Description |
|------|-------------|
| `src/` | React UI, components, API clients |
| `server/` | FastAPI app, agent, catalog, form schema, PR lines, DB build |
| `data/` | Source XLSX (LFS) and generated `unspsc.db` (after build) |
| `docker/start.sh` | Starts Uvicorn + nginx in the container |
| `Dockerfile` | Node build → Python runtime + nginx |
| `nginx.conf` | SPA + `/api` proxy |

---

## 5. Related links

- [Hugging Face Spaces config](https://huggingface.co/docs/hub/spaces-config-reference) (YAML in README frontmatter for the Space)

---

*Generated for maintainers and onboarding; adjust as the product evolves.*