Local setup

Start here: Your setup checklist — full step-by-step including Tesseract, Docker, and GCP.

Exact steps to run the local MVP on Windows.

Prerequisites

• Python 3.11+
• (Optional) Tesseract on PATH for tesseract parser
• (Optional) GCP credentials in .env for Document AI and Gemini parsers

Step 0 — Environment

cd C:\path\to\faxautomation
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev,local]"
copy .env.example .env

Step 1 — Run API + UI

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

Open http://127.0.0.1:8000

Step 2 — First run (real parsers only)

1. Enable Google Document AI Layout + Vertex Gemini Extractor (and Tesseract in Docker)
2. Upload a redacted PDF
3. Click Run extraction

Step 3 — Enable GCP parsers (when creds ready)

Add to .env:

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

Authenticate:

gcloud auth application-default login

Refresh the page — Document AI and Gemini checkboxes become enabled.

Step 4 — Run tests after each change

pytest

GCP integration tests skip automatically without creds.

Step 5 — Documentation preview

mkdocs serve -a 127.0.0.1:8001

Open http://127.0.0.1:8001

Or use .\scripts\serve-docs.ps1

Troubleshooting

Issue	Fix
GCP parsers greyed out	Fill .env vars; restart uvicorn
Tesseract greyed out	Install Tesseract; add to PATH
400 Parser disabled	Do not select disabled parsers
No Python	Install from python.org; disable Windows Store alias

HIPAA

Use synthetic or redacted PDFs only in local dev. Never commit real patient documents.