@anyformat/sdk 1.10.0 → 1.12.0

package/dist/index.d.cts

@@ -319,6 +319,72 @@ 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'>);
 
+/**
+ * AccuracyCoverageV3
+ *
+ * Which fields have ground truth to grade against.
+ */
+type AccuracyCoverageV3 = {
+    /**
+     * Graded Persistent Ids
+     *
+     * Fields graded on at least one document.
+     */
+    graded_persistent_ids: Array<string>;
+    /**
+     * Ungraded Persistent Ids
+     *
+     * Fields graded on no document.
+     */
+    ungraded_persistent_ids: Array<string>;
+};
+/**
+ * AccuracyV3
+ *
+ * An accuracy breakdown: totals, per field, per document and per dataset tag.
+ *
+ * Accuracy is `matched / (matched + mismatched)`; `ungraded` values are left
+ * out of it.
+ */
+type AccuracyV3 = {
+    /**
+     * By Dataset Tag
+     *
+     * Counts per dataset tag, ordered by tag name.
+     */
+    by_dataset_tag: Array<DatasetTagAccuracyV3>;
+    /**
+     * By Document Packet
+     *
+     * Counts per document.
+     */
+    by_document_packet: Array<DocumentPacketAccuracyV3>;
+    /**
+     * By Field
+     *
+     * Counts per field.
+     */
+    by_field: Array<FieldAccuracyV3>;
+    coverage: AccuracyCoverageV3;
+    /**
+     * Matched
+     *
+     * Values that matched ground truth.
+     */
+    matched: number;
+    /**
+     * Mismatched
+     *
+     * Values that did not match ground truth.
+     */
+    mismatched: number;
+    /**
+     * Ungraded
+     *
+     * Values with no ground truth to grade against.
+     */
+    ungraded: number;
+};
 /**
  * AllOfCheck
  *
@@ -681,6 +747,59 @@ type ConsolidationCandidate = {
      */
     value_unit?: string | null;
 };
+/**
+ * DatasetTagAccuracyV3
+ *
+ * Grading counts for the documents carrying one dataset tag.
+ *
+ * A document counts under every tag it carries, so the rows do not add up to
+ * the totals.
+ */
+type DatasetTagAccuracyV3 = {
+    /**
+     * Dataset Tag Id
+     *
+     * The dataset tag's id (hyphenated UUID).
+     */
+    dataset_tag_id: string;
+    /**
+     * Matched
+     *
+     * Values that matched ground truth.
+     */
+    matched: number;
+    /**
+     * Mismatched
+     *
+     * Values that did not match ground truth.
+     */
+    mismatched: number;
+};
+/**
+ * DatasetTagV3
+ *
+ * One of a workflow's dataset tags.
+ */
+type DatasetTagV3 = {
+    /**
+     * Created At
+     *
+     * Timestamp when the tag was created (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Id
+     *
+     * The dataset tag's id (hyphenated UUID); pass it in `dataset_tag_ids` to launch an eval on the documents carrying it.
+     */
+    id: string;
+    /**
+     * Name
+     *
+     * The tag's name, unique within the workflow.
+     */
+    name: string;
+};
 /**
  * DatasetUploadFileV3
  *
@@ -853,6 +972,67 @@ type Detection = {
      */
     type: string;
 };
+/**
+ * DocumentPacketAccuracyV3
+ *
+ * Grading counts for one dataset document.
+ */
+type DocumentPacketAccuracyV3 = {
+    /**
+     * Document Packet Id
+     *
+     * The dataset copy's document packet id (hyphenated UUID), not the id of the production packet it was added from.
+     */
+    document_packet_id: string;
+    /**
+     * Failed Persistent Ids
+     *
+     * `persistent_id` of every field with at least one mismatched value.
+     */
+    failed_persistent_ids: Array<string>;
+    /**
+     * File Count
+     *
+     * Number of files in the document packet.
+     */
+    file_count: number;
+    /**
+     * First File Name
+     *
+     * Name of the document's first file.
+     */
+    first_file_name: string;
+    /**
+     * Has Extraction
+     *
+     * `false` when the eval produced no extraction for this document.
+     */
+    has_extraction: boolean;
+    /**
+     * Matched
+     *
+     * Values that matched ground truth.
+     */
+    matched: number;
+    /**
+     * Mismatched
+     *
+     * Values that did not match ground truth.
+     */
+    mismatched: number;
+    /**
+     * Name
+     *
+     * The document packet's own name. Absent when it has none.
+     */
+    name?: string | null;
+    /**
+     * Ungraded
+     *
+     * Values with no ground truth to grade against.
+     */
+    ungraded: number;
+};
 /**
  * DocumentPacketDetailV3
  *
@@ -1152,6 +1332,167 @@ type EnumOption = {
      */
     name: string;
 };
