Add document-extraction intake: vision PDF read + live reveal

The intake step now reads a real invoice PDF, closing the end-to-end loop
(document → extract → match → investigate → human gate → ERP).

- lib/invoice-pdf.ts renders each seeded invoice to a real PDF on demand
  (app/api/pdf/[id]); no stored binary, can't drift from the data.
- lib/extract.ts: vision extraction (PDF → schema-validated Invoice) via the
  Anthropic SDK + Sonnet, ported from the sibling ai-invoice-parser repo.
- The run streams a phase-0 intake event; the UI shows the actual PDF (pdf.js)
  with a scan sweep and the extracted fields filling in (components/
  extraction-reveal.tsx, pdf-document.tsx).
- Safety: extraction is shown, but the pipeline runs on the trusted seeded
  record, so a model misread degrades the reveal, never the verdicts. Fails open
  on timeout/error.
- UX: PDF preview on select/hover (header follows), optimistic running state,
  trace auto-follow that yields to manual scroll, queue lock during a run.
- Strip unsupported JSON-schema keywords (minimum/maximum) for the structured-
  output model; runtime Zod still enforces them.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DylanMerigaud

README.md

@@ -1,40 +1,42 @@
 # ledgerloop
 
-An invoice **procure-to-pay** pipeline: 2/3-way matching, approval routing, and reconciliation, with a live execution trace you watch as it runs.
+An invoice **procure-to-pay** pipeline: a vendor PDF comes in, gets extracted, matched, routed, and reconciled, with a live execution trace you watch as it runs.
 
-The money decisions are deterministic code. An AI agent is used for one thing — investigating a flagged exception, where the answer lives in messy records and there's a real judgment to make. It recommends; a human decides; nothing posts until they do. Built with [Mastra](https://mastra.ai).
+AI is used in the two places it earns its keep, and nowhere else. **Extraction** reads the messy vendor PDF into structured data (vision). **Investigation** judges a flagged exception against unstructured records, recommends, and a human decides. Everything in between — matching, approval tiering, reconciliation — is deterministic code, because a payment decision must be exact and repeatable, never a model's guess. Nothing posts until a human approves. Built with [Mastra](https://mastra.ai).
 
 ### ▶︎ [Try the live demo →](https://ledgerloop-eta.vercel.app/)
 
