@anyformat/sdk 0.2.3 → 1.0.0

package/dist/index.d.cts

@@ -319,6 +319,51 @@ interface TDataShape {
 type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
 type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
 
+/**
+ * AllOfCheck
+ *
+ * AND combinator — passes iff every sub-check passes.
+ *
+ * Tri-state: FAIL if any child fails; else INCONCLUSIVE if any child is
+ * inconclusive; else PASS. Children are the same closed ``Check`` union
+ * (mutual recursion via forward ref) so combinators nest by construction —
+ * the CheckBuilder UI restricts nesting to a single level for MVP.
+ *
+ * ``max_length=32`` bounds runaway fan-out per combinator. Practical rules
+ * stay well below the cap; a legitimate use case wanting more should motivate
+ * the raise rather than land silently. Nesting-depth is bounded by pydantic's
+ * own recursion during parse.
+ */
+type AllOfCheck = {
+    /**
+     * Checks
+     */
+    checks: Array<RangeCheck | DateCheck | ArithmeticCheck | ComparisonCheck | OneOfCheck | RegexCheck | RequiredCheck | ConfidenceCheck | ExpressionCheck | ValidationCheck | AllOfCheck | AnyOfCheck>;
+    /**
+     * Type
+     */
+    type: 'all_of';
+};
+/**
+ * AnyOfCheck
+ *
+ * OR combinator — passes iff any sub-check passes.
+ *
+ * Tri-state: PASS if any child passes; else INCONCLUSIVE if any child is
+ * inconclusive; else FAIL.
+ *
+ * ``max_length=32`` — see :class:`AllOfCheck` for the rationale.
+ */
+type AnyOfCheck = {
+    /**
+     * Checks
+     */
+    checks: Array<RangeCheck | DateCheck | ArithmeticCheck | ComparisonCheck | OneOfCheck | RegexCheck | RequiredCheck | ConfidenceCheck | ExpressionCheck | ValidationCheck | AllOfCheck | AnyOfCheck>;
+    /**
+     * Type
+     */
+    type: 'any_of';
+};
 /**
  * ArithmeticCheck
  */
@@ -326,13 +371,13 @@ type ArithmeticCheck = {
     /**
      * Equals
      *
-     * persistent_id whose value the result must equal.
+     * The field whose value the result must equal. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     equals: string;
     /**
      * Operands
      *
-     * persistent_ids combined by `operator`.
+     * The fields combined by `operator`. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     operands: Array<string>;
     /**
@@ -398,9 +443,9 @@ type Block = {
     /**
      * Layout Confidence
      *
-     * 0-100 YOLO layout detection confidence for this block.
+     * 0-1 layout detection confidence for this block. `null` when no layout detector ran — the `lite` tier gets its layout from the OCR response, which reports no confidence in the type it assigned.
      */
-    layout_confidence: number;
+    layout_confidence?: number | null;
     /**
      * Page
      *
@@ -413,6 +458,12 @@ type Block = {
      * 0-100 parse confidence calibrated from LLM logprobs. `null` when logprobs were unavailable (e.g. text-bytes strategy).
      */
     parse_confidence?: number | null;
+    /**
+     * Regions
+     *
+     * The layout detections this block is made of, each with the words printed inside it. A block the detector reported as one box has one region, that box. Empty only for a block parsed before detections were reported, or one that has no box at all.
+     */
+    regions?: Array<Detection>;
     /**
      * Rows
      *
@@ -442,10 +493,6 @@ type BooleanField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -455,9 +502,15 @@ type BooleanField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
  * ClassificationResult
@@ -474,9 +527,9 @@ type ClassificationResult = {
     /**
      * Confidence
      *
-     * 0-100 model confidence in the verdict.
+     * 0-100 model confidence in the verdict. `null` when the verdict carries no score, because nothing was measured.
      */
-    confidence: number;
+    confidence: number | null;
     /**
      * Evidence
      *
@@ -539,7 +592,7 @@ type ComparisonCheck = {
     /**
      * Left
      *
-     * persistent_id of the left-hand field.
+     * The left-hand field. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     left: string;
     /**
@@ -559,6 +612,84 @@ type ComparisonCheck = {
      */
     type: 'comparison';
 };
+/**
+ * ConfidenceCheck
+ */
+type ConfidenceCheck = {
+    /**
+     * Field
+     *
+     * The field whose extraction confidence to compare. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
+     */
+    field: string;
+    /**
+     * Op
+     */
+    op: '<' | '<=' | '>' | '>=' | '==' | '!=';
+    /**
+     * Threshold
+     *
+     * Confidence percentile 0..100.
+     */
+    threshold: number;
+    /**
+     * Type
+     */
+    type: 'confidence';
+};
+/**
+ * DatasetUploadFileV3
+ *
+ * Per-file entry in a dataset-upload response.
+ */
+type DatasetUploadFileV3 = {
+    /**
+     * Id
+     *
+     * Unique identifier of the file (hyphenated UUID).
+     */
+    id: string;
+    /**
+     * Name
+     *
+     * Filename the file is stored under.
+     */
+    name: string;
+    /**
+     * Original Name
+     *
+     * The name you uploaded, present only when the file was auto-renamed (`on_conflict=rename` resolving a collision). `null` when the stored `name` is the name you sent.
+     */
+    original_name?: string | null;
+};
+/**
+ * DatasetUploadResponseV3
+ *
+ * Response for `POST /v3/workflows/{workflow_id}/dataset/upload/`.
+ *
+ * One dataset document packet, all-or-nothing. `document_packet_id` is the
+ * stable handle for the deferred ground-truth-edit follow-up.
+ */
+type DatasetUploadResponseV3 = {
+    /**
+     * Document Packet Id
+     *
+     * Unique identifier of the created dataset document packet (hyphenated UUID).
+     */
+    document_packet_id: string;
+    /**
+     * Files
+     *
+     * Files in the packet, in the order they were provided.
+     */
+    files: Array<DatasetUploadFileV3>;
+    /**
+     * Ground Truth Saved
+     *
+     * Whether ground truth was supplied and saved for this document packet.
+     */
+    ground_truth_saved: boolean;
+};
 /**
  * DateCheck
  */
@@ -570,7 +701,7 @@ type DateCheck = {
     /**
      * Field
      *
-     * persistent_id of the date field.
+     * The date field. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     field: string;
     /**
@@ -596,10 +727,6 @@ type DateField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -609,9 +736,15 @@ type DateField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
  * DatetimeField
@@ -627,10 +760,6 @@ type DatetimeField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -640,217 +769,438 @@ type DatetimeField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
- * Edge
+ * Detection
  *
- * A directed edge between two nodes. ``branch`` carries the source-port label
- * used for routing out of ``classify`` (category id) or ``splitter`` (rule id) nodes.
+ * One layout detection a block is made of: where it is and what is printed inside it.
+ *
+ * A block is often the fusion of several detections, and a consumer that has to point at what
+ * the page prints needs the parts, not only their union.
  */
-type Edge = {
+type Detection = {
     /**
-     * Branch
+     * Bbox
      *
-     * Source-port label for branch routing. Required when leaving a classify or splitter node by category/rule.
+     * Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.
      */
-    branch?: string | null;
+    bbox: {
+        [key: string]: number;
+    };
     /**
-     * Source
+     * Text
+     *
+     * The words the page prints inside this box.
      */
-    source: string;
+    text: string;
     /**
-     * Target
+     * Type
+     *
+     * What the layout detector called this box.
      */
-    target: string;
+    type: string;
 };
 /**
- * EnumField
+ * DocumentPacketDetailV3
+ *
+ * A packet with its per-file breakdown and latest run reference.
  */
-type EnumField = {
+type DocumentPacketDetailV3 = {
     /**
-     * Data Type
+     * Created At
+     *
+     * Timestamp when the packet was created (ISO 8601).
      */
-    data_type: 'enum';
+    created_at?: string | null;
     /**
-     * Description
+     * Files
      *
-     * Free-form description shown to the extraction model.
+     * Files in this packet.
      */
-    description?: string;
+    files: Array<DocumentPacketFileV3>;
     /**
-     * Enum Options
+     * Id
+     *
+     * Unique identifier of the document packet (hyphenated UUID).
      */
-    enum_options: Array<EnumOption>;
+    id: string;
     /**
-     * Lookup
+     * Latest Run Id
+     *
+     * Id of the packet's most recent run (hyphenated UUID); `null` until the packet has been run.
      */
-    lookup?: boolean;
+    latest_run_id?: string | null;
     /**
-     * Name
+     * Metadata
      *
-     * Field name. Used as the key in the extraction response.
+     * Free-form JSON supplied at packet creation. No schema is enforced; the extract operator may source datapoints from a top-level key whose name matches a schema field. `null` when no metadata was attached.
      */
-    name: string;
+    metadata?: {
+        [key: string]: unknown;
+    } | null;
     /**
-     * Persistent Id
+     * Name
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Human-readable name of the packet.
      */
-    persistent_id?: string | null;
-};
-/**
- * EnumOption
- */
-type EnumOption = {
+    name?: string | null;
     /**
-     * Description
+     * Processing status. Non-terminal: `not_started`, `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
+     */
+    status: DocumentPacketStatus;
+    /**
+     * Updated At
      *
-     * Free-form description shown to the model.
+     * Timestamp when the packet was last updated (ISO 8601).
      */
-    description: string;
+    updated_at?: string | null;
     /**
-     * Name
+     * Workflow Id
+     *
+     * The workflow this packet belongs to (hyphenated UUID).
      */
-    name: string;
+    workflow_id: string;
 };
 /**
- * Evidence
+ * DocumentPacketFileV3
  *
- * A snippet of source text supporting an extracted value, with the page it came from.
+ * Slim per-file projection inside a packet.
  */
-type Evidence = {
+type DocumentPacketFileV3 = {
     /**
-     * Page Number
+     * Id
      *
-     * 1-indexed page number where the snippet was found.
+     * Unique identifier of the file (hyphenated UUID).
      */
-    page_number: number;
+    id: string;
     /**
-     * Text
+     * Name
      *
-     * The exact source-text snippet that supports the extracted value.
+     * Filename the file is stored under. Filenames are unique within a workflow: a name that collides with an existing file is auto-renamed by inserting a ` (n)` counter before the extension (e.g. `invoice.pdf` → `invoice (1).pdf`).
      */
-    text: string;
+    name: string;
 };
 /**
- * ExtractNode
+ * DocumentPacketStatus
+ *
+ * Extraction lifecycle of a packet. Non-terminal: ``not_started``
+ * (no run yet), ``queued``, ``in_progress``. Terminal: ``processed``
+ * (success), ``error``, ``cancelled``.
+ */
+type DocumentPacketStatus = 'not_started' | 'queued' | 'in_progress' | 'processed' | 'error' | 'cancelled';
+/**
+ * DocumentPacketSummaryV3
+ *
+ * Slim packet projection returned by list pages.
  */
-type ExtractNode = {
+type DocumentPacketSummaryV3 = {
     /**
-     * Schema for the fields this node extracts. Required.
+     * Created At
+     *
+     * Timestamp when the packet was created (ISO 8601).
      */
-    extraction_schema: ExtractionSchema;
+    created_at?: string | null;
     /**
      * Id
      *
-     * Stable identifier for this node within the graph.
+     * Unique identifier of the document packet (hyphenated UUID).
      */
     id: string;
     /**
-     * Lookup File Uploads
+     * Name
      *
-     * Inline lookup-file content for the typed create call. Each entry is uploaded and the resulting URI is appended to ``lookup_files``; this field is create-input only.
+     * Human-readable name of the packet.
      */
-    lookup_file_uploads?: Array<LookupFileUpload>;
+    name?: string | null;
     /**
-     * Lookup Files
-     *
-     * Smart-lookup reference document URIs persisted on the extract node.
+     * Processing status. Non-terminal: `not_started`, `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
      */
-    lookup_files?: Array<string>;
+    status: DocumentPacketStatus;
     /**
-     * Lookup Reasoning Effort
+     * Updated At
      *
-     * Reasoning effort for the smart-lookup matcher (gpt-5 family): minimal | low | medium | high. None = model default. Higher effort improves match reliability on noisy join keys at higher latency/cost.
+     * Timestamp when the packet was last updated (ISO 8601).
      */
-    lookup_reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high' | null;
+    updated_at?: string | null;
     /**
-     * Lookup Schema
+     * Workflow Id
      *
-     * Typed schema of fields the smart-lookup pass should produce. Derived server-side from the workflow's smart-lookup fields; default empty for nodes without any.
+     * The workflow this packet belongs to (hyphenated UUID).
      */
-    lookup_schema?: Array<StringField | IntegerField | FloatField | BooleanField | DateField | DatetimeField | EnumField | MultiSelectField | ObjectField>;
+    workflow_id: string;
+};
+/**
+ * Edge
+ *
+ * A directed edge between two nodes. ``branch`` carries the source-port label
+ * used for routing out of ``classify`` (category id) or ``splitter`` (rule id) nodes.
+ */
+type Edge = {
     /**
-     * Lookup Suggestion
+     * Branch
      *
-     * Free-form hint shown to the smart-lookup matcher.
+     * Source-port label for branch routing. Required when leaving a classify or splitter node by category/rule.
      */
-    lookup_suggestion?: string | null;
+    branch?: string | null;
     /**
-     * Mode
+     * Source
+     */
+    source: string;
+    /**
+     * Target
+     */
+    target: string;
+};
+/**
+ * Edit
+ *
+ * One edit node's filled form for one file of the collection: the values
+ * written into the document's fields, plus a short-lived link to the filled
+ * PDF. One entry per file the edit node processed.
+ */
+type Edit = {
+    /**
+     * Download Url
      *
-     * Extraction tier. 'standard' (default): single-pass extraction — the best balance for simple documents and layouts. 'agentic': multi-step extraction that maps every table to the schema and reasons across sections — for dense or cross-page tables; extra cost per page. 'max' (feature-gated): extracts table rows page by page with cross-page context tracking, then independently verifies row sums against document totals and re-extracts pages that don't reconcile — for multi-page invoices with complex row grouping. 'lite' (shown as 'Fast' in the app): standard extraction, faster and cheaper; quality may vary on complex layouts.
+     * Presigned link to the filled PDF, valid for 15 minutes from the moment this response was built. Re-read the results endpoint for a fresh link. `null` when no filled PDF was stored.
      */
-    mode?: 'standard' | 'agentic' | 'max' | 'lite';
+    download_url?: string | null;
     /**
-     * Page Sum Verification Enabled
+     * Fields
      *
-     * After row extraction, independently re-check each page's rows against document totals and re-extract pages that don't reconcile ('max' mode implies this).
+     * Every form field detected in the document, filled or not, in document order.
      */
-    page_sum_verification_enabled?: boolean;
+    fields?: Array<EditFormField>;
     /**
-     * Row Extractor Enabled
+     * File Id
      *
-     * Extract table rows page by page, carrying context across page breaks so rows stay in their group ('max' mode implies this).
+     * The UUID of the file this form was filled from.
      */
-    row_extractor_enabled?: boolean;
+    file_id: string;
     /**
-     * Type
+     * File Name
+     *
+     * The file's display name.
      */
-    type: 'extract';
+    file_name: string;
     /**
-     * Use Images
+     * Unmatched Instructions
      *
-     * Standard/lite modes: send each PDF page's rendered image alongside its parsed text so the model can read layout the text missed — adds vision cost on every page. No effect in agentic/max modes or on non-PDF sources.
+     * Instruction fragments, quoted verbatim, that matched no field in this document.
      */
-    use_images?: boolean;
+    unmatched_instructions?: Array<string>;
 };
 /**
- * ExtractedField
+ * EditFormField
  *
- * One extracted field's value, confidence, and supporting evidence.
+ * One form field the edit node detected, with the value it wrote in.
  */
-type ExtractedField$1 = {
+type EditFormField = {
+    /**
+     * Bbox
+     *
+     * The field's fillable area as a normalised bounding box in [0, 1] page coordinates, keys `x0`/`y0`/`x1`/`y1`.
+     */
+    bbox: {
+        [key: string]: number;
+    };
     /**
      * Confidence
      *
-     * Model confidence in the extracted value, on a 0-100 scale. `null` when the backend did not produce a confidence (e.g. manual entry).
+     * Raw, uncalibrated 0-100 match score for pairing an instruction with this field. It grades how surely the instruction addresses the field, not whether the written value is correct, and it is not a probability. `null` when no instruction addressed this field, because nothing was measured.
      */
-    confidence?: number | null;
+    confidence: number | null;
     /**
-     * Evidence
+     * Form Field Id
      *
-     * Source-text snippets the model used to derive this value.
+     * Stable identifier for this form field within the document, in the form `p<page>_f<index>`.
      */
-    evidence?: Array<Evidence>;
+    form_field_id: string;
     /**
-     * Value
+     * Kind
      *
-     * The extracted value. Type depends on the field's `data_type` (string, number, date, etc.). `null` when extraction could not produce a value.
+     * `checkbox` for a tick target, `text` for anything else.
      */
-    value: unknown | null;
+    kind: string;
     /**
-     * Value Override
+     * Label
      *
-     * A human-supplied override of the extracted `value`, if one was set during verification. `null` when no override exists.
+     * The field's own printed caption, verbatim from the document.
      */
-    value_override?: unknown | null;
+    label: string;
     /**
-     * Verification Status
+     * Page
      *
-     * Verification state for this datapoint (e.g. `not_verified`, `verified`). `null` when not yet reviewed.
+     * 1-indexed page number the field sits on.
      */
-    verification_status?: string | null;
-};
-/**
- * Extraction
- *
- * One unit of extracted data. For linear (parse->extract) workflows there
- * is exactly one entry with `split_name=null` and `partition=null`. For split
- * workflows there is one entry per (split, partition) pair; join with
+    page: number;
+    /**
+     * State
+     *
+     * `empty` if the field was blank in the source document and therefore fillable, `prefilled` if the document already carried a value. Prefilled fields are never overwritten, so they always read back with `value: null`.
+     */
+    state: string;
+    /**
+     * Value
+     *
+     * The value written into the field — the literal string `true`/`false` for a `checkbox`. `null` when no instruction addressed this field.
+     */
+    value: string | null;
+};
+/**
+ * EnumField
+ */
+type EnumField = {
+    /**
+     * Data Type
+     */
+    data_type: 'enum';
+    /**
+     * Description
+     *
+     * Free-form description shown to the extraction model.
+     */
+    description?: string;
+    /**
+     * Enum Options
+     */
+    enum_options: Array<EnumOption>;
+    /**
+     * Name
+     *
+     * Field name. Used as the key in the extraction response.
+     */
+    name: string;
+    /**
+     * Persistent Id
+     *
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
+     */
+    persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
+};
+/**
+ * EnumOption
+ */
+type EnumOption = {
+    /**
+     * Description
+     *
+     * Free-form description shown to the model.
+     */
+    description: string;
+    /**
+     * Name
+     */
+    name: string;
+};
+/**
+ * Evidence
+ *
+ * A snippet of source text supporting an extracted value, with the page it came from.
+ *
+ * When ``text`` starts with ``metadata.``, the value was sourced from the
+ * packet's caller-supplied metadata (not the document): the remainder is
+ * the JSON path into that metadata, and ``page_number`` is ``0``. Encoded
+ * in ``text`` on purpose — same wire shape as document evidence, no schema
+ * change for SDK consumers.
+ */
+type Evidence = {
+    /**
+     * Page Number
+     *
+     * 1-indexed page number where the snippet was found.
+     */
+    page_number: number;
+    /**
+     * Text
+     *
+     * The exact source-text snippet that supports the extracted value.
+     */
+    text: string;
+};
+/**
+ * ExpressionCheck
+ *
+ * A CEL expression over the whole extraction, evaluated in a sandbox.
+ *
+ * The expression reads one root variable ``data`` and addresses fields by
+ * extracted name (``data.total``, ``data.lineas.map(l, l.importe)``), never by
+ * ``persistent_id`` — so ``field_ids`` returns ``[]`` for it, and a field
+ * rename silently breaks the rule. An expression the evaluator cannot parse,
+ * cannot answer with a boolean, or prices above its evaluation budget reports
+ * ``inconclusive``.
+ *
+ * ADR platform/0036 records why the CEL parser stays out of this package, so
+ * ``expression`` is unvalidated here.
+ */
+type ExpressionCheck = {
+    /**
+     * Expression
+     */
+    expression: string;
+    /**
+     * Type
+     */
+    type: 'expression';
+};
+/**
+ * ExtractedField
+ *
+ * One extracted field's value, confidence, and supporting evidence.
+ */
+type ExtractedField$1 = {
+    /**
+     * Confidence
+     *
+     * Model confidence in the extracted value, on a 0-100 scale. `null` when the backend did not produce a confidence (e.g. manual entry).
+     */
+    confidence?: number | null;
+    /**
+     * Evidence
+     *
+     * Source-text snippets the model used to derive this value.
+     */
+    evidence?: Array<Evidence>;
+    /**
+     * Value
+     *
+     * The extracted value, always as a string — a field declared `integer` returns `"3"`, not `3`. Values are stored as text, so `data_type` governs how the field is extracted and validated, not the JSON type you get back; parse it yourself, minding that a document may write a number as `1.026,00`. `null` when extraction produced no value.
+     */
+    value: unknown | null;
+    /**
+     * Value Override
+     *
+     * A human-supplied override of the extracted `value`, if one was set during verification. `null` when no override exists.
+     */
+    value_override?: unknown | null;
+    /**
+     * Verification Status
+     *
+     * Verification state for this datapoint (e.g. `not_verified`, `verified`). `null` when not yet reviewed.
+     */
+    verification_status?: string | null;
+};
+/**
+ * Extraction
+ *
+ * One unit of extracted data. For linear (parse->extract) workflows there
+ * is exactly one entry with `split_name=null` and `partition=null`. For split
+ * workflows there is one entry per (split, partition) pair; join with
  * `splits[]` by `split_name` to look up geometry.
  */
 type Extraction = {
@@ -876,6 +1226,12 @@ type Extraction = {
      * The split category this extraction belongs to. `null` for linear workflows.
      */
     split_name?: string | null;
+    /**
+     * Validations
+     *
+     * Configured validation verdicts and automatic extraction review warnings. Unresolved chunk fields have a null value and an inconclusive warning with candidate values and evidence, even without a validate node.
+     */
+    validations?: Array<Validation>;
 };
 /**
  * ExtractionSchema
@@ -933,10 +1289,6 @@ type FloatField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -946,9 +1298,15 @@ type FloatField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
  * Hyperlink
@@ -983,10 +1341,6 @@ type IntegerField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -996,9 +1350,38 @@ type IntegerField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
+};
+/**
+ * KnowledgeNode
+ *
+ * Terminal knowledge sink — its presence opts the workflow into the
+ * knowledge base (priced separately, so absent by default).
+ *
+ * The backend reacts to parse callbacks by ingesting parsed markdown into
+ * the workflow's navigable corpus; core never executes this node — the
+ * execution builder keeps it and its edges off the worker message. Emits
+ * nothing downstream.
+ */
+type KnowledgeNode = {
+    /**
+     * Id
+     *
+     * Stable identifier for this node within the graph.
+     */
+    id: string;
+    /**
+     * Type
+     */
+    type: 'knowledge';
 };
 /**
  * LookupFileUpload
@@ -1040,10 +1423,6 @@ type MultiSelectField = {
      * Enum Options
      */
     enum_options: Array<EnumOption>;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -1053,12 +1432,23 @@ type MultiSelectField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
  * ObjectField
+ *
+ * A repeating group — the way a table or line-item list is modelled.
+ *
+ * There is no separate list type: one ``object`` field describes the shape of
+ * a single row, and the extraction returns an array of those rows.
  */
 type ObjectField = {
     /**
@@ -1071,10 +1461,6 @@ type ObjectField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -1084,15 +1470,21 @@ type ObjectField = {
     /**
      * Nested Fields
      *
-     * Child fields of this object. Only one level of nesting is supported — an object field's children must be non-object types.
+     * Columns of one row. The extracted value is an array of objects with these keys, one entry per row found. Only one level of nesting is supported — an object field's children must be non-object types.
      */
     nested_fields: Array<StringField | IntegerField | FloatField | BooleanField | DateField | DatetimeField | EnumField | MultiSelectField>;
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
  * OneOfCheck
@@ -1108,6 +1500,8 @@ type OneOfCheck = {
     case_sensitive?: boolean;
     /**
      * Field
+     *
+     * The field to test. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     field: string;
     /**
@@ -1116,122 +1510,291 @@ type OneOfCheck = {
     type: 'one_of';
 };
 /**
- * ParseNode
+ * ParseResult
+ *
+ * Parsed markdown for a file.
  */
-type ParseNode = {
+type ParseResult = {
     /**
-     * Cache
+     * Blocks
      *
-     * Reuse parsed output when the same file was already parsed with the same mode and settings — a hit skips the whole parse. Disable to force a fresh parse.
+     * Structured per-block representation of the parsed document. One entry per `<a id></a>` anchor in document order, with type-specific structured data (`rows` for tables, `image_base64` for pictures) surfaced as first-class fields so consumers don't have to HTML-parse.
      */
-    cache?: boolean;
+    blocks?: Array<Block>;
     /**
-     * Effort
+     * Layout Confidence
      *
-     * Agentic mode: quality/cost preset. 'low' = several times cheaper but more errors on dense or low-contrast tables, 'mid' (default) = balanced, 'accurate' = highest fidelity. (Distinct from lite `ocr_effort`.)
+     * Document-level YOLO layout confidence on a 0-1 scale, char-weighted mean across all blocks. `null` if no annotated sections.
      */
-    effort?: 'low' | 'mid' | 'accurate';
+    layout_confidence?: number | null;
     /**
-     * Figure Enhancement
+     * Markdown
      *
-     * Standard mode: extract structured data from charts and images — extra processing per figure. Ignored in agentic (figures are already handled) and in lite (use `figures` instead).
+     * Document content rendered as structured markdown. Each block is preceded by an empty `<a id="p{page}_b{idx}"></a>` anchor (invisible in any markdown renderer; the id joins to `blocks[].id` and can be used as an in-page link target). Image hydration for picture/figure blocks happens client-side. `null` if parsing failed.
      */
-    figure_enhancement?: boolean;
+    markdown: string | null;
     /**
-     * Figures
+     * Parse Confidence
      *
-     * Lite mode: the correction pass reads data points off charts/figures and reconstructs them as HTML tables (extra work on figure pages; needs skip_routing_review=False).
+     * Document-level parse confidence on a 0-100 scale, char-weighted mean of per-block LLM logprob scores. `null` when no blocks have logprob-based confidence.
      */
-    figures?: boolean;
+    parse_confidence?: number | null;
+    /**
+     * Text
+     *
+     * `markdown` with `<img>` tags removed and runs of blank lines collapsed. Block anchors are deliberately kept, so on a document whose pictures are markdown images rather than `<img>` tags this is `markdown` verbatim — read one or the other, not both. `null` if `markdown` is null.
+     */
+    text?: string | null;
+};
+/**
+ * PublicEditNode
+ *
+ * Terminal form-filler. ``reference_uris`` is resolved server-side at run
+ * time from ``reference_document_ids`` — omitted here, and any client-supplied
+ * value is discarded rather than trusted.
+ */
+type PublicEditNode = {
+    /**
+     * Font
+     *
+     * Typeface the filled values are written in.
+     */
+    font?: 'sans' | 'serif' | 'mono';
     /**
      * Id
      *
      * Stable identifier for this node within the graph.
      */
     id: string;
+    /**
+     * Instructions
+     *
+     * Free-text values to map onto the fillable fields detected on the upstream parse's PDF, e.g. 'Name: ACME SL; Date: 2026-01-01; I accept the terms: yes'. Takes precedence over a reference document where both address the same field.
+     */
+    instructions?: string | null;
+    /**
+     * Output Mode
+     *
+     * 'flattened' paints the values on and the PDF is final. 'editable' leaves each value in a live form field a reviewer can correct in any PDF viewer.
+     */
+    output_mode?: 'flattened' | 'editable';
+    /**
+     * Reference Document Ids
+     *
+     * Ids of reference documents this node fills from, uploaded to the workflow beforehand. Every id must belong to this workflow and be fully resolved, or the run is refused rather than filled from a partial reference.
+     */
+    reference_document_ids?: Array<string>;
+    /**
+     * Type
+     */
+    type: 'edit';
+};
+/**
+ * PublicExtractNode
+ */
+type PublicExtractNode = {
+    /**
+     * Schema for the fields this node extracts. Required.
+     */
+    extraction_schema: ExtractionSchema;
+    /**
+     * Id
+     *
+     * Stable identifier for this node within the graph.
+     */
+    id: string;
+    /**
+     * Lookup File Uploads
+     *
+     * Inline lookup-file content for the typed create call. Each entry is uploaded and the resulting URI is appended to ``lookup_files``; this field is create-input only.
+     */
+    lookup_file_uploads?: Array<LookupFileUpload>;
+    /**
+     * Lookup Files
+     *
+     * Smart-lookup reference document URIs persisted on the extract node.
+     */
+    lookup_files?: Array<string>;
+    /**
+     * Lookup Reasoning Effort
+     *
+     * Reasoning effort for the smart-lookup matcher (gpt-5 family): minimal | low | medium | high. None = model default. Higher effort improves match reliability on noisy join keys at higher latency/cost.
+     */
+    lookup_reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high' | null;
+    /**
+     * Lookup Suggestion
+     *
+     * Free-form hint shown to the smart-lookup matcher.
+     */
+    lookup_suggestion?: string | null;
     /**
      * Mode
      *
-     * Parse tier. 'standard' (default): page-by-page parsing with reading-order correction — the best quality/speed balance for most documents and tables. 'agentic': adaptive parsing that works hardest on dense tables (50+ rows, many columns) — highest fidelity on complex documents; extra cost per page. 'lite' (shown as 'Fast' in the app): OCR-first tier, fastest and cheapest — accurate OCR by default; set skip_routing_review=False to add a correction pass when reading order, figures, or text formatting matter.
+     * Extraction tier. 'standard' (default): single-pass extraction — the best balance for simple documents and layouts. 'agentic': multi-step extraction that maps every table to the schema and reasons across sections — for dense or cross-page tables; extra cost per page. 'lite' (shown as 'Fast' in the app): standard extraction, faster and cheaper; quality may vary on complex layouts.
      */
     mode?: 'standard' | 'agentic' | 'lite';
     /**
-     * Ocr Effort
+     * Type
+     */
+    type: 'extract';
+    /**
+     * Use Images
      *
-     * Lite mode: 'high' (default) = the strongest OCR — best accuracy on complex layouts, tables, and handwriting, and usually all a document needs. 'medium' = faster and cheaper, for clean digital documents. (Distinct from agentic `effort`.)
+     * Standard/lite modes: send each PDF page's rendered image alongside its parsed text so the model can read layout the text missed — adds vision cost on every page.
      */
-    ocr_effort?: 'medium' | 'high';
+    use_images?: boolean;
+};
+/**
+ * PublicIfElseNode
+ */
+type PublicIfElseNode = {
     /**
-     * Prompt Hint
+     * Condition
+     */
+    condition: ({
+        type: 'range';
+    } & RangeCheck) | ({
+        type: 'date';
+    } & DateCheck) | ({
+        type: 'arithmetic';
+    } & ArithmeticCheck) | ({
+        type: 'comparison';
+    } & ComparisonCheck) | ({
+        type: 'one_of';
+    } & OneOfCheck) | ({
+        type: 'regex';
+    } & RegexCheck) | ({
+        type: 'required';
+    } & RequiredCheck) | ({
+        type: 'confidence';
+    } & ConfidenceCheck) | ({
+        type: 'expression';
+    } & ExpressionCheck) | ({
+        type: 'validation';
+    } & ValidationCheck) | ({
+        type: 'all_of';
+    } & AllOfCheck) | ({
+        type: 'any_of';
+    } & AnyOfCheck);
+    /**
+     * Id
      *
-     * Free-form hint that biases the parse output. In lite mode it guides the correction pass, so it requires skip_routing_review=False.
+     * Stable identifier for this node within the graph.
      */
-    prompt_hint?: string | null;
+    id: string;
+    /**
+     * Type
+     */
+    type: 'if_else';
+};
+/**
+ * PublicParseNode
+ */
+type PublicParseNode = {
     /**
-     * Region
+     * Cache
+     *
+     * Reuse parsed output when the same file was already parsed with the same mode and settings — a hit skips the whole parse. Disable to force a fresh parse.
+     */
+    cache?: boolean;
+    /**
+     * Effort
+     *
+     * Agentic mode: quality/cost preset. 'low' = several times cheaper but more errors on dense or low-contrast tables, 'mid' (default) = balanced, 'accurate' = highest fidelity. (Distinct from lite `ocr_effort`.)
+     */
+    effort?: 'low' | 'mid' | 'accurate';
+    /**
+     * Figure Enhancement
+     *
+     * Standard mode: extract structured data from charts and images — extra processing per figure. Ignored in agentic and in lite.
+     */
+    figure_enhancement?: boolean;
+    /**
+     * Id
+     *
+     * Stable identifier for this node within the graph.
+     */
+    id: string;
+    /**
+     * Mode
      *
-     * Lite mode: OCR data-residency. 'eu' keeps processing in-region; 'global' uses the hosted endpoint. Feature-flagged.
+     * Parse tier. 'standard' (default): page-by-page parsing with reading-order correction — the best quality/speed balance for most documents and tables. 'agentic': adaptive parsing that works hardest on dense tables (50+ rows, many columns) — highest fidelity on complex documents; extra cost per page. 'lite' (shown as 'Fast' in the app): OCR-only tier — accurate OCR, no LLM call; use standard or agentic when the output needs LLM correction. 'flash': the PDF's own text layer plus layout grounding, no model call — the cheapest and fastest tier; a page with no text layer is OCR'd by default (see scanned_pages).
      */
-    region?: 'eu' | 'global';
+    mode?: 'standard' | 'agentic' | 'lite' | 'flash';
     /**
-     * Routing Effort
+     * Ocr Effort
      *
-     * Lite mode: effort of the correction pass's reading-order analysis — its dominant latency knob (None = the highest). Lower it to cut latency on simple layouts.
+     * Lite mode: 'high' (default) = the strongest OCR — best accuracy on complex layouts, tables, and handwriting. 'medium' = faster and cheaper, for clean digital documents. (Distinct from agentic `effort`.)
      */
-    routing_effort?: 'minimal' | 'low' | 'medium' | 'high' | null;
+    ocr_effort?: 'medium' | 'high';
     /**
-     * Skip Routing Review
+     * Prompt Hint
      *
-     * Lite mode: emit the OCR output as-is (the default — fastest and cheapest). Set False to add a correction pass that fixes reading order and OCR errors and rebuilds broken tables; while True, figures/text_formatting/routing_effort/prompt_hint are inert.
+     * Free-form hint that biases the parse output. Standard and agentic modes only; ignored in lite.
      */
-    skip_routing_review?: boolean;
+    prompt_hint?: string | null;
     /**
-     * Text Formatting
+     * Scanned Pages
      *
-     * Lite mode: the correction pass restores inline styling (bold/italic/superscript), code, and LaTeX math in text blocks (needs skip_routing_review=False).
+     * Flash mode: what to do with a page whose text layer produced no words. 'ocr' (default): OCR the page and parse it like any other, at no extra model cost. 'skip': serve it blank and flag it, don't fail the parse. 'fail': raise, naming the page numbers.
      */
-    text_formatting?: boolean;
+    scanned_pages?: 'ocr' | 'skip' | 'fail';
     /**
      * Type
      */
     type: 'parse';
 };
 /**
- * ParseResult
+ * PublicSlackAlertNode
  *
- * Parsed markdown for a file.
+ * Terminal alert-sink. ``field_index`` is executor-injected — omitted here.
  */
-type ParseResult = {
+type PublicSlackAlertNode = {
+    /**
+     * Channel Id
+     */
+    channel_id: string;
+    /**
+     * Channel Name
+     */
+    channel_name: string;
+    /**
+     * Id
+     *
+     * Stable identifier for this node within the graph.
+     */
+    id: string;
+    /**
+     * Message Template
+     */
+    message_template: string;
     /**
-     * Blocks
-     *
-     * Structured per-block representation of the parsed document. One entry per `<a id></a>` anchor in document order, with type-specific structured data (`rows` for tables, `image_base64` for pictures) surfaced as first-class fields so consumers don't have to HTML-parse.
+     * Severity
      */
-    blocks?: Array<Block>;
+    severity?: 'info' | 'warning' | 'critical';
     /**
-     * Layout Confidence
-     *
-     * Document-level YOLO layout confidence on a 0-100 scale, char-weighted mean across all blocks. `null` if no annotated sections.
+     * Type
      */
-    layout_confidence?: number | null;
+    type: 'slack_alert';
+};
+/**
+ * PublicValidateNode
+ */
+type PublicValidateNode = {
     /**
-     * Markdown
+     * Id
      *
-     * Document content rendered as structured markdown. Each block is preceded by an empty `<a id="p{page}_b{idx}"></a>` anchor (invisible in any markdown renderer; the id joins to `blocks[].id` and can be used as an in-page link target). Image hydration for picture/figure blocks happens client-side. `null` if parsing failed.
+     * Stable identifier for this node within the graph.
      */
-    markdown: string | null;
+    id: string;
     /**
-     * Parse Confidence
-     *
-     * Document-level parse confidence on a 0-100 scale, char-weighted mean of per-block LLM logprob scores. `null` when no blocks have logprob-based confidence.
+     * Rules
      */
-    parse_confidence?: number | null;
+    rules: Array<ValidationRule>;
     /**
-     * Text
-     *
-     * Plain markdown with structural HTML removed — `<DOCUMENT>` framing, block anchors, `<img>` tags, and `<figure-content>` wrappers stripped. Useful when feeding the parsed output into an LLM or a search index that doesn't need the block-level metadata. `null` if `markdown` is null.
+     * Type
      */
-    text?: string | null;
+    type: 'validate';
 };
 /**
  * RangeCheck
@@ -1240,7 +1803,7 @@ type RangeCheck = {
     /**
      * Field
      *
-     * persistent_id of the bounded numeric field.
+     * The bounded numeric field. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     field: string;
     /**
@@ -1262,6 +1825,8 @@ type RangeCheck = {
 type RegexCheck = {
     /**
      * Field
+     *
+     * The field to match. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     field: string;
     /**
@@ -1281,6 +1846,8 @@ type RegexCheck = {
 type RequiredCheck = {
     /**
      * Field
+     *
+     * The field that must be present. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     field: string;
     /**
@@ -1289,14 +1856,12 @@ type RequiredCheck = {
     type: 'required';
 };
 /**
- * ResultsResponse
+ * ResultsResponseV3
  *
- * Canonical response shape for the file-collection results endpoint.
- *
- * Returned with HTTP 200 once processing completes. Returns 412 while processing is
- * in progress; poll until 200, or use webhooks.
+ * v3-scoped results envelope — same shape as ``ResultsResponse`` minus the
+ * legacy ``collection_id`` alias. v3 emits only ``document_packet_id``.
  */
-type ResultsResponse = {
+type ResultsResponseV3 = {
     /**
      * Classifications
      *
@@ -1304,11 +1869,17 @@ type ResultsResponse = {
      */
     classifications?: Array<ClassificationResult>;
     /**
-     * Collection Id
+     * Document Packet Id
+     *
+     * The document packet's UUID — v3 canonical name for `collection_id`. Same value; both fields are always present.
+     */
+    document_packet_id: string;
+    /**
+     * Edits
      *
-     * The file collection's UUID. Same value as the `id` returned by `POST /v2/workflows/{wid}/run/`.
+     * Filled-form output, one entry per file an edit node processed. Empty when the workflow has no edit node.
      */
-    collection_id: string;
+    edits?: Array<Edit>;
     /**
      * Extraction
      *
@@ -1344,6 +1915,98 @@ type ResultsResponse = {
      */
     verification_url?: string | null;
 };
+/**
+ * RunDetailV3
+ *
+ * Flat single-run read: lifecycle status plus results inline.
+ *
+ * `results` is `null` until the run reaches `processed`, then carries the
+ * same results envelope `GET /v2/workflows/{id}/files/{id}/results/`
+ * returns — no separate results endpoint, no 412 while in flight.
+ */
+type RunDetailV3 = {
+    /**
+     * Created At
+     *
+     * Timestamp when the run was triggered (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Document Packet Id
+     *
+     * The document packet the run executed on (hyphenated UUID).
+     */
+    document_packet_id: string;
+    /**
+     * Id
+     *
+     * Unique identifier of the run (hyphenated UUID).
+     */
+    id: string;
+    /**
+     * Extraction results envelope; `null` until `status` is `processed`. Same shape as the v2 results endpoint.
+     */
+    results?: ResultsResponseV3 | null;
+    /**
+     * Execution status. Non-terminal: `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
+     */
+    status: RunStatus;
+    /**
+     * Updated At
+     *
+     * Timestamp of the run's last status change (ISO 8601).
+     */
+    updated_at?: string | null;
+    /**
+     * Workflow Id
+     *
+     * The workflow this run executed (hyphenated UUID).
+     */
+    workflow_id: string;
+};
+/**
+ * RunStatus
+ *
+ * Execution lifecycle of a run. Non-terminal: ``queued``,
+ * ``in_progress``. Terminal: ``processed`` (success), ``error``,
+ * ``cancelled``.
+ */
+type RunStatus = 'queued' | 'in_progress' | 'processed' | 'error' | 'cancelled';
+/**
+ * RunSummaryV3
+ *
+ * Slim run projection returned by list pages.
+ */
+type RunSummaryV3 = {
+    /**
+     * Created At
+     *
+     * Timestamp when the run was triggered (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Document Packet Id
+     *
+     * The document packet the run executes on (hyphenated UUID).
+     */
+    document_packet_id: string;
+    /**
+     * Id
+     *
+     * Unique identifier of the run (hyphenated UUID).
+     */
+    id: string;
+    /**
+     * Execution status. Non-terminal: `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
+     */
+    status: RunStatus;
+    /**
+     * Updated At
+     *
+     * Timestamp of the run's last status change (ISO 8601).
+     */
+    updated_at?: string | null;
+};
 /**
  * SplitPartition
  *
@@ -1353,9 +2016,9 @@ type SplitPartition = {
     /**
      * Confidence
      *
-     * 0-100 minimum confidence across the partition's ranges.
+     * 0-100 minimum confidence across the partition's ranges. `null` when the partition holds no page, because nothing was measured.
      */
-    confidence: number;
+    confidence: number | null;
     /**
      * Files
      */
@@ -1378,9 +2041,9 @@ type SplitResult = {
     /**
      * Confidence
      *
-     * 0-100 aggregate confidence (min across partitions).
+     * 0-100 aggregate confidence (min across partitions). `null` when the category matched no page, because nothing was measured.
      */
-    confidence: number;
+    confidence: number | null;
     /**
      * Files
      *
@@ -1454,10 +2117,6 @@ type StringField = {
      * Free-form description shown to the extraction model.
      */
     description?: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * Name
      *
@@ -1467,36 +2126,103 @@ type StringField = {
     /**
      * Persistent Id
      *
-     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit for new fields; when omitted on an update, the server matches the field to the prior version by name.
+     * Server-assigned stable field identity (UUID), emitted by GET /definition/. Echo it back on updates — including across renames — to keep quality metrics, ground-truth links and analytics attached to the field. Matching is scoped to the field's nesting level in the immediately-prior version; an id that matches nothing at its level, appears on more than one field, or is sent at workflow creation is rejected with 400. Omit only for genuinely new fields: there is no matching by name, so a field sent without one is always treated as new and minted a fresh id, silently detaching that field's metrics, ground truth and analytics.
      */
     persistent_id?: string | null;
+    /**
+     * Source
+     *
+     * How the field gets its value: extraction (from the document), smart_lookup (from the lookup file, always overwrites) or lookup_if_missing (extracted too; the lookup only fills it where extraction left no value).
+     */
+    source?: 'extraction' | 'smart_lookup' | 'lookup_if_missing';
 };
 /**
- * ValidateNode
+ * Validation
+ *
+ * A configured rule verdict or an automatic extraction review warning.
  */
-type ValidateNode = {
+type Validation = {
     /**
-     * Field Index
+     * Compared Values
      *
-     * Executor-injected at run time (persistent_id → field name); never set by callers or persisted.
+     * The field values the rule looked at, keyed by field name. `null` when nothing was compared.
      */
-    field_index?: {
-        [key: string]: string;
+    compared_values?: {
+        [key: string]: unknown;
     } | null;
     /**
-     * Id
+     * Description
      *
-     * Stable identifier for this node within the graph.
+     * The rule's natural-language description; empty for a deterministic rule.
      */
-    id: string;
+    description?: string;
     /**
-     * Rules
+     * Detail
+     *
+     * Human-readable explanation of the verdict.
      */
-    rules: Array<ValidationRule>;
+    detail?: string;
+    /**
+     * Rule Id
+     *
+     * The configured rule ID, or an `extract.consolidation:` ID for an automatic review warning.
+     */
+    rule_id: string;
+    /**
+     * Severity
+     *
+     * `error` or `warning`, as declared on the rule.
+     */
+    severity: string;
+    /**
+     * Source Fields
+     *
+     * `persistent_id`s of the rule's inputs. Empty for automatic extraction warnings; field names are in `compared_values`.
+     */
+    source_fields?: Array<string>;
+    /**
+     * Status
+     *
+     * `pass`, `fail`, or `inconclusive` — the last one when the rule could not be evaluated (no data, an unanswerable expression).
+     */
+    status: string;
+};
+/**
+ * ValidationCheck
+ *
+ * Routes on the outcome of a named validation rule already run upstream.
+ *
+ * Reads from ``state.validation_results`` (populated by an upstream
+ * ``ValidateNode``), filtered to the current partition (``split_id``) so
+ * per-partition IfElse routing matches per-partition rule outcomes. The
+ * ``status`` values mirror the worker enum
+ * (``anyformat_core.operations.validate_rules`` — ``pass`` / ``fail`` /
+ * ``inconclusive``) verbatim: no translation layer, so template tokens
+ * like ``${validation.<rule_id>.status}`` render the same three strings
+ * the enum uses.
+ *
+ * Unlike every other ``Check`` variant this consumes no extracted fields
+ * (``field_ids`` returns ``[]``); the rule identity is the entire input.
+ * A ``rule_id`` with no matching entry evaluates to ``inconclusive`` — the
+ * rule didn't run for this partition, so the outcome is unknown.
+ */
+type ValidationCheck = {
+    /**
+     * Rule Id
+     *
+     * Stable id of the upstream ValidationRule to route on.
+     */
+    rule_id: string;
+    /**
+     * Status
+     *
+     * Outcome to match. ``fail`` (default) is the common case for routing to an alert branch.
+     */
+    status?: 'fail' | 'pass' | 'inconclusive';
     /**
      * Type
      */
-    type: 'validate';
+    type: 'validation';
 };
 /**
  * ValidationRule
@@ -1521,7 +2247,17 @@ type ValidationRule = {
         type: 'regex';
     } & RegexCheck) | ({
         type: 'required';
-    } & RequiredCheck) | null;
+    } & RequiredCheck) | ({
+        type: 'confidence';
+    } & ConfidenceCheck) | ({
+        type: 'expression';
+    } & ExpressionCheck) | ({
+        type: 'validation';
+    } & ValidationCheck) | ({
+        type: 'all_of';
+    } & AllOfCheck) | ({
+        type: 'any_of';
+    } & AnyOfCheck) | null;
     /**
      * Description
      *
@@ -1569,10 +2305,11 @@ type ValidationRule = {
  * (``kind="deterministic"`` + a structured ``check``, evaluated in pure
  * Python with no model call).
  *
- * Defined as a thin subclass so the FastAPI-generated OpenAPI components
- * entry is named ``WorkflowCreateRequest`` (FastAPI uses the model's
- * ``__name__``). Behaviour is fully inherited from
- * ``WorkflowDefinition`` in ``anyformat.workflow``.
+ * Uses ``PublicNode`` (public request models with only the fields callers
+ * may set); the domain ``AnyNode`` also carries ``filter`` (worker-only)
+ * and executor-injected / staff-only fields, so the public bodies pin a
+ * stricter node schema. Call :meth:`to_domain` before forwarding to the
+ * backend.
  */
 type WorkflowCreateRequest = {
     /**
@@ -1590,7 +2327,96 @@ type WorkflowCreateRequest = {
     /**
      * Nodes
      */
-    nodes: Array<ParseNode | ClassifyNode | SplitterNode | ExtractNode | ValidateNode>;
+    nodes: Array<PublicParseNode | ClassifyNode | SplitterNode | PublicExtractNode | PublicValidateNode | PublicIfElseNode | PublicSlackAlertNode | PublicEditNode | KnowledgeNode>;
+};
+/**
+ * WorkflowDetailV3
+ *
+ * A workflow with its complete typed graph inline.
+ *
+ * ``{name, description, nodes, edges}`` is the exact shape
+ * ``POST /v3/workflows/`` accepts — mutate it and feed it back to edit.
+ */
+type WorkflowDetailV3 = {
+    /**
+     * Created At
+     *
+     * Timestamp when the workflow was created (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Description
+     *
+     * Optional description of what this workflow extracts.
+     */
+    description?: string | null;
+    /**
+     * Edges
+     *
+     * Directed edges between the graph nodes.
+     */
+    edges?: Array<Edge>;
+    /**
+     * Id
+     *
+     * Unique identifier of the workflow (hyphenated UUID).
+     */
+    id: string;
+    /**
+     * Name
+     *
+     * Human-readable name of the workflow.
+     */
+    name: string;
+    /**
+     * Nodes
+     *
+     * Typed graph nodes (parse / classify / splitter / extract / validate / if_else).
+     */
+    nodes: Array<PublicParseNode | ClassifyNode | SplitterNode | PublicExtractNode | PublicValidateNode | PublicIfElseNode | PublicSlackAlertNode | PublicEditNode | KnowledgeNode>;
+    /**
+     * Updated At
+     *
+     * Timestamp when the workflow was last modified (ISO 8601).
+     */
+    updated_at?: string | null;
+};
+/**
+ * WorkflowSummaryV3
+ *
+ * Slim workflow projection returned by create and list.
+ */
+type WorkflowSummaryV3 = {
+    /**
+     * Created At
+     *
+     * Timestamp when the workflow was created (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Description
+     *
+     * Optional description of what this workflow extracts.
+     */
+    description?: string | null;
+    /**
+     * Id
+     *
+     * Unique identifier of the workflow (hyphenated UUID).
+     */
+    id: string;
+    /**
+     * Name
+     *
+     * Human-readable name of the workflow.
+     */
+    name: string;
+    /**
+     * Updated At
+     *
+     * Timestamp when the workflow was last modified (ISO 8601).
+     */
+    updated_at?: string | null;
 };
 /**
  * _FieldOperand
@@ -1599,7 +2425,7 @@ type FieldOperand = {
     /**
      * Field
      *
-     * persistent_id of the compared field.
+     * The compared field. Either the field's ``persistent_id`` (Studio field-picker path) or its ``sanitized_name`` as it appears in the extraction response (SDK/API/assistant path) — the executor resolves both.
      */
     field: string;
     /**
@@ -1657,12 +2483,18 @@ type ExtractedField<T = unknown> = Omit<ExtractedField$1, "value" | "value_overr
     value: T | null;
     value_override?: T | null;
 };
+/**
+ * A list/object-array field (e.g. `line_items`): one entry per row, each row a
+ * record of named `ExtractedField`s. This is the shape `field()` returns for a
+ * non-scalar field.
+ */
+type ExtractedRows = Array<Record<string, ExtractedField>>;
 /** Typed wrapper over a completed run's results. */
 declare class Result {
-    readonly raw: ResultsResponse;
+    readonly raw: ResultsResponseV3;
     private _parse;
-    constructor(raw: ResultsResponse);
-    get collectionId(): string;
+    constructor(raw: ResultsResponseV3);
+    get documentPacketId(): string;
     get extractions(): Extraction[];
     /**
      * Typed view over the parse node's output, or `null` when the workflow has
@@ -1670,57 +2502,148 @@ declare class Result {
      */
     get parse(): ParseView | null;
     /**
-     * Convenience accessor for a top-level scalar field on the first
-     * extraction (linear workflows). Returns `undefined` for missing fields
-     * or list-valued fields — read `extractions` directly for those.
+     * Convenience accessor for a top-level field on the untagged (linear)
+     * extraction. Returns the scalar `ExtractedField` for a scalar field, or
+     * the array of row records (`ExtractedRows`) for a list/object field such
+     * as `line_items`. `undefined` only when the field is absent.
      *
-     * Parameterise with the declared schema type to type `.value`:
+     * Parameterise with the declared schema type to type a scalar's `.value`:
      * `result.field<number>("total").value` is `number | null`.
      */
-    field<T = unknown>(name: string): ExtractedField<T> | undefined;
+    field<T = unknown>(name: string): ExtractedField<T> | ExtractedRows | undefined;
 }
 
 interface WaitOptions {
     /** Overall budget before giving up. Default 300 000 ms (300s). */
     timeoutMs?: number;
-    /** Delay between result polls. Default 3 000 ms (3s). */
+    /** Delay between status polls. Default 3 000 ms (3s). */
     pollMs?: number;
 }
 /**
- * A submitted run. `wait()` polls for completion. Created eagerly by
- * `Workflow.run()` — the workflow + file submission have already happened
- * by the time you hold a `Run`.
+ * One execution attempt of a workflow against a document packet. Created
+ * eagerly by the run triggers — the extraction is already enqueued by the
+ * time you hold a `Run`. `wait()` polls `GET /v3/runs/{run_id}/` until the
+ * status is terminal and returns the inline results.
  */
 declare class Run {
     private readonly client;
-    readonly workflowId: string;
     readonly id: string;
+    readonly workflowId: string;
+    readonly documentPacketId: string;
+    /** Status at trigger time, refreshed on every `wait()` poll. */
+    status: RunStatus;
     /** @internal */
-    constructor(client: Client, workflowId: string, id: string);
+    constructor(client: Client, id: string, workflowId: string, documentPacketId: string, status?: RunStatus);
     wait(opts?: WaitOptions): Promise<Result>;
 }
 
+interface RunTriggerOptions {
+    /**
+     * Caller-supplied key (Stripe convention). Retrying with the same key
+     * returns the original run instead of triggering (and billing) a second
+     * extraction.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Options for the methods that stage an upload (`Workflow.run`,
+ * `Workflow.upload`). Adds the filename-conflict policy on top of the
+ * run-trigger options — it only applies where files are actually uploaded,
+ * which is why the run-only paths (`Upload.run`, `Anyformat.runDocumentPacket`)
+ * take {@link RunTriggerOptions} instead and don't accept it.
+ */
+interface UploadOptions extends RunTriggerOptions {
+    /**
+     * How the server resolves an uploaded filename that already exists in the
+     * workflow (filenames are unique within a workflow). `"error"` (the server
+     * default) rejects the whole upload with `409`; `"rename"` auto-renames
+     * (`invoice.pdf` → `invoice (1).pdf`). Omit to use the server default.
+     */
+    onConflict?: "error" | "rename";
+}
+/**
+ * Options for URL imports. The server derives the filename from each URL, so
+ * there is no idempotency key — only the conflict policy applies.
+ */
+interface UploadFromUrlsOptions {
+    /** See {@link UploadOptions.onConflict}. Omit to use the server default. */
+    onConflict?: "error" | "rename";
+}
+/**
+ * Options for a dataset upload (`Workflow.uploadToDataset`), mirroring the
+ * regular upload's conflict policy.
+ */
+interface DatasetUploadOptions {
+    /**
+     * The expected document (ground truth) for this document packet, as a plain
+     * object — the SDK JSON-encodes it for the multipart field. Keys are the
+     * workflow schema's field identifiers (advertise `persistent_id`); a scalar
+     * field maps to `string | null`, a table/object field to an array of row
+     * objects. Ground truth attaches to the workflow's current version.
+     */
+    groundTruth?: Record<string, unknown> | null;
+    /**
+     * Caller-supplied key (Stripe convention). Retrying with the same key
+     * replays the original document packet instead of registering a duplicate
+     * document.
+     */
+    idempotencyKey?: string;
+    /**
+     * Filename-collision policy. Omit to use the server default (`error`): a
+     * colliding name fails with `409`. `rename` auto-renames the collision and
+     * the returned file's `original_name` holds the name you sent.
+     */
+    onConflict?: "error" | "rename";
+}
+/**
+ * One document for a bulk dataset upload: 1..100 files plus optional
+ * ground truth. Mirrors the arguments of `Workflow.uploadToDataset`.
+ */
+interface DatasetDocument {
+    /** 1..10 named files forming ONE document (one document packet in the dataset). */
+    files: File | File[];
+    /** See {@link DatasetUploadOptions.groundTruth}. */
+    groundTruth?: Record<string, unknown> | null;
+    /** See {@link DatasetUploadOptions.idempotencyKey}. */
+    idempotencyKey?: string;
+    /** See {@link DatasetUploadOptions.onConflict}. */
+    onConflict?: "error" | "rename";
+}
 /**
- * A document staged in a workflow but not yet run. Returned by
- * `Workflow.upload()`. Call `run()` to start extraction — uploading alone
- * spends no credits.
+ * One document registered into a workflow's dataset as one
+ * document packet. Returned by `Workflow.uploadToDataset()`. `documentPacketId` is the
+ * stable handle for the document; `groundTruthSaved` is `true` only when
+ * ground truth was supplied and stored.
+ */
+declare class DatasetUpload {
+    readonly workflowId: string;
+    readonly documentPacketId: string;
+    readonly files: DatasetUploadFileV3[];
+    readonly groundTruthSaved: boolean;
+    /** @internal */
+    constructor(workflowId: string, documentPacketId: string, files: DatasetUploadFileV3[], groundTruthSaved: boolean);
+}
+/**
+ * A document packet staged in a workflow but not yet run. Returned by
+ * `Workflow.upload()` / `Workflow.uploadFromUrls()`. Call `run()` to start
+ * extraction — uploading alone spends no credits.
  */
 declare class Upload {
     private readonly client;
     readonly workflowId: string;
-    readonly collectionId: string;
-    readonly fileId: string | null;
+    readonly documentPacketId: string;
+    readonly files: DocumentPacketFileV3[];
     /** @internal */
-    constructor(client: Client, workflowId: string, collectionId: string, fileId: string | null);
-    /** Trigger extraction on the staged file and return a pending `Run`. */
-    run(): Promise<Run>;
+    constructor(client: Client, workflowId: string, documentPacketId: string, files: DocumentPacketFileV3[]);
+    /** Trigger extraction on the staged packet and return a pending `Run`. */
+    run(opts?: RunTriggerOptions): Promise<Run>;
 }
 
 /**
  * A persisted workflow on the server. Returned by `WorkflowBuilder.create()`.
- * `run(file)` submits a document and returns a `Run` you can `.wait()` on.
- * `upload(file)` stages a document without running it; call `.run()` on the
- * returned `Upload` to extract.
+ * `run(files)` uploads a document packet and starts extraction, returning a
+ * `Run` you can `.wait()` on. `upload(files)` stages a packet without
+ * running it; call `.run()` on the returned `Upload` to extract.
  */
 declare class Workflow {
     private readonly client;
@@ -1728,13 +2651,33 @@ declare class Workflow {
     readonly name: string;
     /** @internal */
     constructor(client: Client, id: string, name: string);
-    /** Submit a document against this workflow and return a pending `Run`. */
-    run(file?: File | null): Promise<Run>;
+    /** Upload 1..100 files as one document packet and run it. Returns a pending `Run`. */
+    run(files?: File | File[] | null, opts?: UploadOptions): Promise<Run>;
+    /**
+     * Stage 1..100 files as one document packet WITHOUT running it (no credits
+     * spent). Returns an `Upload`; call `.run()` on it to start extraction.
+     */
+    upload(files?: File | File[] | null, opts?: UploadOptions): Promise<Upload>;
+    /**
+     * Upload 1..100 files as ONE document (+ optional ground truth) into the
+     * workflow's dataset, as one document packet. Atomic: any rejected file or a
+     * ground-truth failure fails the call and stores nothing. By default a
+     * colliding filename fails with `409`; pass `onConflict: "rename"` to
+     * auto-rename instead.
+     */
+    uploadToDataset(files?: File | File[] | null, opts?: DatasetUploadOptions): Promise<DatasetUpload>;
+    /**
+     * Client-orchestrated bulk dataset upload: one atomic call per document,
+     * in order. There is no batch endpoint — each document is bounded and
+     * independently retryable. On failure the call rejects; documents already
+     * uploaded stay registered.
+     */
+    uploadDocumentsToDataset(documents: DatasetDocument[]): Promise<DatasetUpload[]>;
     /**
-     * Stage a document in this workflow WITHOUT running it (no credits spent).
+     * Import 1..10 HTTPS URLs server-side into one document packet, atomically.
      * Returns an `Upload`; call `.run()` on it to start extraction.
      */
-    upload(file?: File | null): Promise<Upload>;
+    uploadFromUrls(urls: string[], opts?: UploadFromUrlsOptions): Promise<Upload>;
 }
 
 /** Any extraction field — the discriminated union on `data_type`. */
@@ -1744,37 +2687,52 @@ type Field = ExtractionSchema["fields"][number];
  * level of nesting is supported, so objects cannot contain objects.
  */
 type NestedField = ObjectField["nested_fields"][number];
-type LookupOpt = {
-    lookup?: boolean;
-};
+interface FieldOpts {
+    /**
+     * How the field gets its value: `"extraction"` (from the document,
+     * the default), `"smart_lookup"` (from the lookup file, always
+     * overwrites) or `"lookup_if_missing"` (extracted too; the lookup only
+     * fills it where extraction left no value).
+     */
+    source?: "extraction" | "smart_lookup" | "lookup_if_missing";
+    /**
+     * Server-assigned stable field identity from `GET /v3/workflows/{id}/`.
+     * Echo it on updates — including across renames — to keep quality
+     * metrics, ground truth and analytics attached to the field. Omit for
+     * new fields.
+     */
+    persistentId?: string;
+}
 /**
  * Factory for extraction-schema fields — the TS mirror of the Python
  * `Schema` facade. Each method returns the typed wire model the API
  * validates against; the discriminator (`data_type`) is filled in for you.
  */
 declare const Schema: {
-    string: (name: string, description: string, opts?: LookupOpt) => StringField;
-    integer: (name: string, description: string, opts?: LookupOpt) => IntegerField;
-    float: (name: string, description: string, opts?: LookupOpt) => FloatField;
-    boolean: (name: string, description: string, opts?: LookupOpt) => BooleanField;
-    date: (name: string, description: string, opts?: LookupOpt) => DateField;
-    datetime: (name: string, description: string, opts?: LookupOpt) => DatetimeField;
-    enum: (name: string, description: string, options: EnumOption[], opts?: LookupOpt) => EnumField;
-    multiSelect: (name: string, description: string, options: EnumOption[], opts?: LookupOpt) => MultiSelectField;
-    object: (name: string, description: string, fields: NestedField[], opts?: LookupOpt) => ObjectField;
+    string: (name: string, description: string, opts?: FieldOpts) => StringField;
+    integer: (name: string, description: string, opts?: FieldOpts) => IntegerField;
+    float: (name: string, description: string, opts?: FieldOpts) => FloatField;
+    boolean: (name: string, description: string, opts?: FieldOpts) => BooleanField;
+    date: (name: string, description: string, opts?: FieldOpts) => DateField;
+    datetime: (name: string, description: string, opts?: FieldOpts) => DatetimeField;
+    enum: (name: string, description: string, options: EnumOption[], opts?: FieldOpts) => EnumField;
+    multiSelect: (name: string, description: string, options: EnumOption[], opts?: FieldOpts) => MultiSelectField;
+    object: (name: string, description: string, fields: NestedField[], opts?: FieldOpts) => ObjectField;
     option: (name: string, description: string) => EnumOption;
 };
 
-type ExtractMode = "standard" | "agentic" | "max" | "lite";
+type ExtractMode = "standard" | "agentic" | "lite";
 type AgenticEffort = "low" | "mid" | "accurate";
-type OcrEffort = "medium" | "high";
-type OcrRegion = "eu" | "global";
-type RoutingEffort = "minimal" | "low" | "medium" | "high";
+type ScannedPages = "ocr" | "skip" | "fail";
+/** How much reasoning a node asks a model for. Taken from the generated wire types, which
+ *  follow the Python `ReasoningEffort` alias, so a new level needs no edit here.
+ *  The Python gives `ExtractNode.lookup_reasoning_effort`
+ *  that same alias, so one of the two fields derives the type for both. */
+type ReasoningEffort = NonNullable<PublicExtractNode["lookup_reasoning_effort"]>;
 /** Source-port label routing into an extract/validate node. */
 type Branch = string | ClassifyCategory | SplitterRule;
 /** Knobs shared by every parse mode. */
 interface ParseOptionsBase {
-    promptHint?: string;
     figureEnhancement?: boolean;
     cache?: boolean;
     id?: string;
@@ -1782,21 +2740,22 @@ interface ParseOptionsBase {
 /**
  * Parse options as a `mode`-discriminated union: each mode only accepts its own knobs, so a lite
  * knob on `{ mode: "standard" }` is a compile-time error rather than a silent no-op. `mode` is
- * optional only on the standard variant (the default), required on agentic/lite.
+ * optional only on the standard variant (the default), required on agentic/lite. Lite has no
+ * knobs of its own — one recipe, OCR-only — and never reads `promptHint`.
  */
 type ParseOptions = (ParseOptionsBase & {
     mode?: "standard";
+    promptHint?: string;
 }) | (ParseOptionsBase & {
     mode: "agentic";
     effort?: AgenticEffort;
+    promptHint?: string;
 }) | (ParseOptionsBase & {
     mode: "lite";
-    ocrEffort?: OcrEffort;
-    region?: OcrRegion;
-    skipRoutingReview?: boolean;
-    figures?: boolean;
-    textFormatting?: boolean;
-    routingEffort?: RoutingEffort;
+}) | (ParseOptionsBase & {
+    mode: "flash";
+    scannedPages?: ScannedPages;
+    promptHint?: string;
 });
 /**
  * Fluent assembler for a typed workflow graph — a faithful TS port of the
@@ -1833,7 +2792,7 @@ declare class WorkflowBuilder {
         mode?: ExtractMode;
         lookupFiles?: string[];
         lookupSuggestion?: string;
-        lookupReasoningEffort?: RoutingEffort;
+        lookupReasoningEffort?: ReasoningEffort;
         useImages?: boolean;
     }): this;
     validate(rules: ValidationRule[], opts?: {
@@ -1844,9 +2803,9 @@ declare class WorkflowBuilder {
     private normalizeExtractBranch;
     /** Assemble the wire request (branch-routed edges). Pure — no network. */
     build(): WorkflowCreateRequest;
-    /** Persist the workflow and return a handle you can `.run(file)` on. */
+    /** Persist the workflow and return a handle you can `.run(files)` on. */
     create(): Promise<Workflow>;
-    /** Replace an existing workflow's definition and return a handle you can `.run(file)` on. */
+    /** Replace an existing workflow's typed graph and return a handle you can `.run(files)` on. */
     update(workflowId: string): Promise<Workflow>;
 }
 
@@ -1855,70 +2814,155 @@ interface AnyformatOptions {
     /** Override the API base URL (defaults to production). */
     baseUrl?: string;
 }
+/** One keyset page. Follow `nextCursor` (pass it as `cursor`) until it is `null`. */
+interface Page<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+interface ListOptions {
+    /** Page size, capped at 100 by the API. */
+    limit?: number;
+    /** Opaque token from a previous page's `nextCursor`. */
+    cursor?: string;
+}
+interface IterOptions {
+    /** Page size the auto-pager fetches per underlying request, capped at 100 by the API. */
+    limit?: number;
+}
+/**
+ * The editable sub-shape of a workflow: exactly what `GET /v3/workflows/{id}/`
+ * returns minus the read-only fields, and exactly what PATCH accepts — so a
+ * fetched `WorkflowDetailV3` can be mutated and sent back as-is.
+ */
+type WorkflowDefinition = Pick<WorkflowDetailV3, "name" | "description" | "nodes" | "edges">;
 /** Entry point. `new Anyformat({ apiKey }).workflow("name").parse()...` */
 declare class Anyformat {
     /** @internal */
     readonly _client: Client;
     constructor(opts: AnyformatOptions);
     workflow(name: string, description?: string): WorkflowBuilder;
-    listWorkflows(opts?: {
-        page?: number;
-        pageSize?: number;
-        status?: string;
-    }): Promise<Workflow[]>;
-    deleteWorkflow(workflowId: string): Promise<string>;
-    /** Stage a document in a workflow without running it. Returns an `Upload`. */
-    upload(workflowId: string, file?: File | null): Promise<Upload>;
-    /** Trigger extraction on already-uploaded files. Returns a pending `Run` per file_id. */
-    runWorkflow(workflowId: string, fileIds: string[]): Promise<Run[]>;
+    listWorkflows(opts?: ListOptions): Promise<Page<Workflow>>;
+    /** Retrieve a workflow with its complete typed graph inline (round-trippable into `updateWorkflow`). */
+    getWorkflow(workflowId: string): Promise<WorkflowDetailV3>;
     /**
-     * Parse a document with the platform's atomic `/parse` operation (fast lite
-     * parse). Returns an opaque `jobId`; poll `getParseMarkdown(jobId)` for the
-     * parsed markdown.
+     * Replace a workflow's typed graph (atomic). Accepts the shape `getWorkflow`
+     * returns — echo each field's `persistent_id` unchanged (including across
+     * renames) to keep the field's identity; omit it for new fields.
+     */
+    updateWorkflow(workflowId: string, definition: WorkflowDefinition): Promise<WorkflowDetailV3>;
+    deleteWorkflow(workflowId: string): Promise<string>;
+    /** Stage 1..100 files as one document packet without running it. Returns an `Upload`. */
+    upload(workflowId: string, files: File | File[], opts?: UploadOptions): Promise<Upload>;
+    /** Upload 1..100 files (+ optional ground truth) as one dataset collection. Returns a `DatasetUpload`. */
+    uploadToDataset(workflowId: string, files: File | File[], opts?: DatasetUploadOptions): Promise<DatasetUpload>;
+    /** Bulk-upload documents into a workflow's dataset, one atomic call per document. */
+    uploadDocumentsToDataset(workflowId: string, documents: DatasetDocument[]): Promise<DatasetUpload[]>;
+    getDocumentPacket(documentPacketId: string): Promise<DocumentPacketDetailV3>;
+    /** Delete a document packet and all its files. Irreversible. */
+    deleteDocumentPacket(documentPacketId: string): Promise<string>;
+    /** Run (or re-run) a document packet on the latest version of its workflow. */
+    runDocumentPacket(documentPacketId: string, opts?: RunTriggerOptions): Promise<Run>;
+    listDocumentPackets(workflowId: string, opts?: ListOptions): Promise<Page<DocumentPacketSummaryV3>>;
+    listRuns(workflowId: string, opts?: ListOptions): Promise<Page<RunSummaryV3>>;
+    /**
+     * Every workflow, following `nextCursor` across pages so no rows are silently
+     * truncated. Lazy — each page is fetched on demand as the iterator advances.
+     */
+    iterWorkflows(opts?: IterOptions): AsyncIterableIterator<Workflow>;
+    /** Every document packet of a workflow, following `nextCursor` across pages. Lazy. */
+    iterDocumentPackets(workflowId: string, opts?: IterOptions): AsyncIterableIterator<DocumentPacketSummaryV3>;
+    /** Every run of a workflow, following `nextCursor` across pages. Lazy. */
+    iterRuns(workflowId: string, opts?: IterOptions): AsyncIterableIterator<RunSummaryV3>;
+    /** Retrieve one run: lifecycle status plus results inline once `processed`. */
+    getRun(runId: string): Promise<RunDetailV3>;
+    /**
+     * Parse a document with the platform's atomic parse operation (fast lite
+     * parse). Returns the run id; poll `getParseMarkdown(runId)` for the parsed
+     * markdown.
      */
     parse(file: Blob | File): Promise<string>;
     /**
-     * Poll a parse job. Returns the parsed markdown once the job is done, or
-     * `null` while it is still processing.
+     * Poll a parse run. Returns the parsed markdown once the run is `processed`,
+     * or `null` while it is still queued or in progress.
      */
-    getParseMarkdown(jobId: string): Promise<string | null>;
+    getParseMarkdown(runId: string): Promise<string | null>;
 }
 
 declare class AnyformatError extends Error {
 }
+/** Any JSON value the envelope's free-shaped `detail` may carry. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** One field-level failure; the `detail` convention of validation errors. */
+interface ValidationItem {
+    type: string;
+    loc: (string | number)[];
+    msg: string;
+}
+/** A `params` value: a scalar, `null`, or an array of those. */
+type ScalarOrList = string | number | boolean | null | (string | number | boolean | null)[];
 declare class APIError extends AnyformatError {
     readonly status: number;
     readonly body?: unknown | undefined;
+    /** Stable identifier for programmatic handling, e.g. `PAYMENT_REQUIRED`. */
+    readonly errorCode?: string;
+    /** Developer-facing explanation; not surfaced in `message` (ADR platform/0053 §2). Often a `ValidationItem[]`. */
+    readonly detail?: JsonValue;
+    /** Named substitutions the `error` summary refers to, e.g. `{ required_scope }`. */
+    readonly params?: Record<string, ScalarOrList>;
+    /** Whether the API says retrying the same request can succeed. */
+    readonly retryable?: boolean;
+    /** Correlation id to quote in support requests. */
+    readonly requestId?: string;
     constructor(status: number, message: string, body?: unknown | undefined);
 }
 declare class BadRequestError extends APIError {
 }
 declare class UnauthorizedError extends APIError {
 }
+declare class PaymentRequiredError extends APIError {
+}
 declare class ForbiddenError extends APIError {
 }
 declare class NotFoundError extends APIError {
 }
 declare class RateLimitedError extends APIError {
+    /** Seconds the API asks the caller to wait, from the `Retry-After` header; `undefined` when absent. */
+    readonly retryAfter?: number | undefined;
+    constructor(status: number, message: string, body?: unknown, 
+    /** Seconds the API asks the caller to wait, from the `Retry-After` header; `undefined` when absent. */
+    retryAfter?: number | undefined);
 }
 declare class ServerError extends APIError {
 }
-/** @deprecated Use `BadRequestError`. Alias for one minor release. */
-declare const BadRequest: typeof BadRequestError;
-/** @deprecated Use `UnauthorizedError`. Alias for one minor release. */
-declare const Unauthorized: typeof UnauthorizedError;
-/** @deprecated Use `ForbiddenError`. Alias for one minor release. */
-declare const Forbidden: typeof ForbiddenError;
-/** @deprecated Use `NotFoundError`. Alias for one minor release. */
-declare const NotFound: typeof NotFoundError;
-/** @deprecated Use `RateLimitedError`. Alias for one minor release. */
-declare const RateLimited: typeof RateLimitedError;
+/** The API key lacks the scope this call needs (`insufficient_api_key_scope`). */
+declare class InsufficientScopeError extends ForbiddenError {
+}
+/** The caller must accept the terms of service first (`terms_acceptance_required`). */
+declare class TermsAcceptanceRequiredError extends ForbiddenError {
+}
+/** A workflow with that name already exists (`WORKFLOW_NAME_CONFLICT`). */
+declare class WorkflowNameConflictError extends APIError {
+}
 declare class SDKTimeoutError extends AnyformatError {
 }
-/** @deprecated Use `SDKTimeoutError`. Alias for one minor release. */
-declare const SDKTimeout: typeof SDKTimeoutError;
+/** Thrown by `Run.wait()` when the run reaches a terminal failure status. */
+declare class RunFailedError extends AnyformatError {
+    readonly runId: string;
+    readonly status: "error" | "cancelled";
+    constructor(runId: string, status: "error" | "cancelled");
+}
+/** The run ended in the terminal `error` status. */
+declare class ExtractionFailedError extends RunFailedError {
+    constructor(runId: string);
+}
+/** The run ended in the terminal `cancelled` status. */
+declare class ExtractionCancelledError extends RunFailedError {
+    constructor(runId: string);
+}
 /** Raised by the fluent `WorkflowBuilder` for builder-API misuse. */
 declare class WorkflowBuilderError extends AnyformatError {
 }
 
-export { APIError, Anyformat, AnyformatError, type AnyformatOptions, type ArithmeticCheck, BadRequest, BadRequestError, type Block, type BooleanField, type Branch, type ClassifyCategory, type ComparisonCheck, type DateCheck, type DateField, type DatetimeField, type EnumField, type EnumOption, type ExtractedField, type Extraction, type ExtractionSchema, type Field, type FloatField, Forbidden, ForbiddenError, type IntegerField, type MultiSelectField, type NestedField, NotFound, NotFoundError, type ObjectField, type OneOfCheck, ParseView, type RangeCheck, RateLimited, RateLimitedError, type RegexCheck, type RequiredCheck, Result, type ResultsResponse, Run, SDKTimeout, SDKTimeoutError, Schema, ServerError, type SplitterRule, type StringField, Unauthorized, UnauthorizedError, Upload, type ValidationRule, type WaitOptions, Workflow, WorkflowBuilder, WorkflowBuilderError, type WorkflowCreateRequest };
+export { APIError, type AllOfCheck, type AnyOfCheck, Anyformat, AnyformatError, type AnyformatOptions, type ArithmeticCheck, BadRequestError, type Block, type BooleanField, type Branch, type ClassifyCategory, type ComparisonCheck, type DatasetDocument, DatasetUpload, type DatasetUploadFileV3, type DatasetUploadOptions, type DatasetUploadResponseV3, type DateCheck, type DateField, type DatetimeField, type DocumentPacketDetailV3, type DocumentPacketFileV3, type DocumentPacketStatus, type DocumentPacketSummaryV3, type Edge, type EnumField, type EnumOption, type ExpressionCheck, type ExtractedField, type ExtractedRows, type Extraction, ExtractionCancelledError, ExtractionFailedError, type ExtractionSchema, type Field, type FloatField, ForbiddenError, InsufficientScopeError, type IntegerField, type IterOptions, type JsonValue, type ListOptions, type MultiSelectField, type NestedField, NotFoundError, type ObjectField, type OneOfCheck, type Page, type ParseResult, ParseView, PaymentRequiredError, type RangeCheck, RateLimitedError, type RegexCheck, type RequiredCheck, Result, type ResultsResponseV3, Run, type RunDetailV3, RunFailedError, type RunStatus, type RunSummaryV3, type RunTriggerOptions, SDKTimeoutError, type ScalarOrList, Schema, ServerError, type SplitterRule, type StringField, TermsAcceptanceRequiredError, UnauthorizedError, Upload, type UploadFromUrlsOptions, type UploadOptions, type ValidationItem, type ValidationRule, type WaitOptions, Workflow, WorkflowBuilder, WorkflowBuilderError, type WorkflowCreateRequest, type WorkflowDefinition, type WorkflowDetailV3, WorkflowNameConflictError, type WorkflowSummaryV3 };