@anyformat/sdk 0.2.2 → 1.0.0-rc.2

package/dist/index.d.cts

@@ -6,6 +6,13 @@ interface Auth {
      * @default 'header'
      */
     in?: 'header' | 'query' | 'cookie';
+    /**
+     * A unique identifier for the security scheme.
+     *
+     * Defined only when there are multiple security schemes whose `Auth`
+     * shape would otherwise be identical.
+     */
+    key?: string;
     /**
      * Header or query parameter name.
      *
@@ -312,6 +319,82 @@ 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
+ */
+type ArithmeticCheck = {
+    /**
+     * Equals
+     *
+     * 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
+     *
+     * 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>;
+    /**
+     * Operator
+     */
+    operator?: 'sum' | 'subtract' | 'product';
+    /**
+     * Tolerance
+     *
+     * Absolute slack allowed around `equals`.
+     */
+    tolerance?: number;
+    /**
+     * Type
+     */
+    type: 'arithmetic';
+};
 /**
  * Block
  *
@@ -360,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
      *
@@ -375,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
      *
@@ -403,17 +492,25 @@ type BooleanField = {
      *
      * Free-form description shown to the extraction model.
      */
-    description: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
+    description?: string;
     /**
      * 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';
 };
 /**
  * ClassificationResult
@@ -430,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
      *
@@ -459,7 +556,7 @@ type ClassifyCategory = {
     /**
      * Name
      *
-     * Display name shown to the LLM.
+     * Display name shown to the LLM; classification and routing key off it, so it must be unique across categories.
      */
     name: string;
 };
@@ -484,282 +581,639 @@ type ClassifyNode = {
     /**
      * User Prompt
      *
-     * Optional prompt prefix for the classifier.
+     * Optional extra instructions inserted between the classifier's system prompt and the document text.
      */
     user_prompt?: string | null;
 };
 /**
- * DateField
+ * ComparisonCheck
  */
