SDKs (Python and TypeScript) and the viewer component
Package names: extractit-sdk (import extractit_sdk, also from extractit import DX
with the extra sdk), @extractit/sdk and @extractit/react. Decisions: ADR-011.
Hello world
from extractit_sdk import DX, Tier
from pydantic import BaseModel
class Invoice(BaseModel):
invoice_number: str
total: float
result = DX().extract(
"invoice.pdf", schema=Invoice, tier=Tier.STANDARD
) # DX_API_KEY from the environment
print(
result.data.total, result.confidence("total").score, result.evidence("total")[0].regions[0].bbox
)
import { DX } from "@extractit/sdk";
import { z } from "zod";
const Invoice = z.object({ invoice_number: z.string(), total: z.number() }).meta({ title: "Invoice" });
const run = await new DX({ apiKey: process.env.DX_API_KEY }).extract(file, { schema: Invoice });
console.log(run.data.total, run.fields.total?.evidence[0]?.regions); // run.data.total: number
What the hand-written layer adds
| Feature | Python | TypeScript |
|---|---|---|
| Clients | DX, AsyncDX |
DX (fetch) |
| Retries | 3 retries, base 0.5 s, cap 30 s, jitter ±25 %, only 408/429/5xx/connection errors, Retry-After (cap 30 s), one Idempotency-Key per call reused by every attempt |
same policy (retry.ts) |
| Errors | DXError → APIError → BadRequest (400, 422), Unauthorized, Forbidden, NotFound, Conflict, PreconditionFailed, RateLimited, ServerError; RunFailed, SDKTimeout, FieldMissingError, UnsupportedSchemaError, WorkflowBuilderError; each API error carries request_id and errors |
same names |
| Typed result | ExtractResult[T] (data, confidence(path), evidence(path); allow_partial) |
ExtractRun<Infer<S>> (data, fields, confidence, evidence; allowPartial) |
| Schema | Pydantic → JSON Schema 2020-12 with x-dx (dx_field(...) or json_schema_extra) |
zod 4 z.toJSONSchema + .meta({"x-dx": …}); zod 3 via useZodToJsonSchema(zodToJsonSchema) |
| Pagination | for run in dx.runs.list(limit=50) follows next_cursor |
for await (const run of dx.runs.list({limit: 50})) |
| Events | dx.runs.events(run_id) (SSE, Last-Event-ID, no duplicates by sequence) |
same, over fetch streaming (no EventSource: it cannot send Authorization) |
| Webhooks | dx.webhooks.verify(payload, headers, secret, tolerance=300) (Standard Webhooks) |
verifyWebhook(payload, headers, secret) on WebCrypto only (Node 20, browsers, edge) |
| Builder | dx.workflow(name).parse().classify(...).extract(Model, branch=…).validate(dx.rules.arithmetic(...)).publish(alias="dev") |
same chain; both produce the same graph (sdk/fixtures/invoice.workflow.json) |
extract after classify or split without branch raises WorkflowBuilderError before any request.
A result larger than 5 MiB comes as result_url; runs.result follows it.
Everything the API offers and the wrappers do not cover is in the generated client:
dx.generated (Python, same pool and retries) and @extractit/sdk/generated (TypeScript).
The API key never appears in repr, logs, error messages or URLs (page images are fetched with the
Authorization header and shown as object URLs). A key in a browser is visible to the visitor:
the TypeScript client warns once; proxy the calls through your server.
Regenerate and check
make sdk-regen # regenerate _generated/ and src/generated/ from openapi/openapi.json
python3 scripts/check_sdk_coverage.py # every operationId has a method in both SDKs (exemptions: sdk/exemptions.toml)
uv run pytest sdk/python/tests # Python SDK
uv run pyright -p sdk/python # strict
pnpm --filter @extractit/sdk check # tsc, build, publint, attw, size-limit (core <= 40 KB gzip)
<EvidenceViewer>
import { EvidenceViewer } from "@extractit/react";
import "@extractit/react/styles.css";
<EvidenceViewer client={dx} runId="run_…" fieldPath="total" onSelectField={setField} />
client is anything with baseUrl, authHeaders() and runs.result(runId) (a DX of the TypeScript
SDK is one). It draws the page as displayed (page_display_norm_v1: rotation and CropBox already
applied) with an SVG layer of the polygons of the words behind the selected field, and a listbox of
the fields (aria-selected, aria-controls, arrow keys) as the accessible alternative. Document text
is rendered escaped. usePageImage keeps the last 10 page images as object URLs and revokes the rest.