+/**
+ * EvalDetailV3
+ *
+ * One eval's frozen headline — the poll target for a launched run.
+ *
+ * ``id`` here is the same identifier the launch returned as ``eval_id``. The
+ * headline fields (``accuracy``, ``matched``, ``mismatched``, ``ungraded``)
+ * are ``null`` while ``status`` is ``in_progress``; ``accuracy`` stays ``null``
+ * on a ``processed`` eval whose graded denominator is 0.
+ */
+type EvalDetailV3 = {
+    /**
+     * Accuracy
+     *
+     * Headline accuracy in [0, 1]; `null` while `in_progress` and on a `processed` eval with a 0 graded denominator.
+     */
+    accuracy?: number | null;
+    /**
+     * Created At
+     *
+     * Timestamp when the eval was created (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Dataset Tag Ids
+     *
+     * Dataset tags the eval was launched on, as sent at launch. Absent on an eval of the whole dataset.
+     */
+    dataset_tag_ids?: Array<string>;
+    /**
+     * Failed Count
+     *
+     * Number of dataset documents that failed to enqueue for this run.
+     */
+    failed_count: number;
+    /**
+     * File Count
+     *
+     * Number of dataset documents in the eval's realized cohort.
+     */
+    file_count: number;
+    /**
+     * Id
+     *
+     * Unique identifier of the eval (hyphenated UUID); equals the launch's `eval_id`.
+     */
+    id: string;
+    /**
+     * Matched
+     *
+     * Values that matched ground truth; `null` while `in_progress`.
+     */
+    matched?: number | null;
+    /**
+     * Mismatched
+     *
+     * Values that did not match ground truth; `null` while `in_progress`.
+     */
+    mismatched?: number | null;
+    /**
+     * Run Number
+     *
+     * Per-workflow run counter (#1, #2, …) for this eval.
+     */
+    run_number: number;
+    /**
+     * Grading status. Non-terminal: `in_progress`. Terminal: `processed`, `error`.
+     */
+    status: EvalStatus;
+    /**
+     * Ungraded
+     *
+     * Values with no ground truth to grade against; `null` while `in_progress`.
+     */
+    ungraded?: number | null;
+    /**
+     * Untagged
+     *
+     * `true` when the eval also ran the untagged documents. Absent otherwise.
+     */
+    untagged?: boolean;
+    /**
+     * Version Id
+     *
+     * Workflow version the eval scored.
+     */
+    version_id: string;
+};
+/**
+ * EvalDocumentPacketFieldsV3
+ *
+ * Extracted against expected values for one document of an eval.
+ */
+type EvalDocumentPacketFieldsV3 = {
+    /**
+     * Document Packet Id
+     *
+     * The dataset copy's document packet id (hyphenated UUID), not the id of the production packet it was added from.
+     */
+    document_packet_id: string;
+    /**
+     * Fields
+     *
+     * One entry per graded field.
+     */
+    fields: Array<FieldValuesV3>;
+    /**
+     * First File Name
+     *
+     * Name of the document's first file.
+     */
+    first_file_name: string;
+    /**
+     * Has Extraction
+     *
+     * `false` when the eval produced no extraction for this document.
+     */
+    has_extraction: boolean;
+};
+/**
+ * EvalLaunchedV3
+ *
+ * 202 response: the eval was created and its cohort enqueued.
+ *
+ * Exposes counts, never the internal extraction/file ids. Read the eval by
+ * ``eval_id`` for the per-document breakdown (including which documents
+ * failed to enqueue).
+ */
+type EvalLaunchedV3 = {
+    /**
+     * Enqueued Count
+     *
+     * Number of dataset documents whose extraction was enqueued for this run.
+     */
+    enqueued_count: number;
+    /**
+     * Eval Id
+     *
+     * Unique identifier of the new eval (hyphenated UUID); the poll handle.
+     */
+    eval_id: string;
+    /**
+     * Failed Count
+     *
+     * Number of dataset documents that failed to enqueue. Read the eval for the failed document ids.
+     */
+    failed_count: number;
+    /**
+     * Run Number
+     *
+     * Per-workflow run counter (#1, #2, …) for this eval.
+     */
+    run_number: number;
+};
+/**
+ * EvalStatus
+ *
+ * Grading lifecycle of an eval. Non-terminal: ``in_progress`` (the headline
+ * fields are null). Terminal: ``processed`` (graded) and ``error``.
+ */
+type EvalStatus = 'in_progress' | 'processed' | 'error';
 /**
  * Evidence
  *
@@ -1310,6 +1651,62 @@ type ExtractionSchema = {
      */
     fields: Array<StringField | IntegerField | FloatField | BooleanField | DateField | DatetimeField | EnumField | MultiSelectField | ObjectField>;
 };
