Skip to content

Your setup checklist — step by step

Complete these in order. Check each box before moving on.

You need: Windows PC, Google Cloud account (ready), this repo cloned.

Phase 1 — Python app (15 minutes)

1.1 Install Python (if not done)

  1. Download Python 3.11+ (you have 3.14 — OK)
  2. During install: check “Add python.exe to PATH”
  3. Disable Windows Store alias: Settings → Apps → Advanced app settings → App execution aliases → turn off python.exe / python3.exe stubs

Verify:

python --version

1.2 Create virtual environment

cd "C:\Users\Toward Health\Desktop\Workspace\faxautomation"
python -m venv .venv
.\.venv\Scripts\Activate.ps1

If activation is blocked:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

1.3 Install dependencies

pip install -U pip
pip install -e ".[dev,local,gcp]"

1.4 Copy environment file

copy .env.example .env

(not committed — holds secrets locally)

1.5 Run tests

pytest

Expected: 35 passed, 1 skipped (GCP test skips until creds set).

1.6 Start the local UI

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

Open http://127.0.0.1:8000

1.7 First demo

  1. Select enabled parsers (docai + gemini-extract; tesseract in Docker)
  2. Upload a redacted PDF
  3. Run extraction — analyte table + Elation preview JSON

Phase 2 — Tesseract (local OCR)

You have two options. Pick one.

Option A — Install on Windows (simpler for daily dev)

  1. Install Tesseract: powershell winget install UB-Mannheim.TesseractOCR Or: Tesseract Windows installer
  2. Add to PATH (if tesseract not found):
  3. Default folder: C:\Program Files\Tesseract-OCR
  4. Settings → System → About → Advanced system settings → Environment Variables
  5. Add that folder to Path → OK
  6. Restart PowerShell
  7. Verify: powershell tesseract --version
  8. Restart uvicorn and refresh http://127.0.0.1:8000 — Tesseract OCR checkbox should be enabled.

Note: Current tesseract plugin extracts embedded PDF text via pypdf. For scanned fax PDFs (image-only), install optional raster support:

pip install pdf2image pytesseract

Also install Poppler for Windows and add bin to PATH.

Option B — Docker (streamlined — Tesseract + Poppler preinstalled)

Best when you want one command and identical Linux tooling without fighting Windows PATH.

Prerequisites: Docker Desktop

cd "C:\Users\Toward Health\Desktop\Workspace\faxautomation"
copy .env.example .env
# Edit .env with GCP values when ready (Phase 3)

docker compose up --build

Open http://127.0.0.1:8000

  • Tesseract is inside the container — no Windows install needed
  • To mount GCP credentials for Doc AI / Gemini, see comments in docker-compose.yml

Stop: Ctrl+C then docker compose down

Phase 3 — Google Cloud (Document AI + Vertex Gemini)

Your project: fax-automation-toward-health (use this project ID in .env).

Which APIs to enable (important)

Search in API Library Enable? Service name Use for this project
Document AI API Yes documentai.googleapis.com OCR / layout (you enabled this)
Vertex AI API OR Agent Platform API Yes aiplatform.googleapis.com Gemini on Vertex — this is what we use
Gemini API (“for Developers” / AI Studio) No Developer / consumer path Not for PHI — no API key from aistudio.google.com

Your screenshot “Agent Platform API” is correct. Google renamed the console entry; the service name aiplatform.googleapis.com is Vertex AI. Click Enable on that page.

Do not enable the marketplace result “Gemini API — Build with latest models… for Developers”. That is Google AI Studio / API-key path, which our code and HIPAA rules explicitly avoid.

Direct links (project must be fax-automation-toward-health):

If “Vertex AI API” search shows nothing, open Agent Platform API — confirm Service name = aiplatform.googleapis.com → Enable.

3.1 Project and BAA

  1. Confirm project fax-automation-toward-health is under your org’s signed GCP BAA
  2. Copy Project ID (top bar or IAM → Settings) — usually same as project name

3.2 Enable APIs (Console UI only)

  1. Go to APIs & Services → Library
  2. Enable Document AI API (done)
  3. Search aiplatform → open Vertex AI API or Agent Platform API → Enable
  4. Optional: APIs & Services → Enabled APIs — verify both appear

3.3 Create Document AI processor (Console UI)

  1. Open Document AI → Processor gallery
  2. Region (left sidebar): keep **us** selected (you already have this — correct for United States)
  3. Step 3.3.3 — which processor to click:
Priority Click this card Why
1st choice Layout Parser Best for lab tables, reading order, fax layouts (matches our plan)
2nd choice Document OCR Simpler/cheaper; fine for first test
Skip for now Custom Extractor, Form Parser, Splitter Add later when tuning specific lab vendors
  1. Click the card → Create processor → confirm region **us**
  2. After create: Document AI → My processors → open your processor → copy Processor ID

Where is “region”? On the Processor gallery page, look at the left sidebar under the search box — section labeled Region. Your screenshot shows a chip **us** at the top of that list. That is the US multi-region bucket for Document AI (not us-central1 or us-east1 individually).

