Files · Vertex AI Contract Pay App Extraction for SMB Construction

# Vertex AI Contract Pay App Extraction for SMB Construction
 
> Extract line items, retainage, and change orders from contractor payment applications using Vertex AI and automated repair.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build a production-grade document extraction pipeline with the `@reaatech/*` package family.
 
## What it does
 
SMB construction project managers upload a contractor payment application PDF via a web form. The pipeline extracts structured line items, retainage details, and change orders using Vertex AI Gemini, repairs malformed output with structured repair, flags low-confidence extractions for human review, tracks LLM costs, and persists multi-document project sessions.
 
## Architecture
 
```
PDF Upload → pdfjs-dist text extraction → Vertex AI Gemini (field extraction)
  → @reaatech/structured-repair-core (repair + validation)
  → @reaatech/confidence-router (confidence routing)
  → @reaatech/llm-cost-telemetry (cost tracking)
  → @reaatech/session-continuity (session persistence)
```
 
## Packages
 
### REAA (vendored)
- `@reaatech/media-pipeline-mcp-doc-extraction@0.3.0` — document extraction operations framework with provider delegation
- `@reaatech/structured-repair-core@1.0.0` — Zod schema–driven repair engine for malformed LLM outputs
- `@reaatech/confidence-router@0.1.1` — threshold-based decision engine for routing low-confidence extractions
- `@reaatech/llm-cost-telemetry@0.2.0` — cost tracking with CostSpan types and calculation utilities
- `@reaatech/session-continuity@0.1.0` — typed session lifecycle manager with token budget enforcement
 
### Third-party
- `pdfjs-dist@6.0.227` — Mozilla PDF.js for PDF text extraction
- `@google-cloud/vertexai@1.12.0` — Vertex AI Gemini model access
- `zod@3.25.76` — runtime schema validation
 
## Getting Started
 
```bash
pnpm install
cp .env.example .env   # then fill in your GCP project details
pnpm dev               # start the dev server on http://localhost:3000
```
 
## API
 
### `POST /api/upload`
 
Upload a PDF payment application for extraction.
 
**Request:** `multipart/form-data` with field `file` (PDF file).
 
**Response (200):**
```json
{
  "paymentApplication": { "id": "pa-001", "contractorName": "...", "lineItems": [...], ... },
  "routingDecision": { "needsReview": false, "decisions": [...] },
  "costSpan": { "id": "...", "provider": "google", "model": "gemini-2.5-flash", ... },
  "session": { "id": "...", ... }
}
```
 
**Response (400):** `{ "error": "A PDF file is required" }`
**Response (500):** `{ "error": "Extraction failed", "details": "..." }`
 
### Example
 
```bash
curl -F "file=@pay-app.pdf" http://localhost:3000/api/upload
```
 
## Environment Variables
 
| Variable | Description |
|----------|-------------|
| `GOOGLE_CLOUD_PROJECT` | GCP project ID for Vertex AI |
| `GOOGLE_CLOUD_LOCATION` | GCP location (default: us-central1) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON |
| `REVIEW_QUEUE_URL` | Optional webhook URL for low-confidence results |
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/lib/              libraries (pdf-extractor, cost-tracker, session-manager, vertex-provider)
src/services/         business logic (schemas, extraction pipeline, confidence checking)
tests/                vitest suite mirroring src/
packages/             API references for every dependency
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).