+/**
+ * FieldAccuracyV3
+ *
+ * Grading counts for one field across the graded documents.
+ */
+type FieldAccuracyV3 = {
+    /**
+     * Matched
+     *
+     * Values of this field that matched ground truth.
+     */
+    matched: number;
+    /**
+     * Mismatched
+     *
+     * Values of this field that did not match ground truth.
+     */
+    mismatched: number;
+    /**
+     * Persistent Id
+     *
+     * The field's `persistent_id` in the workflow schema.
+     */
+    persistent_id: string;
+    /**
+     * Ungraded
+     *
+     * Values of this field with no ground truth to grade against.
+     */
+    ungraded: number;
+};
+/**
+ * FieldValuesV3
+ *
+ * One field's extracted value beside its ground truth.
+ */
+type FieldValuesV3 = {
+    /**
+     * Expected
+     *
+     * The ground-truth value, in the same shape.
+     */
+    expected?: unknown;
+    /**
+     * Extracted
+     *
+     * The value the eval extracted. A scalar for a scalar field; for a field inside a list or object, one value per row, in row order.
+     */
+    extracted?: unknown;
+    /**
+     * Persistent Id
+     *
+     * The field's `persistent_id` in the workflow schema.
+     */
+    persistent_id: string;
+};
 /**
  * FilePages
  *
@@ -2495,6 +2892,35 @@ type WorkflowSummaryV3 = {
      */
     updated_at?: string | null;
 };
+/**
+ * WorkflowVersionSummaryV3
+ *
+ * One entry in a workflow's version history.
+ *
+ * Versions are read-only: they exist for comparison and audit, and runs
+ * always use the latest version. Pass ``version_id`` as
+ * ``GET /v3/workflows/{workflow_id}/?version=`` to read that version's graph.
+ */
+type WorkflowVersionSummaryV3 = {
+    /**
+     * Created At
+     *
+     * Timestamp when the version was created (ISO 8601).
+     */
+    created_at?: string | null;
+    /**
+     * Version
+     *
+     * Display number, `major.minor.patch`.
+     */
+    version: string;
+    /**
+     * Version Id
+     *
+     * Identifier of the version; pass it as `?version=` on `GET /v3/workflows/{workflow_id}/`.
+     */
+    version_id: string;
+};
 /**
  * _FieldOperand
  */
@@ -2903,6 +3329,13 @@ interface ListOptions {
     /** Opaque token from a previous page's `nextCursor`. */
     cursor?: string;
 }