Do all US regions work? Not interchangeably. Rules:

  • The processor lives in one region (e.g. us or us-central1).
  • Your .env **DOCAI_LOCATION must exactly match** that region.
  • **us** (multi-region) is the easiest default for US — use DOCAI_LOCATION=us.
  • Do not pick eu or asia-* unless you have a specific reason.

Example processor URL:

.../locations/us/processors/abc123...

→ DOCAI_LAYOUT_PROCESSOR_ID=abc123... and DOCAI_LOCATION=us

Vertex Gemini is separate: use VERTEX_LOCATION=us-central1 in .env (Gemini models run on Vertex, not the Document AI us location).

3.4 Credentials — Console UI (no gcloud auth on your PC)

Use a service account so the app authenticates without local gcloud login.

  1. IAM & Admin → Service Accounts → Create service account
  2. Name: fax-automation-local (or similar)
  3. Grant roles (minimum for MVP trials):
  4. Document AI API User (or Document AI Editor)
  5. Vertex AI User
  6. Create service account → open it → Keys tab → Add key → JSON → download
  7. Save JSON outside git, e.g. C:\Users\Toward Health\Desktop\Workspace\faxautomation\secrets\gcp-sa.json
  8. File is in .gitignore via secrets.json pattern — never commit
  9. In .env add:
GOOGLE_APPLICATION_CREDENTIALS=C:\Users\Toward Health\Desktop\Workspace\faxautomation\secrets\gcp-sa.json
GCP_PROJECT_ID=fax-automation-toward-health
DOCAI_LOCATION=us
DOCAI_LAYOUT_PROCESSOR_ID=paste-processor-id-here
VERTEX_LOCATION=us-central1
VERTEX_GEMINI_MODEL=gemini-2.5-flash
  1. Restart the app (uvicorn or Docker)

Alternative (if you prefer gcloud on PC): skip service account JSON and run gcloud auth application-default login — see Phase 3.4b below.

3.4b Optional — local gcloud auth (instead of service account JSON)

gcloud auth login
gcloud config set project fax-automation-toward-health
gcloud auth application-default login

3.5 Fill .env (summary)

Edit .env in the repo root:

GCP_PROJECT_ID=your-project-id
GCP_LOCATION=us-central1
DOCAI_LAYOUT_PROCESSOR_ID=your-processor-id
VERTEX_GEMINI_MODEL=gemini-2.5-flash

For Document AI, if your processor is in region us, set:

GCP_LOCATION=us

3.6 Restart app and verify UI

# Stop uvicorn (Ctrl+C), then:
uvicorn faxautomation.main:app --reload

Refresh http://127.0.0.1:8000

Parser Should show
Google Document AI Layout Enabled (if .env filled)
Vertex Gemini Extractor Enabled (if GCP_PROJECT_ID set)

3.7 Test GCP parsers

  1. Upload a redacted lab PDF
  2. Select docai + gemini-extract
  3. Run extraction
  4. Compare results in the analyte table

3.8 Run GCP-marked test (optional)

$env:GCP_PROJECT_ID="your-project-id"
$env:DOCAI_LAYOUT_PROCESSOR_ID="your-processor-id"
pytest -m gcp -v

Phase 4 — Documentation site

pip install -e ".[dev]"   # includes mkdocs
.\scripts\serve-docs.ps1

Open http://127.0.0.1:8001

Phase 5 — What comes next (not local MVP)

Step When Doc
Elation sandbox results[] test Before real Elation integration scripts/elation-sandbox/README.md
MA time study Parallel brainstorming/intake-inventory.md
Cloud deploy After local accuracy OK docs/roadmap/local-to-cloud.md
VPC / HIPAA egress Before production PHI SECURITY.md

Quick reference

Goal Command
Activate venv .\.venv\Scripts\Activate.ps1
Tests pytest
Run app (native) uvicorn faxautomation.main:app --reload
Run app (Docker) docker compose up --build
Docs .\scripts\serve-docs.ps1
Tesseract on PATH? tesseract --version
GCP logged in? gcloud auth application-default print-access-token

HIPAA reminders

  • Local dev: redacted or synthetic PDFs only
  • Never commit .env, samples/, or real fax files
  • Vertex AI in GCP under BAA — never Google AI Studio / consumer Gemini for PHI
  • Production: complete SECURITY.md before real patient data

Troubleshooting

Problem Fix
tesseract greyed out in UI Install Tesseract + PATH; or use docker compose up
GCP parsers greyed out Fill .env; run gcloud auth application-default login; restart uvicorn
Doc AI 404 / permission Check processor ID, region (GCP_LOCATION), API enabled
Vertex error / quota Enable Vertex AI API; check model name in region
pytest import errors Activate .venv; pip install -e ".[dev,local,gcp]"
Docker GCP auth Mount ADC file — see docker-compose.yml comments
Scanned PDF no text Install Poppler + pdf2image (Windows) or use Docker