Audience: engineers and power users who want to know how an emailed invoice becomes a posted NetSuite Vendor Bill — the “magic” explained.

The pipeline at a glance

An invoice flows through a chain of small, independently-testable stages:

Email → Triage (classify) → Draft + vendor resolve → OCR (Textract) → Structure (Claude) → PO match → Item match → Vendor coding → Project coding → Validate → Review → Post (SuiteTalk)

Every stage writes its result onto one VendorBillDraft.draft JSON blob (header + lines + totals), so any stage is inspectable and re-runnable.

1. Ingest & triage

• Gmail is watched two ways: a Pub/Sub push webhook (primary) + a 2-minute poll safety net (Gmail::PollInboxJob).
• Each email is classified by Claude (EmailTriage::Classifier, forced tool use) into invoice / spam / other with a confidence + recommended action → stored as a TriageDecision.
• Invoices with PDFs land in Needs review. Some cases are quarantined (e.g. Lightreach direct-pay CED/Greentech invoices, where the lease provider pays).
• Shadow mode: the agent never forwards or posts on its own — a human always confirms (SHADOW_MODE defaults on).

2. Draft creation & vendor resolution

NetsuiteBills::DraftInitiator:

• Resolves the vendor from the sender via trigram similarity against the NsVendor mirror, biased toward high-bill-count vendors so a junk/duplicate record doesn't out-score the real one.
• Pulls the chosen PDF from Gmail → S3 (Active Storage) → creates the VendorBillDraft (ocr_running) → enqueues OCR.

3. OCR — AWS Textract

NetsuiteBills::OcrJob runs Textract (async start-then-poll), storing raw text + tables + blocks in BillOcrResult. Status → ocr_done → structuring.

4. Structuring — Claude with forced tool use

NetsuiteBills::BillStructurer is the heart:

• Sends Textract text + tables and the PDF itself (inlined for vision) to Claude with a forced tool call (record_vendor_bill) whose schema is the code-owned contract.
• Extracts the header (vendor, invoice #, dates, terms, PO, currency, memo) + every line (description, product code, qty, rate, amount), plus coding hints: branch, job_type, ATTN name, and project_id.