+/** Narrows an eval to a tagged subset; omit both for the whole dataset. */
+interface DatasetTagFilter {
+    /** Documents carrying at least one of these dataset tags. */
+    datasetTagIds?: string[];
+    /** Documents with no dataset tag; with `datasetTagIds`, their union. */
+    untagged?: boolean;
+}
 interface IterOptions {
     /** Page size the auto-pager fetches per underlying request, capped at 100 by the API. */
     limit?: number;
@@ -2920,8 +3353,13 @@ declare class Anyformat {
     constructor(opts: AnyformatOptions);
     workflow(name: string, description?: string): WorkflowBuilder;
     listWorkflows(opts?: ListOptions): Promise<Page<Workflow>>;
-    /** Retrieve a workflow with its complete typed graph inline (round-trippable into `updateWorkflow`). */
-    getWorkflow(workflowId: string): Promise<WorkflowDetailV3>;
+    /**
+     * Retrieve a workflow with its complete typed graph inline (round-trippable into `updateWorkflow`).
+     * Pass a `version_id` as `version` to read that version instead of the current one.
+     */
+    getWorkflow(workflowId: string, opts?: {
+        version?: string;
+    }): Promise<WorkflowDetailV3>;
     /**
      * Replace a workflow's typed graph (atomic). Accepts the shape `getWorkflow`
      * returns — echo each field's `persistent_id` unchanged (including across
@@ -2951,6 +3389,10 @@ declare class Anyformat {
     iterDocumentPackets(workflowId: string, opts?: IterOptions): AsyncIterableIterator<DocumentPacketSummaryV3>;
     /** Every run of a workflow, following `nextCursor` across pages. Lazy. */
     iterRuns(workflowId: string, opts?: IterOptions): AsyncIterableIterator<RunSummaryV3>;
+    /** A workflow's versions, newest first; item 0 of the first page is the current version. */
+    listWorkflowVersions(workflowId: string, opts?: ListOptions): Promise<Page<WorkflowVersionSummaryV3>>;
+    /** Every version of a workflow, newest first, following `nextCursor` across pages. Lazy. */
+    iterWorkflowVersions(workflowId: string, opts?: IterOptions): AsyncIterableIterator<WorkflowVersionSummaryV3>;
     /** Retrieve one run: lifecycle status plus results inline once `processed`. */
     getRun(runId: string): Promise<RunDetailV3>;
     /**
@@ -2975,6 +3417,25 @@ declare class Anyformat {
      * or `null` while it is still queued or in progress.
      */
     getParseMarkdown(runId: string): Promise<string | null>;
+    /** A workflow's dataset tags, ordered by name; a tag's `id` is what `datasetTagIds` takes. */
+    listDatasetTags(workflowId: string): Promise<DatasetTagV3[]>;
+    /**
+     * Launch an eval: extract every dataset document on a version and grade it
+     * against ground truth. Billed per document. Omit `versionId` for the current
+     * version. `idempotencyKey` makes a retry return the original eval instead of
+     * launching a second one. `datasetTagIds: []` without `untagged: true` throws.
+     */
+    launchEval(workflowId: string, opts?: DatasetTagFilter & {
+        versionId?: string;
+        idempotencyKey?: string;
+    }): Promise<EvalLaunchedV3>;
+    /** One eval's headline; poll it until `status` leaves `in_progress`. */
+    getEval(workflowId: string, evalId: string): Promise<EvalDetailV3>;
+    listEvals(workflowId: string, opts?: ListOptions): Promise<Page<EvalDetailV3>>;
+    /** An eval's accuracy per field, per document and per dataset tag; partial while it runs. */
+    getEvalAccuracy(workflowId: string, evalId: string): Promise<AccuracyV3>;
+    /** One eval document's extracted values beside its ground truth. The id is the dataset copy's. */
+    getEvalDocumentPacketFields(workflowId: string, evalId: string, documentPacketId: string): Promise<EvalDocumentPacketFieldsV3>;
 }
 
 declare class AnyformatError extends Error {
@@ -3054,4 +3515,4 @@ declare class ExtractionCancelledError extends RunFailedError {
 declare class WorkflowBuilderError extends AnyformatError {
 }
 
-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 SplitPartition, type SplitResult, 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 };
+export { APIError, type AccuracyCoverageV3, type AccuracyV3, type AllOfCheck, type AnyOfCheck, Anyformat, AnyformatError, type AnyformatOptions, type ArithmeticCheck, BadRequestError, type Block, type BooleanField, type Branch, type ClassifyCategory, type ComparisonCheck, type DatasetDocument, type DatasetTagAccuracyV3, type DatasetTagFilter, type DatasetTagV3, DatasetUpload, type DatasetUploadFileV3, type DatasetUploadOptions, type DatasetUploadResponseV3, type DateCheck, type DateField, type DatetimeField, type DocumentPacketAccuracyV3, type DocumentPacketDetailV3, type DocumentPacketFileV3, type DocumentPacketStatus, type DocumentPacketSummaryV3, type Edge, type EnumField, type EnumOption, type EvalDetailV3, type EvalDocumentPacketFieldsV3, type EvalLaunchedV3, type ExpressionCheck, type ExtractedField, type ExtractedRows, type Extraction, ExtractionCancelledError, ExtractionFailedError, type ExtractionSchema, type Field, type FieldAccuracyV3, type FieldValuesV3, 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 SplitPartition, type SplitResult, 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, type WorkflowVersionSummaryV3 };