-[![CI](https://github.com/DylanMerigaud/ledgerloop/actions/workflows/ci.yml/badge.svg)](https://github.com/DylanMerigaud/ledgerloop/actions/workflows/ci.yml) ![Mastra](https://img.shields.io/badge/agent-Mastra-000000) ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6) ![model](https://img.shields.io/badge/Claude-Haiku_4.5-4F46E5) ![database](https://img.shields.io/badge/database-Supabase-3ECF8E)
+[![CI](https://github.com/DylanMerigaud/ledgerloop/actions/workflows/ci.yml/badge.svg)](https://github.com/DylanMerigaud/ledgerloop/actions/workflows/ci.yml) ![Mastra](https://img.shields.io/badge/agent-Mastra-000000) ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6) ![models](https://img.shields.io/badge/Claude-Sonnet_4.6_%2B_Haiku_4.5-4F46E5) ![database](https://img.shields.io/badge/database-Supabase-3ECF8E)
 
 ---
 
 ## What it does
 
 ```mermaid
 flowchart LR
-    I([Invoice]) --> M[Matching<br/>deterministic]
+    PDF([Vendor PDF]) --> X[Extraction AI<br/>vision → structured]
+    X --> M[Matching<br/>deterministic]
     M --> V{Verdict?}
 
     V -- "clean" --> AUTO[Auto-approve<br/>straight-through]
     V -- "duplicate" --> BLK[Blocked<br/>never posted]
-    V -- "exception" --> INV[Investigator AGENT<br/>reads messy records,<br/>recommends]
+    V -- "exception" --> INV[Investigator AI<br/>reads messy records,<br/>recommends]
 
     INV --> R[Approval routing<br/>deterministic tier]
     R --> H{{Human decision<br/>Approve / Reject}}
     H -- "approve" --> POST
     H -- "reject" --> REJ[Rejected<br/>not posted]
     AUTO --> POST[Reconciliation → ERP<br/>vendor bill + GL]
 
-    classDef agent fill:#EEF2FF,stroke:#4F46E5,color:#0A0A0A;
+    classDef ai fill:#EEF2FF,stroke:#4F46E5,color:#0A0A0A;
     classDef gate fill:#FEF3C7,stroke:#B45309,color:#0A0A0A;
     classDef stop fill:#FEE2E2,stroke:#B91C1C,color:#0A0A0A;
-    class INV agent;
+    class X,INV ai;
     class H gate;
     class BLK,REJ stop;
 ```
 
+- **Extraction (AI)** — the vendor's invoice PDF is read by a vision model into a schema-validated `Invoice`. You watch the document get scanned and the fields fill in. (The seeded pipeline then runs on the trusted record, so a model misread degrades the reveal, never the downstream verdicts — see below.)
 - **Matching** — a 2-way (invoice ↔ PO) or 3-way (invoice ↔ PO ↔ goods receipt) match, returning a verdict: `clean`, `exception`, or `duplicate`.
 - **Investigation** — runs only on an exception, and the one step that's an agent. A number ("9% over the PO") doesn't tell a reviewer whether it's a legitimate price increase or an overcharge; that lives in unstructured records, and which records matter depends on what you find. The agent **chooses** which tools to call, reads the records, and writes a recommendation. It decides nothing about the money.
 - **Approval routing** — tiers an exception (manager / director by the money and variance at stake) and **pauses for a human**; a duplicate is blocked so it's never paid twice; a clean match skips straight through.
@@ -57,9 +59,11 @@ The split-view dashboard shows the **invoice queue** (color-coded by outcome) an
 
 ## How it's built
 
-**Code decides the money; the agent investigates the ambiguity.** Whether an invoice is a 9%-over price variance, a duplicate, or which approval tier applies is arithmetic and policy, not a language problem — so it's pure, unit-tested functions ([`lib/matching.ts`](lib/matching.ts), [`lib/policy.ts`](lib/policy.ts), [`lib/erp.ts`](lib/erp.ts)): exact, auditable, identical on every run. The agent is reserved for the one step where the right sequence of actions isn't knowable in advance — judging a flagged exception against messy records — and even there it only *recommends*. The deterministic routing and the human gate own the outcome, so a wrong recommendation is caught by the reviewer, and a slow or unavailable model just means the run proceeds without the agent's note. Autonomy sits where a mistake is recoverable, not where it isn't.
+**AI at the edges, deterministic code in the core.** The two ends of the pipeline are language/perception problems — reading a messy PDF, judging a fuzzy exception — so they use a model. The middle (is this a 9%-over variance? a duplicate? which approval tier?) is arithmetic and policy, so it's pure, unit-tested functions ([`lib/matching.ts`](lib/matching.ts), [`lib/policy.ts`](lib/policy.ts), [`lib/erp.ts`](lib/erp.ts)): exact, auditable, identical on every run. An LLM never decides a payment amount.
 
-**The investigator agent.** [`src/mastra/agents/investigator.ts`](src/mastra/agents/investigator.ts) is a Mastra [`Agent`](https://mastra.ai) with three tools — `get-vendor-price-history`, `get-po-notes`, `get-receipt-notes` — returning deliberately unstructured, free-text records ([`lib/vendor-context.ts`](lib/vendor-context.ts)). It runs an open-ended loop: it picks which tools to call and in what order (a quantity problem pulls the receipt notes first; a price problem pulls the price history), reads them, and writes a recommendation (`likely_legitimate` / `likely_overcharge` / `unclear`). Each tool call and the recommendation appear live on the trace. Tools read the trusted vendor from `requestContext`, not model-generated args, so the agent can't pull the wrong vendor's file. Model id lives in one place ([`src/mastra/model.ts`](src/mastra/model.ts)), resolved by Mastra's router (`"anthropic/claude-haiku-4-5"`).
+**Extraction reads the document; the record decides.** The vendor's PDF is rendered ([`lib/invoice-pdf.ts`](lib/invoice-pdf.ts)) and read by a vision model into a schema-validated `Invoice` ([`lib/extract.ts`](lib/extract.ts), `Invoice.safeParse`). Here's the deliberate part: the extracted invoice is *shown* (the reveal proves the read happened), but the downstream pipeline runs on the **trusted seeded record**, not the model's output. So a misread degrades the reveal, never the verdicts — the demo's edge cases stay reliable. It also fails open: if the model is slow or down, the run notes it and proceeds on the record. In production you'd reconcile extraction against the PO and surface the diff; the seam is the same.
+
+**The investigator agent.** [`src/mastra/agents/investigator.ts`](src/mastra/agents/investigator.ts) is a Mastra [`Agent`](https://mastra.ai) with three tools — `get-vendor-price-history`, `get-po-notes`, `get-receipt-notes` — returning deliberately unstructured, free-text records ([`lib/vendor-context.ts`](lib/vendor-context.ts)). It runs an open-ended loop: it picks which tools to call and in what order (a quantity problem pulls the receipt notes first; a price problem pulls the price history), reads them, and writes a recommendation (`likely_legitimate` / `likely_overcharge` / `unclear`). It only *recommends* — the deterministic routing and the human gate own the outcome, so a wrong call is caught by the reviewer. Each tool call and the recommendation appear live on the trace. Tools read the trusted vendor from `requestContext`, not model-generated args, so the agent can't pull the wrong vendor's file. Model id lives in one place ([`src/mastra/model.ts`](src/mastra/model.ts)), resolved by Mastra's router (`"anthropic/claude-haiku-4-5"`).
 
 **A real human-in-the-loop, statelessly.** On an exception the run pauses before reconciliation (`awaiting`) and the ERP post does not happen until a human clicks Approve. The demo never writes to the database, yet a pause normally needs a persisted run to resume — so instead of a stored snapshot, the Approve/Reject click fires a second request that recomputes the cheap deterministic prefix and continues into reconciliation, gated by a `humanApproval` input ([`app/api/run/route.ts`](app/api/run/route.ts)). Mastra's native `suspend`/`resume` would need durable storage across two serverless requests; recomputing a pure prefix is the stateless-friendly choice.
 
@@ -83,9 +87,14 @@ src/mastra/
   testing/            mock model + offline integration tests
 lib/
   matching.ts · policy.ts · erp.ts   pure, unit-tested decision logic
+  extract.ts          vision extraction (invoice PDF → validated Invoice)
+  invoice-pdf.ts      render an Invoice to a PDF (so there's a real doc to read)
   vendor-context.ts   the messy free-text records the agent reasons over
   schema.ts           Zod source of truth → types + JSON schema
   trace.ts · ndjson.ts   stream adapter + framing
+app/api/
+  run/                streams the run (extraction → pipeline → trace)
+  pdf/[id]/           renders the invoice PDF on demand
 db/
   schema.ts · seed-data.ts · seed.ts · client.ts   Drizzle + read-only query layer
 ```
@@ -125,7 +134,7 @@ pnpm dev                          # http://localhost:3000
 
 | Variable | Required | Purpose |
 | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | **yes** | The investigator agent (Claude Haiku via Mastra's router) |
+| `ANTHROPIC_API_KEY` | **yes** | Extraction (Claude Sonnet vision) + the investigator agent (Claude Haiku via Mastra's router) |
 | `DATABASE_URL` | **yes** | Supabase Postgres — use the **transaction pooler** string |
 | `DIRECT_DATABASE_URL` | optional | Direct (non-pooled) string for `db:push` / `db:seed` |
 
@@ -142,7 +151,7 @@ This is a stateless demo with a fake ERP; the decision logic (matching, routing,
 - swap the fake ERP adapter for a real one (same `ErpAdapter` interface),
 - add persistence and an audit trail (the `agent_runs` table is already shaped for it),
 - wire real approver identity to the human gate,
-- a document-extraction intake step (PDF/email → `Invoice`) ahead of matching,
+- make extraction authoritative — reconcile the extracted invoice against the PO and surface the diff for review, rather than running on the seeded record,
 - batch processing across the whole queue.
 
 ---

app/api/pdf/[id]/route.ts

@@ -0,0 +1,53 @@
+import { loadInvoiceById } from "@/db/client";
+import { renderInvoicePdf } from "@/lib/invoice-pdf";
+
+/**
+ * GET /api/pdf/[id] — render the seeded invoice as a PDF on demand.
+ *
+ * The PDF isn't stored: it's generated deterministically from the seeded invoice
+ * row each request (same invoice → same bytes), so there's no extra DB column,
+ * no migration, and the document can never drift from the data. The intake
+ * extraction reveal (and the queue hover preview) fetch this, render it with
+ * pdf.js, and the model reads the same bytes.
+ *
+ * Only the invoice is loaded (`loadInvoiceById`), not the whole run bundle — the
+ * document doesn't need the PO / receipt / ledger. Because the bytes are
+ * deterministic and the data is read-only seed data, the response is cacheable,
+ * so re-hovering or re-selecting an invoice is served from the browser cache
+ * instead of regenerating the PDF.
+ *
+ * Node runtime — pdf-lib runs in Node, not Edge.
+ */
+
+export const runtime = "nodejs";
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  const { id } = await params;
+
+  let invoice: Awaited<ReturnType<typeof loadInvoiceById>>;
+  try {
+    invoice = await loadInvoiceById(id);
+  } catch {
+    return new Response("Could not load the invoice.", { status: 500 });
+  }
+  if (!invoice) {
+    return new Response(`No seeded invoice with id "${id}".`, { status: 404 });
+  }
+
+  const bytes = await renderInvoicePdf(invoice);
+  // Copy into a fresh ArrayBuffer so the body is a plain BodyInit (not a typed
+  // array view over a possibly-larger buffer).
+  const body = bytes.slice().buffer;
+  return new Response(body, {
+    status: 200,
+    headers: {
+      "content-type": "application/pdf",
+      // Deterministic bytes from read-only seed data → safe to cache. Re-hovering
+      // a seen invoice is then instant (served from cache, no regeneration).
+      "cache-control": "public, max-age=3600, immutable",
+    },
+  });
+}

app/api/run/route.ts

@@ -3,6 +3,9 @@ import { loadRunBundle } from "@/db/client";
 import { toTraceEvent, pipelineErrorEvent, type TraceEvent } from "@/lib/trace";
 import { ndjsonLine } from "@/lib/ndjson";
 import { checkRateLimit, clientIpFrom } from "@/lib/ratelimit";
+import { renderInvoicePdfBase64 } from "@/lib/invoice-pdf";
+import { extractInvoice } from "@/lib/extract";
+import type { Invoice } from "@/lib/schema";
 import {
   RunRequest,
   STREAM_CONTENT_TYPE,
@@ -16,8 +19,9 @@ import {
  * Runtime: NODE, not Edge. The Postgres driver needs raw TCP sockets that the
  * Edge runtime doesn't provide. Vercel's Node functions support HTTP response
  * streaming AND a configurable maxDuration, which meets the real goal — a long-
- * enough, non-timing-out stream — while keeping the DB driver working. A run is a
- * few seconds (one short agent call, only on an exception), so 60s is ample.
+ * enough, non-timing-out stream — while keeping the DB driver working. A run is
+ * the intake extraction (one vision call, capped at 20s) plus the deterministic
+ * pipeline and, on an exception, one short agent call — comfortably inside 60s.
  *
  * STATELESS BY DESIGN: this reads the seeded invoice/PO/receipt, runs the steps,
  * streams the trace, and FORGETS. It never writes to the database — not the
@@ -39,6 +43,86 @@ function line(obj: unknown): Uint8Array {
   return new TextEncoder().encode(ndjsonLine(obj));
 }
 
+/** Hard cap on the extraction call so a slow model never stalls the demo. */
+const EXTRACTION_TIMEOUT_MS = 20_000;
+
+/**
+ * Phase-0 intake extraction. Renders the seeded invoice to a PDF, has the model
+ * read it back, and emits intake trace events carrying the extracted invoice (for
+ * the reveal) — then leaves the pipeline to run on the trusted seed. Never throws:
+ * any failure becomes a "could not extract, proceeding on record" note.
+ */
+async function emitExtraction(
+  emit: (e: Omit<TraceEvent, "seq" | "atMs">) => void,
+  seed: Invoice,
+): Promise<void> {
+  emit({
+    kind: "step",
+    stage: "intake",
+    status: "running",
+    stepId: "intake",
+    label: "Intake — reading invoice PDF",
+    detail: "Extracting the document with the vision model…",
+    // Carry the document so the reveal can render + scan it immediately, before
+    // the model returns. (This is the on-screen twin of the PDF being read.)
+    data: { document: seed },
+  });
+
+  try {
+    const pdfBase64 = await renderInvoicePdfBase64(seed);
+    const result = await Promise.race([
+      extractInvoice(pdfBase64),
+      new Promise<{ ok: false; kind: "timeout" }>((resolve) =>
+        setTimeout(
+          () => resolve({ ok: false, kind: "timeout" }),
+          EXTRACTION_TIMEOUT_MS,
+        ),
+      ),
+    ]);
+
+    if (result.ok) {
+      // Did the model's read agree with the seeded record on the key fields the
+      // pipeline routes on? (It drives a "validated against PO record" note.)
+      const matches =
+        result.invoice.invoiceNumber === seed.invoiceNumber &&
+        (result.invoice.poNumber ?? null) === (seed.poNumber ?? null) &&
+        Math.abs(result.invoice.total - seed.total) < 0.01;
+      emit({
+        kind: "step",
+        stage: "intake",
+        status: "ok",
+        stepId: "intake",
+        label: "Intake — extracted",
+        detail: matches
+          ? "Extracted and reconciled with the PO record."
+          : "Extracted; key fields differ from the record (pipeline uses the record).",
+        data: { extracted: result.invoice, matches },
+      });
+      return;
+    }
+
+    // Extraction failed/timed out — proceed on the seed.
+    emit({
+      kind: "step",
+      stage: "intake",
+      status: "warn",
+      stepId: "intake",
+      label: "Intake — using record",
+      detail:
+        "Couldn't extract the document just now; proceeding on the seeded record.",
+    });
+  } catch {
+    emit({
+      kind: "step",
+      stage: "intake",
+      status: "warn",
+      stepId: "intake",
+      label: "Intake — using record",
+      detail: "Extraction unavailable; proceeding on the seeded record.",
+    });
+  }
+}
+
 export async function POST(request: Request): Promise<Response> {
   // 0. Rate-limit by IP first — before any work or model calls. The demo is
   //    public and each run spends Anthropic tokens, so this caps abuse. Fails
@@ -117,6 +201,17 @@ export async function POST(request: Request): Promise<Response> {
         controller.enqueue(line(stamp(e)));
 
       try {
+        // Phase 0: INTAKE EXTRACTION. Only on the first request (not the
+        // Approve/Reject resume — re-extracting then would be wasted work). The
+        // agent reads the rendered invoice PDF and we surface what it extracted.
+        // The extracted invoice is shown to prove the read happened; the pipeline
+        // below runs on the TRUSTED seeded record, so a model misread degrades the
+        // reveal, never the deterministic verdicts. Fails open: if extraction
+        // errors or times out, we note it and proceed on the seed.
+        if (decision === undefined) {
+          await emitExtraction(emit, bundle.invoice);
+        }
+
         const workflow = mastra.getWorkflow("p2p");
         const run = await workflow.createRun();
         const result = run.stream({

app/globals.css

@@ -84,3 +84,26 @@ body {
 .animate-pulse-ring {
   animation: pulse-ring 1.4s ease-out infinite;
 }
+
+/* Extraction reveal: a scan band sweeps down the document while the model reads
+   it, so the intake step reads as "the AI is looking at the page". */
+@keyframes scan {
+  0% {
+    transform: translateY(-4rem);
+    opacity: 0;
+  }
+  15% {
+    opacity: 1;
+  }
+  85% {
+    opacity: 1;
+  }
+  100% {
+    transform: translateY(420px);
+    opacity: 0;
+  }
+}
+
+.animate-scan {
+  animation: scan 1.6s ease-in-out infinite;
+}