# Payment OCR Service (FastAPI)

FastAPI wrapper around a Google Cloud Vision OCR pipeline. Used by the Backend for
payment/EOB document extraction (`/extract/json`, `/extract/csv`, `/extract/pdf/json`)
and by the Windows Type Agent for exact-pixel text location (`/extract/words`).

## 1) Prereqs

- Python 3.
- A Google Cloud Vision service-account key (see step 2 below).

## 2) Create a Google Cloud Vision API key

1. Go to [console.cloud.google.com](https://console.cloud.google.com) and select (or
   create) the project this service should use.
2. **APIs & Services → Library** → search for **"Cloud Vision API"** → click **Enable**
   (skip if already enabled).
3. **IAM & Admin → Service Accounts** → either pick an existing service account for
   this app, or **Create Service Account** (any name, e.g. `ocr-service`; no special
   roles are required beyond default — Vision API access comes from the API being
   enabled on the project, not a role grant).
4. Open that service account → **Keys** tab → **Add Key → Create new key → JSON**.
   This immediately downloads a `.json` file to your browser's Downloads folder —
   **this is the only time the private key content is shown**, so keep the file safe
   (a password manager or secure backup, not just Downloads).

## 3) Install the key

1. Move (don't just copy, to avoid leaving stray copies around) the downloaded JSON
   file into this folder (`apps/PaymentOCRService/`).
2. Rename it to exactly `google_credentials.json` — this is the filename `.env`
   already expects:
   ```bash
   mv ~/Downloads/<your-downloaded-file>.json apps/PaymentOCRService/google_credentials.json
   ```
3. This filename is gitignored on purpose — **never commit it**. If a key is ever
   accidentally exposed (committed, pasted, screenshotted), go back to the Keys tab
   in step 2 and delete it, then generate a new one.

## 4) Install & run (local)

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 5003
```

Or just `python main.py` — it reads `HOST`/`PORT` from `.env` (defaults to
`0.0.0.0:5003`) and `GOOGLE_APPLICATION_CREDENTIALS=google_credentials.json` from the
same file.

Verify it's working:
```bash
curl localhost:5003/health
# should report "GOOGLE_APPLICATION_CREDENTIALS set: True"
```

## 5) Endpoints

- `POST /extract/json`, `/extract/csv`, `/extract/csvtext` — payment/EOB document
  images → structured rows (deskew + line-grouping + domain extraction pipeline).
- `POST /extract/pdf/json` — same, for remittance-advice PDFs.
- `POST /extract/words` — raw OCR only: a flat list of every detected word with its
  exact pixel bounding box (`left`, `top`, `w`, `h`, `cx`, `cy`). Used by the Windows
  Type Agent to click exact text locations instead of relying on an AI-vision
  estimate.
- `GET /health`, `GET /status` — liveness/credential check, active/queued job counts.