Skip to content

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.