core

extractkit

Extraction you can audit. Define a Zod schema, feed it a PDF or image, get back schema-validated JSON where every field carries provenance — the page and bounding box it came from — plus a confidence score.

Pre-1.0. The API may change until the public benchmark ships. Part of the extractkit monorepo.

Install

npm install @ratchaw/extractkit ai zod

ai (Vercel AI SDK v7) and zod (v4) are peer dependencies. Bring any AI SDK provider — e.g. @ai-sdk/anthropic, @ai-sdk/openai, or @ai-sdk/google — and pass its model to extract.

Quickstart

import { anthropic } from '@ai-sdk/anthropic';
import { extract } from '@ratchaw/extractkit';
import { readFile } from 'node:fs/promises';
import { z } from 'zod';

const invoice = z.object({
  vendor: z.string().describe('Legal name of the issuing company'),
  invoiceNumber: z.string(),
  issueDate: z.iso.date(),
  currency: z.string().describe('ISO 4217 code, e.g. USD'),
  total: z.number(),
  lineItems: z.array(
    z.object({
      description: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
      amount: z.number(),
    }),
  ),
});

const result = await extract({
  schema: invoice,
  document: { data: await readFile('invoice.pdf') },
  model: anthropic('claude-sonnet-5'),
});

result.data.total;           // 1250.5 — validated against the schema
result.fields.total;         // { value: 1250.5, confidence: 0.97, page: 0, bbox: { x0: 0.72, y0: 0.81, x1: 0.9, y1: 0.84 } }
result.usage;                // { inputTokens, outputTokens, totalTokens, modelCalls, costUSD }
result.issues;               // non-fatal anomalies, e.g. dropped implausible provenance

Every leaf of your schema comes back twice: the plain value in data (validated, typed z.output of your schema) and an ExtractedField in fields with:

• page — 0-based page index (always 0 for images), or null when the model couldn't locate the value.
• bbox — { x0, y0, x1, y1 } normalized to page width/height (0–1, origin top-left), or null. Reported regions are validated: out-of-range pages and degenerate boxes are dropped and noted in result.issues.
• confidence — the model's self-reported probability (0–1) that the value is exactly right. It is not calibrated; treat it as a ranking signal. The eval harness in this repo measures how well it tracks reality per model.

Streaming

import { streamExtract } from '@ratchaw/extractkit';

const stream = streamExtract({ schema: invoice, document, model });

for await (const event of stream) {
  // fires as each field's provenance wrapper completes
  console.log(event.path, event.field.value);
}

const result = await stream.result; // same validated result extract() returns

Field events are emitted before final validation (the finished result is authoritative), and streaming does not run repair attempts — use extract() when robustness matters more than latency.

Documents

document.data accepts Uint8Array, ArrayBuffer, or a base64 string. PDF, PNG, JPEG, and WebP are supported; the type is sniffed from the file signature, and a declared mediaType must match it. PDFs are checked before any tokens are spent: encrypted files, empty files, and unparseable files fail fast with typed errors, and the real page count is used to validate the model's page references.

Schemas

Supported: z.object, z.array, z.string (including formats like z.iso.date()), z.number, z.boolean, z.enum, z.literal, plus .optional(), .nullable(), .describe(), and .refine(). Field descriptions are forwarded to the model — use them.

Rejected by design, with an UnsupportedSchemaError naming the offending path: .transform(), .default(), .catch(), and z.date(). A transformed or defaulted value no longer maps to a region of the document, which breaks the provenance guarantee. Transform after extraction instead.

Failure handling

Error	code	Meaning
UnsupportedSchemaError	SCHEMA_UNSUPPORTED	Schema contains an unsupported type; thrown before any model call
DocumentError	UNSUPPORTED_MEDIA_TYPE, MEDIA_TYPE_MISMATCH, ENCRYPTED_DOCUMENT, INVALID_DOCUMENT	Input rejected before any model call
DocumentUnreadableError	DOCUMENT_UNREADABLE	The model reported the document as blank/illegible/not a document; carries its stated issues
MissingRequiredFieldsError	MISSING_REQUIRED_FIELDS	Document was readable but required fields weren't found; carries missingPaths and the partial extraction
ExtractionFailedError	EXTRACTION_FAILED	Model kept returning invalid output after all repair attempts; carries attempts, usage, and the raw text

All extend ExtractKitError. Transport and provider errors from the AI SDK propagate unwrapped, with the SDK's own maxRetries applied. When the model returns malformed or schema-violating output, extractkit re-prompts it with the specific violations (maxRepairAttempts, default 1); token usage is accumulated across attempts so costs stay visible.

Cost tracking

result.usage always carries token counts and the number of model calls. Pass pricing: { inputPerMTokUSD, outputPerMTokUSD } to get costUSD; without it, costUSD is null — extractkit ships no built-in price table, so costs are never silently wrong.

License

MIT