Files

Gitead 9efa8f6e0a docs+perf: document Google Vision key setup, consolidate OCR calls per screenshot

- README: step-by-step Google Cloud Vision API key creation and setup
  (enable API, create service-account key, place as google_credentials.json)
- ocrLocate: split into getOcrWords()/matchWordsForText() so a screenshot is
  OCR'd once and matched locally against multiple text targets, instead of a
  separate billed Vision API call per target (patient-row and Exam steps each
  cut from 2-3 calls down to 1)

2026-07-30 23:27:33 -04:00

2.9 KiB

Executable File

Raw Blame History

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

Go to console.cloud.google.com and select (or create) the project this service should use.
APIs & Services → Library → search for "Cloud Vision API" → click Enable (skip if already enabled).
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).
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

Move (don't just copy, to avoid leaving stray copies around) the downloaded JSON file into this folder (apps/PaymentOCRService/).

Rename it to exactly google_credentials.json — this is the filename .env already expects:

mv ~/Downloads/<your-downloaded-file>.json apps/PaymentOCRService/google_credentials.json

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)

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:

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.

2.9 KiB Executable File Raw Blame History