-type DateField = {
+type ComparisonCheck = {
     /**
-     * Data Type
+     * Left
+     *
+     * 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.
      */
-    data_type: 'date';
+    left: string;
     /**
-     * Description
-     *
-     * Free-form description shown to the extraction model.
+     * Op
      */
-    description: string;
+    op: '==' | '!=' | '>' | '>=' | '<' | '<=';
     /**
-     * Lookup
+     * Right
      */
-    lookup?: boolean;
+    right: ({
+        source: 'field';
+    } & FieldOperand) | ({
+        source: 'literal';
+    } & LiteralOperand);
     /**
-     * Name
-     *
-     * Field name. Used as the key in the extraction response.
+     * Type
      */
-    name: string;
+    type: 'comparison';
 };
 /**
- * DatetimeField
+ * ConfidenceCheck
  */
-type DatetimeField = {
+type ConfidenceCheck = {
     /**
-     * Data Type
+     * 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.
      */
-    data_type: 'datetime';
+    field: string;
     /**
-     * Description
+     * Op
+     */
+    op: '<' | '<=' | '>' | '>=' | '==' | '!=';
+    /**
+     * Threshold
      *
-     * Free-form description shown to the extraction model.
+     * Confidence percentile 0..100.
      */
-    description: string;
+    threshold: number;
     /**
-     * Lookup
+     * Type
+     */
+    type: 'confidence';
+};
+/**
+ * DatasetUploadFileV3
+ *
+ * Per-file entry in a dataset-upload response.
+ */
+type DatasetUploadFileV3 = {
+    /**
+     * Id
+     *
+     * Unique identifier of the file (hyphenated UUID).
      */
-    lookup?: boolean;
+    id: string;
     /**
      * Name
      *
-     * Field name. Used as the key in the extraction response.
+     * 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;
 };
 /**
- * Edge
+ * DatasetUploadResponseV3
  *
- * 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.
+ * 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 Edge = {
+type DatasetUploadResponseV3 = {
     /**
-     * Branch
+     * Document Packet Id
      *
-     * Source-port label for branch routing. Required when leaving a classify or splitter node by category/rule.
+     * Unique identifier of the created dataset document packet (hyphenated UUID).
      */
-    branch?: string | null;
+    document_packet_id: string;
     /**
-     * Source
+     * Files
+     *
+     * Files in the packet, in the order they were provided.
      */
-    source: string;
+    files: Array<DatasetUploadFileV3>;
     /**
-     * Target
+     * Ground Truth Saved
+     *
+     * Whether ground truth was supplied and saved for this document packet.
      */
-    target: string;
+    ground_truth_saved: boolean;
 };
 /**
- * EnumField
+ * DateCheck
  */
-type EnumField = {
+type DateCheck = {
     /**
-     * Data Type
+     * Earliest
      */
-    data_type: 'enum';
+    earliest?: string | null;
     /**
-     * Description
+     * Field
      *
-     * Free-form description shown to the extraction model.
+     * 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.
      */
-    description: string;
+    field: string;
     /**
-     * Enum Options
+     * Latest
      */
-    enum_options: Array<EnumOption>;
+    latest?: string | null;
+    /**
+     * Type
+     */
+    type: 'date';
+};
+/**
+ * DateField
+ */
+type DateField = {
+    /**
+     * Data Type
+     */
+    data_type: 'date';
     /**
-     * Lookup
+     * Description
+     *
+     * Free-form description shown to the extraction model.
      */
-    lookup?: boolean;
+    description?: string;
     /**
      * 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
+ * DatetimeField
  */
-type EnumOption = {
+type DatetimeField = {
+    /**
+     * Data Type
+     */
+    data_type: 'datetime';
     /**
      * Description
      *
-     * Free-form description shown to the model.
+     * Free-form description shown to the extraction model.
      */
-    description: string;
+    description?: string;
     /**
      * 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';
 };
 /**
- * Evidence
+ * Detection
  *
- * A snippet of source text supporting an extracted value, with the page it came from.
+ * 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 Evidence = {
+type Detection = {
     /**
-     * Page Number
+     * Bbox
      *
-     * 1-indexed page number where the snippet was found.
+     * Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.
      */
-    page_number: number;
+    bbox: {
+        [key: string]: number;
+    };
     /**
      * Text
      *
-     * The exact source-text snippet that supports the extracted value.
+     * The words the page prints inside this box.
      */
     text: string;
+    /**
+     * Type
+     *
+     * What the layout detector called this box.
+     */
+    type: string;
 };
 /**
- * ExtractNode
+ * DocumentPacketDetailV3
+ *
+ * A packet with its per-file breakdown and latest run reference.
  */
-type ExtractNode = {
+type DocumentPacketDetailV3 = {
     /**
-     * Context Tracker
+     * Created At
+     *
+     * Timestamp when the packet was created (ISO 8601).
      */
-    context_tracker?: string;
+    created_at?: string | null;
     /**
-     * Schema for the fields this node extracts. Required. The backend executor populates this from the ORM field tree before constructing the typed node; nothing else should be able to build an ExtractNode without it.
+     * Files
+     *
+     * Files in this packet.
      */
-    extraction_schema: ExtractionSchema;
+    files: Array<DocumentPacketFileV3>;
     /**
      * Id
      *
-     * Stable identifier for this node within the graph.
+     * Unique identifier of the document packet (hyphenated UUID).
      */
     id: string;
     /**
-     * Lookup File Uploads
+     * Latest Run Id
      *
-     * Inline lookup-file content for the typed create call. The backend uploads each entry to S3 and stores the resulting URI in ``lookup_files``; this field is never persisted in GraphNode.config.
+     * Id of the packet's most recent run (hyphenated UUID); `null` until the packet has been run.
      */
-    lookup_file_uploads?: Array<LookupFileUpload>;
+    latest_run_id?: string | null;
     /**
-     * Lookup Files
+     * Metadata
      *
-     * Smart-lookup reference document URIs persisted on the extract node.
+     * 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.
      */
-    lookup_files?: Array<string>;
-    /**
-     * Lookup Schema
-     *
-     * Typed schema of fields the smart-lookup pass should produce. The *backend* derives this from the field tree (FieldWorkflowVersion rows whose source is SMART_LOOKUP) and attaches it to the node before the message hits the wire — the worker then reads it directly off the node, with no DB round-trip. Default empty: a node without smart-lookup fields carries an empty list.
-     */
-    lookup_schema?: Array<({
-        data_type: 'string';
-    } & StringField) | ({
-        data_type: 'integer';
-    } & IntegerField) | ({
-        data_type: 'float';
-    } & FloatField) | ({
-        data_type: 'boolean';
-    } & BooleanField) | ({
-        data_type: 'date';
-    } & DateField) | ({
-        data_type: 'datetime';
-    } & DatetimeField) | ({
-        data_type: 'enum';
-    } & EnumField) | ({
-        data_type: 'multi_select';
-    } & MultiSelectField) | ({
-        data_type: 'object';
-    } & ObjectField)>;
+    metadata?: {
+        [key: string]: unknown;
+    } | null;
     /**
-     * Lookup Suggestion
+     * Name
      *
-     * Free-form hint shown to the smart-lookup matcher.
+     * Human-readable name of the packet.
      */
-    lookup_suggestion?: string | null;
+    name?: string | null;
     /**
-     * Mode
+     * Processing status. Non-terminal: `not_started`, `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
      */
-    mode?: 'standard' | 'agentic' | 'max';
+    status: DocumentPacketStatus;
     /**
-     * Page Sum Verification Enabled
+     * Updated At
+     *
+     * Timestamp when the packet was last updated (ISO 8601).
      */
-    page_sum_verification_enabled?: boolean;
+    updated_at?: string | null;
     /**
-     * Row Extractor Enabled
+     * Workflow Id
+     *
+     * The workflow this packet belongs to (hyphenated UUID).
      */
-    row_extractor_enabled?: boolean;
+    workflow_id: string;
+};
+/**
+ * DocumentPacketFileV3
+ *
+ * Slim per-file projection inside a packet.
+ */
+type DocumentPacketFileV3 = {
     /**
-     * Type
+     * Id
+     *
+     * Unique identifier of the file (hyphenated UUID).
      */
-    type: 'extract';
+    id: string;
     /**
-     * Use Images
+     * Name
+     *
+     * 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`).
      */
-    use_images?: boolean;
+    name: string;
 };
 /**
- * ExtractedField
+ * DocumentPacketStatus
  *
- * One extracted field's value, confidence, and supporting evidence.
+ * 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 ExtractedField = {
+type DocumentPacketSummaryV3 = {
     /**
-     * Confidence
+     * Created At
      *
-     * Model confidence in the extracted value, on a 0-100 scale. `null` when the backend did not produce a confidence (e.g. manual entry).
+     * Timestamp when the packet was created (ISO 8601).
      */
-    confidence?: number | null;
+    created_at?: string | null;
     /**
-     * Evidence
+     * Id
      *
-     * Source-text snippets the model used to derive this value.
+     * Unique identifier of the document packet (hyphenated UUID).
      */
-    evidence?: Array<Evidence>;
+    id: string;
     /**
-     * Value
+     * Name
      *
-     * The extracted value. Type depends on the field's `data_type` (string, number, date, etc.). `null` when extraction could not produce a value.
+     * Human-readable name of the packet.
      */
-    value: unknown | null;
+    name?: string | null;
     /**
-     * Value Override
+     * Processing status. Non-terminal: `not_started`, `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
+     */
+    status: DocumentPacketStatus;
+    /**
+     * Updated At
      *
-     * A human-supplied override of the extracted `value`, if one was set during verification. `null` when no override exists.
+     * Timestamp when the packet was last updated (ISO 8601).
      */
-    value_override?: unknown | null;
+    updated_at?: string | null;
     /**
-     * Verification Status
+     * Workflow Id
      *
-     * Verification state for this datapoint (e.g. `not_verified`, `verified`). `null` when not yet reviewed.
+     * The workflow this packet belongs to (hyphenated UUID).
      */
-    verification_status?: string | null;
+    workflow_id: string;
 };
 /**
- * Extraction
+ * Edge
  *
- * 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.
+ * 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 Extraction = {
+type Edge = {
     /**
-     * Fields
+     * Branch
      *
-     * Extracted fields keyed by field name. Same shape as the legacy top-level `extraction`.
+     * Source-port label for branch routing. Required when leaving a classify or splitter node by category/rule.
      */
-    fields: {
-        [key: string]: ExtractedField | Array<{
-            [key: string]: ExtractedField;
-        }>;
-    };
+    branch?: string | null;
+    /**
+     * 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
+     *
+     * 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.
+     */
+    download_url?: string | null;
+    /**
+     * Fields
+     *
+     * Every form field detected in the document, filled or not, in document order.
+     */
+    fields?: Array<EditFormField>;
+    /**
+     * File Id
+     *
+     * The UUID of the file this form was filled from.
+     */
+    file_id: string;
+    /**
+     * File Name
+     *
+     * The file's display name.
+     */
+    file_name: string;
+    /**
+     * Unmatched Instructions
+     *
+     * Instruction fragments, quoted verbatim, that matched no field in this document.
+     */
+    unmatched_instructions?: Array<string>;
+};
+/**
+ * EditFormField
+ *
+ * One form field the edit node detected, with the value it wrote in.
+ */
+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
+     *
+     * 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;
+    /**
+     * Form Field Id
+     *
+     * Stable identifier for this form field within the document, in the form `p<page>_f<index>`.
+     */
+    form_field_id: string;
+    /**
+     * Kind
+     *
+     * `checkbox` for a tick target, `text` for anything else.
+     */
+    kind: string;
+    /**
+     * Label
+     *
+     * The field's own printed caption, verbatim from the document.
+     */
+    label: string;
+    /**
+     * Page
+     *
+     * 1-indexed page number the field sits on.
+     */
+    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 = {
+    /**
+     * Fields
+     *
+     * Extracted fields keyed by field name. Same shape as the legacy top-level `extraction`.
+     */
+    fields: {
+        [key: string]: ExtractedField$1 | Array<{
+            [key: string]: ExtractedField$1;
+        }>;
+    };
     /**
      * Partition
      *
@@ -772,20 +1226,21 @@ 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
  *
- * Schema describing what an extract node produces. Modeled as a typed
- * object (not a bare ``list[AnyField]``) so metadata can be added later
- * (versioning, derived flags, output-shape hints) without another
- * wire-format break.
+ * Schema describing what an extract node produces.
  *
- * Every extraction schema must declare at least one field. The backend
- * executor populates this list from ``FieldWorkflowVersion`` rows
- * *before* constructing the typed ExtractNode; extract nodes without
- * any assigned fields are skipped at the executor layer rather than
- * sent to the worker with an empty schema.
+ * Modeled as a typed object (not a bare ``list[AnyField]``) so metadata
+ * can be added later (versioning, derived flags, output-shape hints)
+ * without another wire-format break. At least one field is required.
  */
 type ExtractionSchema = {
     /**
@@ -793,25 +1248,7 @@ type ExtractionSchema = {
      *
      * Field definitions making up this extract's output.
      */
-    fields: Array<({
-        data_type: 'string';
-    } & StringField) | ({
-        data_type: 'integer';
-    } & IntegerField) | ({
-        data_type: 'float';
-    } & FloatField) | ({
-        data_type: 'boolean';
-    } & BooleanField) | ({
-        data_type: 'date';
-    } & DateField) | ({
-        data_type: 'datetime';
-    } & DatetimeField) | ({
-        data_type: 'enum';
-    } & EnumField) | ({
-        data_type: 'multi_select';
-    } & MultiSelectField) | ({
-        data_type: 'object';
-    } & ObjectField)>;
+    fields: Array<StringField | IntegerField | FloatField | BooleanField | DateField | DatetimeField | EnumField | MultiSelectField | ObjectField>;
 };
 /**
  * FilePages
@@ -851,17 +1288,25 @@ type FloatField = {
      *
      * Free-form description shown to the extraction model.
      */
-    description: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
+    description?: string;
     /**
      * 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';
 };
 /**
  * Hyperlink
@@ -895,17 +1340,48 @@ type IntegerField = {
      *
      * Free-form description shown to the extraction model.
      */
-    description: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
+    description?: string;
     /**
      * 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';
+};
+/**
+ * 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
@@ -913,9 +1389,9 @@ type IntegerField = {
  * Inline lookup-file content carried on the typed create call.
  *
  * The backend reads ``filename`` + ``content`` (base64-encoded bytes),
- * uploads the file to S3 during workflow create, and stores the resulting
- * URI in ``ExtractNode.lookup_files``. This field is stripped from the
- * persisted ``GraphNode.config`` — it is create-input only.
+ * uploads the file, and stores the resulting URI in
+ * ``ExtractNode.lookup_files``. Create-input only — not persisted on
+ * the node after upload.
  */
 type LookupFileUpload = {
     /**
@@ -942,24 +1418,37 @@ type MultiSelectField = {
      *
      * Free-form description shown to the extraction model.
      */
-    description: string;
+    description?: string;
     /**
      * Enum Options
      */
     enum_options: Array<EnumOption>;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
     /**
      * 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';
 };
 /**
  * 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 = {
     /**
@@ -971,11 +1460,7 @@ type ObjectField = {
      *
      * Free-form description shown to the extraction model.
      */
-    description: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
+    description?: string;
     /**
      * Name
      *
@@ -985,36 +1470,243 @@ 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<({
-        data_type: 'string';
-    } & StringField) | ({
-        data_type: 'integer';
-    } & IntegerField) | ({
-        data_type: 'float';
-    } & FloatField) | ({
-        data_type: 'boolean';
-    } & BooleanField) | ({
-        data_type: 'date';
-    } & DateField) | ({
-        data_type: 'datetime';
-    } & DatetimeField) | ({
-        data_type: 'enum';
-    } & EnumField) | ({
-        data_type: 'multi_select';
-    } & MultiSelectField)>;
-};
-/**
- * ParseNode
- */
-type ParseNode = {
+    nested_fields: Array<StringField | IntegerField | FloatField | BooleanField | DateField | DatetimeField | EnumField | MultiSelectField>;
     /**
-     * Cache
+     * 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';
+};
+/**
+ * OneOfCheck
+ */
+type OneOfCheck = {
+    /**
+     * Allowed
+     */
+    allowed: Array<string>;
+    /**
+     * Case Sensitive
+     */
+    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;
+    /**
+     * Type
+     */
+    type: 'one_of';
+};
+/**
+ * ParseResult
+ *
+ * Parsed markdown for a file.
+ */
+type ParseResult = {
+    /**
+     * 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.
+     */
+    blocks?: Array<Block>;
+    /**
+     * Layout Confidence
+     *
+     * Document-level YOLO layout confidence on a 0-1 scale, char-weighted mean across all blocks. `null` if no annotated sections.
+     */
+    layout_confidence?: number | null;
+    /**
+     * Markdown
+     *
+     * 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.
+     */
+    markdown: string | null;
+    /**
+     * 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.
+     */
+    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
+     *
+     * 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';
+    /**
+     * Type
+     */
+    type: 'extract';
+    /**
+     * Use Images
+     *
+     * 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.
+     */
+    use_images?: boolean;
+};
+/**
+ * PublicIfElseNode
+ */
+type PublicIfElseNode = {
+    /**
+     * 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
+     *
+     * Stable identifier for this node within the graph.
+     */
+    id: string;
+    /**
+     * Type
+     */
+    type: 'if_else';
+};
+/**
+ * PublicParseNode
+ */
+type PublicParseNode = {
+    /**
+     * 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;
     /**
@@ -1025,111 +1717,295 @@ type ParseNode = {
     id: string;
     /**
      * 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-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).
      */
-    mode?: 'standard' | 'agentic';
+    mode?: 'standard' | 'agentic' | 'lite' | 'flash';
+    /**
+     * Ocr Effort
+     *
+     * 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`.)
+     */
+    ocr_effort?: 'medium' | 'high';
     /**
      * Prompt Hint
      *
-     * Free-form hint shown to the parse model to bias output.
+     * Free-form hint that biases the parse output. Standard and agentic modes only; ignored in lite.
      */
     prompt_hint?: string | null;
+    /**
+     * Scanned Pages
+     *
+     * 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.
+     */
+    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 = {
     /**
-     * Blocks
+     * Channel Id
+     */
+    channel_id: string;
+    /**
+     * Channel Name
+     */
+    channel_name: string;
+    /**
+     * Id
      *
-     * 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.
+     * Stable identifier for this node within the graph.
      */
-    blocks?: Array<Block>;
+    id: string;
     /**
-     * Layout Confidence
+     * Message Template
+     */
+    message_template: string;
+    /**
+     * Severity
+     */
+    severity?: 'info' | 'warning' | 'critical';
+    /**
+     * Type
+     */
+    type: 'slack_alert';
+};
+/**
+ * PublicValidateNode
+ */
+type PublicValidateNode = {
+    /**
+     * Id
      *
-     * Document-level YOLO layout confidence on a 0-100 scale, char-weighted mean across all blocks. `null` if no annotated sections.
+     * Stable identifier for this node within the graph.
      */
-    layout_confidence?: number | null;
+    id: string;
     /**
-     * Markdown
+     * Rules
+     */
+    rules: Array<ValidationRule>;
+    /**
+     * Type
+     */
+    type: 'validate';
+};
+/**
+ * RangeCheck
+ */
+type RangeCheck = {
+    /**
+     * Field
      *
-     * 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.
+     * 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;
+    /**
+     * Max
+     */
+    max?: number | null;
+    /**
+     * Min
+     */
+    min?: number | null;
+    /**
+     * Type
+     */
+    type: 'range';
+};
+/**
+ * RegexCheck
+ */
+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;
+    /**
+     * Pattern
+     *
+     * Evaluated with google-re2 (linear time); never stdlib re.
+     */
+    pattern: string;
+    /**
+     * Type
+     */
+    type: 'regex';
+};
+/**
+ * RequiredCheck
+ */
+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;
+    /**
+     * Type
+     */
+    type: 'required';
+};
+/**
+ * ResultsResponseV3
+ *
+ * v3-scoped results envelope — same shape as ``ResultsResponse`` minus the
+ * legacy ``collection_id`` alias. v3 emits only ``document_packet_id``.
+ */
+type ResultsResponseV3 = {
+    /**
+     * Classifications
+     *
+     * Per-classifier-node verdicts. Empty when the workflow has no classifier.
+     */
+    classifications?: Array<ClassificationResult>;
+    /**
+     * 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
+     *
+     * Filled-form output, one entry per file an edit node processed. Empty when the workflow has no edit node.
+     */
+    edits?: Array<Edit>;
+    /**
+     * Extraction
+     *
+     * **Deprecated** — use `extractions` instead. Extracted fields keyed by field name, populated only for linear workflows (single extract node, no splitter). `null` for split workflows; read `extractions[]` instead.
+     *
+     * @deprecated
+     */
+    extraction?: {
+        [key: string]: ExtractedField$1 | Array<{
+            [key: string]: ExtractedField$1;
+        }>;
+    } | null;
+    /**
+     * Extractions
+     *
+     * Flat list of extraction datapoints. Linear workflows produce one entry with `split_name=null` and `partition=null`. Split workflows produce one entry per (split, partition). Empty when no extraction has run yet.
+     */
+    extractions?: Array<Extraction>;
+    /**
+     * Parse-node output (rendered markdown). `null` when the workflow has no parse node. Always present in the response.
+     */
+    parse?: ParseResult | null;
+    /**
+     * Splits
+     *
+     * Splitter output: category-level geometry with optional partitions. Empty when the workflow has no splitter.
+     */
+    splits?: Array<SplitResult>;
+    /**
+     * Verification Url
+     *
+     * Link to the AnyFormat dashboard for human review of this collection's results. `null` if the dashboard URL cannot be constructed (e.g. no files in the collection, or the deployment has no frontend URL configured).
+     */
+    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`.
      */
-    markdown: string | null;
+    status: RunStatus;
     /**
-     * Parse Confidence
+     * Updated At
      *
-     * 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.
+     * Timestamp of the run's last status change (ISO 8601).
      */
-    parse_confidence?: number | null;
+    updated_at?: string | null;
     /**
-     * Text
+     * Workflow Id
      *
-     * 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.
+     * The workflow this run executed (hyphenated UUID).
      */
-    text?: string | null;
+    workflow_id: string;
 };
 /**
- * ResultsResponse
+ * RunStatus
  *
- * Canonical response shape for the file-collection results endpoint.
+ * Execution lifecycle of a run. Non-terminal: ``queued``,
+ * ``in_progress``. Terminal: ``processed`` (success), ``error``,
+ * ``cancelled``.
+ */
+type RunStatus = 'queued' | 'in_progress' | 'processed' | 'error' | 'cancelled';
+/**
+ * RunSummaryV3
  *
- * Returned with HTTP 200 once processing completes. Returns 412 while processing is
- * in progress; poll until 200, or use webhooks.
+ * Slim run projection returned by list pages.
  */
-type ResultsResponse = {
-    /**
-     * Classifications
-     *
-     * Per-classifier-node verdicts. Empty when the workflow has no classifier.
-     */
-    classifications?: Array<ClassificationResult>;
+type RunSummaryV3 = {
     /**
-     * Collection Id
+     * Created At
      *
-     * The file collection's UUID. Same value as the `id` returned by `POST /v2/workflows/{wid}/run/`.
+     * Timestamp when the run was triggered (ISO 8601).
      */
-    collection_id: string;
+    created_at?: string | null;
     /**
-     * Extraction
+     * Document Packet Id
      *
-     * **Deprecated** — use `extractions` instead. Extracted fields keyed by field name, populated only for linear workflows (single extract node, no splitter). `null` for split workflows; read `extractions[]` instead.
-     *
-     * @deprecated
+     * The document packet the run executes on (hyphenated UUID).
      */
-    extraction?: {
-        [key: string]: ExtractedField | Array<{
-            [key: string]: ExtractedField;
-        }>;
-    } | null;
+    document_packet_id: string;
     /**
-     * Extractions
+     * Id
      *
-     * Flat list of extraction datapoints. Linear workflows produce one entry with `split_name=null` and `partition=null`. Split workflows produce one entry per (split, partition). Empty when no extraction has run yet.
-     */
-    extractions?: Array<Extraction>;
-    /**
-     * Parse-node output (rendered markdown). `null` when the workflow has no parse node. Always present in the response.
+     * Unique identifier of the run (hyphenated UUID).
      */
-    parse?: ParseResult | null;
+    id: string;
     /**
-     * Splits
-     *
-     * Splitter output: category-level geometry with optional partitions. Empty when the workflow has no splitter.
+     * Execution status. Non-terminal: `queued`, `in_progress`. Terminal: `processed` (success), `error`, `cancelled`.
      */
-    splits?: Array<SplitResult>;
+    status: RunStatus;
     /**
-     * Verification Url
+     * Updated At
      *
-     * Link to the AnyFormat dashboard for human review of this collection's results. `null` if the dashboard URL cannot be constructed (e.g. no files in the collection, or the deployment has no frontend URL configured).
+     * Timestamp of the run's last status change (ISO 8601).
      */
-    verification_url?: string | null;
+    updated_at?: string | null;
 };
 /**
  * SplitPartition
@@ -1140,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
      */
@@ -1165,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
      *
@@ -1222,6 +2098,8 @@ type SplitterRule = {
     name: string;
     /**
      * Partition Key
+     *
+     * Field that further partitions this category into separate sub-documents (e.g. invoice_number): each distinct value becomes its own split, extracted independently. Empty = routing-only, the whole category flows on as one document.
      */
     partition_key?: string;
 };
@@ -1238,61 +2116,176 @@ type StringField = {
      *
      * Free-form description shown to the extraction model.
      */
-    description: string;
-    /**
-     * Lookup
-     */
-    lookup?: boolean;
+    description?: string;
     /**
      * 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';
 };
 /**
- * ValidateNode
+ * Validation
+ *
+ * A configured rule verdict or an automatic extraction review warning.
  */
-type ValidateNode = {
+type Validation = {
     /**
-     * Id
+     * Compared Values
      *
-     * Stable identifier for this node within the graph.
+     * The field values the rule looked at, keyed by field name. `null` when nothing was compared.
      */
-    id: string;
+    compared_values?: {
+        [key: string]: unknown;
+    } | null;
     /**
-     * Rules
+     * Description
+     *
+     * The rule's natural-language description; empty for a deterministic rule.
      */
-    rules: Array<ValidationRule>;
+    description?: string;
+    /**
+     * Detail
+     *
+     * Human-readable explanation of the verdict.
+     */
+    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
  */
 type ValidationRule = {
+    /**
+     * Check
+     *
+     * Structured deterministic check. Required when kind == 'deterministic'.
+     */
+    check?: ({
+        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) | null;
     /**
      * Description
      *
-     * Natural-language description shown to the validation model.
+     * Natural-language description sent to the LLM. Required when kind == 'ai'.
      */
-    description: string;
+    description?: string | null;
     /**
      * Id
      *
-     * Stable rule id; round-trips through ValidationResult.rule_id.
+     * Stable rule id; round-trips through validation results.
      */
     id: string;
+    /**
+     * Kind
+     *
+     * 'deterministic' = a structured check run in code — instant, free, reproducible; 'ai' = a model judges the rule description against the extraction. Prefer deterministic whenever the condition is exact and testable.
+     */
+    kind?: 'ai' | 'deterministic';
     /**
      * Name
      *
-     * Optional human-readable rule name shown on the rule card in the Studio. Stored verbatim on the GraphNode config and surfaced back through the config endpoint so renames round-trip.
+     * Optional human-readable rule name. Round-trips through the config endpoint so renames are preserved.
      */
     name?: string | null;
     /**
      * Severity
+     *
+     * How a failed rule is labelled in results. Display-level only — it never blocks the run.
      */
     severity?: 'error' | 'warning';
     /**
@@ -1305,12 +2298,18 @@ type ValidationRule = {
 /**
  * WorkflowCreateRequest
  *
- * Public-surface workflow create body — typed graph of parse / classify / splitter / extract nodes.
+ * Public-surface workflow create body — typed graph of parse / classify / splitter / extract / validate nodes.
  *
- * 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``.
+ * A ``validate`` node carries ``rules``; each rule is either AI-evaluated
+ * (``kind="ai"`` + a natural-language ``description``) or deterministic
+ * (``kind="deterministic"`` + a structured ``check``, evaluated in pure
+ * Python with no model call).
+ *
+ * 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 = {
     /**
@@ -1328,17 +2327,124 @@ type WorkflowCreateRequest = {
     /**
      * Nodes
      */
-    nodes: Array<({
-        type: 'parse';
-    } & ParseNode) | ({
-        type: 'classify';
-    } & ClassifyNode) | ({
-        type: 'splitter';
-    } & SplitterNode) | ({
-        type: 'extract';
-    } & ExtractNode) | ({
-        type: 'validate';
-    } & 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
+ */
+type FieldOperand = {
+    /**
+     * 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;
+    /**
+     * Source
+     */
+    source: 'field';
+};
+/**
+ * _LiteralOperand
+ */
+type LiteralOperand = {
+    /**
+     * Source
+     */
+    source: 'literal';
+    /**
+     * Value
+     */
+    value: number | string | boolean;
 };
 
 /**
@@ -1368,12 +2474,27 @@ declare class ParseView {
     get layoutConfidence(): number | null;
 }
 
+/**
+ * One extracted field — generic over the value type so callers get real
+ * types at the access site (`result.field<number>("total").value` is
+ * `number | null`, not `unknown`). Wire shape identical to the codegen type.
+ */
+type ExtractedField<T = unknown> = Omit<ExtractedField$1, "value" | "value_override"> & {
+    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
@@ -1381,37 +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 a scalar's `.value`:
+     * `result.field<number>("total").value` is `number | null`.
      */
-    field(name: string): ExtractedField | 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";
+}
+/**
+ * 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 documentPacketId: string;
+    readonly files: DocumentPacketFileV3[];
+    /** @internal */
+    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 | text)` submits a document against this workflow's id and returns
- * a `Run` you can `.wait()` on for results.
+ * `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;
@@ -1419,10 +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, opts?: {
-        text?: string;
-    }): 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[]>;
+    /**
+     * Import 1..10 HTTPS URLs server-side into one document packet, atomically.
+     * Returns an `Upload`; call `.run()` on it to start extraction.
+     */
+    uploadFromUrls(urls: string[], opts?: UploadFromUrlsOptions): Promise<Upload>;
 }
 
 /** Any extraction field — the discriminated union on `data_type`. */
@@ -1432,37 +2687,76 @@ 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 ParseMode = "standard" | "agentic";
+type ExtractMode = "standard" | "agentic" | "lite";
+type AgenticEffort = "low" | "mid" | "accurate";
+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;
-interface ParseOptions {
-    mode?: ParseMode;
-    promptHint?: string;
+/** Knobs shared by every parse mode. */
+interface ParseOptionsBase {
     figureEnhancement?: boolean;
     cache?: boolean;
     id?: string;
 }
+/**
+ * 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. 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";
+}) | (ParseOptionsBase & {
+    mode: "flash";
+    scannedPages?: ScannedPages;
+    promptHint?: string;
+});
 /**
  * Fluent assembler for a typed workflow graph — a faithful TS port of the
  * Python `WorkflowBuilder`. `parse`/`classify`/`split` are singletons;
@@ -1495,8 +2789,11 @@ declare class WorkflowBuilder {
     extract(fields: Field[], opts?: {
         branch?: Branch;
         id?: string;
+        mode?: ExtractMode;
         lookupFiles?: string[];
         lookupSuggestion?: string;
+        lookupReasoningEffort?: ReasoningEffort;
+        useImages?: boolean;
     }): this;
     validate(rules: ValidationRule[], opts?: {
         branch?: Branch;
@@ -1506,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>;
 }
 
@@ -1517,43 +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[]>;
+    listWorkflows(opts?: ListOptions): Promise<Page<Workflow>>;
+    /** Retrieve a workflow with its complete typed graph inline (round-trippable into `updateWorkflow`). */
+    getWorkflow(workflowId: string): Promise<WorkflowDetailV3>;
+    /**
+     * 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 run. Returns the parsed markdown once the run is `processed`,
+     * or `null` while it is still queued or in progress.
+     */
+    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 BadRequest extends APIError {
+declare class BadRequestError extends APIError {
+}
+declare class UnauthorizedError extends APIError {
 }
-declare class Unauthorized extends APIError {
+declare class PaymentRequiredError extends APIError {
 }
-declare class Forbidden extends APIError {
+declare class ForbiddenError extends APIError {
 }
-declare class NotFound extends APIError {
+declare class NotFoundError extends APIError {
 }
-declare class RateLimited 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 {
 }
-declare class SDKTimeout extends AnyformatError {
+/** 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 {
+}
+/** 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, BadRequest, type Block, type BooleanField, type Branch, type ClassifyCategory, type DateField, type DatetimeField, type EnumField, type EnumOption, type ExtractedField, type Extraction, type ExtractionSchema, type Field, type FloatField, Forbidden, type IntegerField, type MultiSelectField, type NestedField, NotFound, type ObjectField, ParseView, RateLimited, Result, type ResultsResponse, Run, SDKTimeout, Schema, ServerError, type SplitterRule, type StringField, Unauthorized, 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 };