@gpt-platform/client 0.10.4 → 0.11.0

package/dist/namespaces/extraction.d.ts

@@ -0,0 +1,1249 @@
+import type { ExtractionAgent, ExtractionBatch, ExtractionDocument, ExtractionResult, TrainingAnalytics } from "../_internal/types.gen";
+import type { RequestOptions } from "../base-client";
+import { RequestBuilder } from "../request-builder";
+/** Attributes for bulk-delete operations. */
+export interface BulkOperationResult {
+    deleted_count?: number;
+    [key: string]: unknown;
+}
+/** Attributes for bulk-reprocess operations. */
+export interface BulkReprocessResult {
+    enqueued_count?: number;
+    [key: string]: unknown;
+}
+/** Lightweight document processing status. */
+export interface DocumentStatusResponse {
+    status?: string;
+    progress_percent?: number;
+    [key: string]: unknown;
+}
+/** Attributes for beginning an extraction document upload. */
+export type BeginUploadAttributes = {
+    filename?: string;
+    content_type?: string;
+    size?: number;
+    agent_id?: string;
+    workspace_id?: string;
+    [key: string]: unknown;
+};
+/** Attributes for find-or-begin upload (dedup-aware). */
+export type FindOrBeginUploadAttributes = {
+    filename?: string;
+    file_hash?: string;
+    content_type?: string;
+    agent_id?: string;
+    [key: string]: unknown;
+};
+/** Aggregate document statistics for a workspace. */
+export interface DocumentStatsResponse {
+    total_count?: number;
+    processed_count?: number;
+    failed_count?: number;
+    pending_count?: number;
+    processing_count?: number;
+    cancelled_count?: number;
+    [key: string]: unknown;
+}
+/** Attributes for updating extraction document verification state. */
+export type UpdateVerificationAttributes = {
+    verified?: boolean;
+    reviewer_id?: string;
+    verification_notes?: string;
+    [key: string]: unknown;
+};
+/** Result of a dismiss-all-trained operation. */
+export interface DismissAllTrainedResult {
+    dismissed_count?: number;
+    [key: string]: unknown;
+}
+/** Attributes for requesting a presigned upload URL. */
+export type ExtractionPresignedUploadAttributes = {
+    filename: string;
+    content_type?: string;
+    size?: number;
+    [key: string]: unknown;
+};
+/** Response from a presigned upload request. */
+export interface ExtractionPresignedUploadResponse {
+    upload_url?: string;
+    document_id?: string;
+    [key: string]: unknown;
+}
+/** Attributes for updating an extraction result. */
+export type UpdateExtractionResultAttributes = {
+    review_status?: string;
+    [key: string]: unknown;
+};
+/** Attributes for regenerating an extraction result. */
+export type RegenerateResultAttributes = {
+    agent_version?: string;
+    [key: string]: unknown;
+};
+/** Attributes for saving corrections on an extraction result. */
+export type SaveCorrectionsAttributes = {
+    corrections: Record<string, unknown>[];
+    [key: string]: unknown;
+};
+/** Attributes for creating an extraction batch. */
+export type CreateExtractionBatchAttributes = {
+    name?: string;
+    agent_id?: string;
+    workspace_id?: string;
+    document_ids?: string[];
+    [key: string]: unknown;
+};
+/** An extraction export record. */
+export interface ExtractionExportRecord {
+    id?: string;
+    status?: string;
+    format?: string;
+    download_url?: string;
+    [key: string]: unknown;
+}
+/** Attributes for creating an extraction export. */
+export type CreateExtractionExportAttributes = {
+    format: "csv" | "json" | "excel";
+    agent_id?: string;
+    [key: string]: unknown;
+};
+/** Attributes for creating a schema discovery job. */
+export type CreateSchemaDiscoveryAttributes = {
+    document_ids?: string[];
+    sample_text?: string;
+    [key: string]: unknown;
+};
+/** A schema discovery record. */
+export interface SchemaDiscoveryRecord {
+    id?: string;
+    status?: string;
+    suggested_fields?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+/** A field template record. */
+export interface FieldTemplateRecord {
+    id?: string;
+    name?: string;
+    category?: string;
+    field_type?: string;
+    [key: string]: unknown;
+}
+/** Attributes for creating a field template. */
+export type CreateFieldTemplateAttributes = {
+    name: string;
+    category?: string;
+    field_type?: string;
+    [key: string]: unknown;
+};
+/** A field mapping record. */
+export interface FieldMappingRecord {
+    confirmed?: boolean;
+    mappings?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+/** Attributes for creating/confirming a field mapping. */
+export type CreateFieldMappingAttributes = {
+    confirmed: boolean;
+    mappings?: Record<string, unknown>[];
+    [key: string]: unknown;
+};
+/**
+ * A single attribute filter predicate for server-side JSONB row filtering.
+ * Operators: eq, not_eq, contains, in, lt, gt, not_null
+ */
+export interface AttributeFilter {
+    /** The column name to filter on */
+    field: string;
+    /** Comparison operator */
+    op: "eq" | "not_eq" | "contains" | "in" | "lt" | "gt" | "not_null";
+    /** The comparison value. Not required for `not_null`. For `in`, must be an array. */
+    value?: unknown;
+}
+/** Parameters for `results.query()` */
+export interface ExtractionRowQueryParams {
+    /** Filter predicates applied server-side (AND semantics). Empty array returns all rows. */
+    filters?: AttributeFilter[];
+    /** Maximum rows to return. Defaults to 1000. Server enforces max 5000. */
+    limit?: number;
+    /** Zero-based row offset for pagination. Defaults to 0. */
+    offset?: number;
+}
+/** Response from `results.query()` */
+export interface ExtractionRowQueryResult {
+    /** Matching rows (up to `limit` rows) */
+    rows: Record<string, unknown>[];
+    /** Total number of rows in the result (before filtering) */
+    total: number;
+    /** Number of rows that matched the filters */
+    filtered: number;
+    /** The effective limit used */
+    limit: number;
+    /** The effective offset used */
+    offset: number;
+}
+/**
+ * Creates the extraction namespace providing access to document upload,
+ * processing, results, batches, exports, schema discovery, field templates,
+ * and field mappings.
+ *
+ * Access via `client.extraction`.
+ *
+ * @example
+ * ```typescript
+ * const client = new GptClient({ apiKey: 'sk_app_...' });
+ *
+ * // Upload a document and wait for extraction
+ * const doc = await client.extraction.documents.upload(file);
+ * console.log(doc.id);
+ * ```
+ */
+export declare function createExtractionNamespace(rb: RequestBuilder): {
+    /**
+     * Documents — upload, manage, and track extraction documents.
+     *
+     * Documents move through a lifecycle: `pending` → `processing` → `processed`
+     * (or `failed`). Use `documents.status` to poll progress. Completed documents
+     * have associated `ExtractionResult` records accessible via `results.byDocument`.
+     */
+    documents: {
+        /**
+         * List extraction documents with optional pagination.
+         *
+         * Returns one page of documents. Use `listAll` to automatically traverse
+         * all pages.
+         *
+         * @param options - Optional page number, page size, and request options.
+         * @returns A page of `ExtractionDocument` records.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const docs = await client.extraction.documents.list({ page: 1, pageSize: 25 });
+         * console.log(docs.length);
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<ExtractionDocument[]>;
+        /**
+         * List all extraction documents, automatically paginating through every page.
+         *
+         * Fetches pages sequentially until the server reports no more results.
+         * Suitable for datasets that fit in memory; for very large collections
+         * prefer `list` with explicit pagination.
+         *
+         * @param options - Optional request options (signal, headers, etc.).
+         * @returns All `ExtractionDocument` records as a flat array.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const allDocs = await client.extraction.documents.listAll();
+         * console.log(`Total documents: ${allDocs.length}`);
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<ExtractionDocument[]>;
+        /**
+         * Retrieve a single extraction document by its ID.
+         *
+         * @param id - The UUID of the extraction document.
+         * @param options - Optional request options.
+         * @returns The matching `ExtractionDocument`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.get('doc_abc123');
+         * console.log(doc.attributes?.status);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Retrieve the viewer-facing representation of an extraction document.
+         *
+         * Returns a version of the document enriched with display metadata
+         * (e.g., page thumbnails, viewer annotations) suitable for rendering
+         * in the document review UI. Differs from `get` in that it may include
+         * pre-signed URL references for inline rendering.
+         *
+         * @param id - The UUID of the extraction document.
+         * @param options - Optional request options.
+         * @returns The viewer-enriched `ExtractionDocument`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const viewDoc = await client.extraction.documents.view('doc_abc123');
+         * // Use viewDoc.attributes?.viewer_url for embedding in an iframe
+         * ```
+         */
+        view: (id: string, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Permanently delete an extraction document.
+         *
+         * This removes the document record and its associated storage object.
+         * Deletion is irreversible. Any linked `ExtractionResult` records will
+         * also be removed by the server via cascade.
+         *
+         * @param id - The UUID of the extraction document to delete.
+         * @param options - Optional request options.
+         * @returns `true` on successful deletion.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.extraction.documents.delete('doc_abc123');
+         * ```
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Bulk-delete multiple extraction documents in a single request.
+         *
+         * More efficient than calling `delete` in a loop. The server processes
+         * deletions transactionally; if any ID is not found the entire operation
+         * may be rejected (depends on server policy).
+         *
+         * @param ids - Array of document UUIDs to delete.
+         * @param options - Optional request options.
+         * @returns An operation result object with counts of deleted records.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.documents.bulkDelete([
+         *   'doc_abc123',
+         *   'doc_def456',
+         * ]);
+         * console.log(result);
+         * ```
+         */
+        bulkDelete: (ids: string[], options?: RequestOptions) => Promise<BulkOperationResult>;
+        /**
+         * Re-run extraction on an existing document.
+         *
+         * Queues the document for re-processing through the extraction pipeline.
+         * Useful after updating an agent's schema or correcting a failed extraction.
+         * The document transitions back to `processing` status and any previous
+         * `ExtractionResult` records are replaced on completion.
+         *
+         * @param id - The UUID of the extraction document to reprocess.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionDocument` with new processing status.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.reprocess('doc_abc123');
+         * console.log(doc.attributes?.status); // "processing"
+         * ```
+         */
+        reprocess: (id: string, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Re-run extraction on multiple documents in a single request.
+         *
+         * Enqueues all specified documents for re-processing. More efficient
+         * than calling `reprocess` in a loop when handling batch corrections.
+         *
+         * @param documentIds - Array of document UUIDs to reprocess.
+         * @param options - Optional request options.
+         * @returns An operation result object indicating how many jobs were enqueued.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.documents.bulkReprocess([
+         *   'doc_abc123',
+         *   'doc_def456',
+         * ]);
+         * console.log(result);
+         * ```
+         */
+        bulkReprocess: (documentIds: string[], options?: RequestOptions) => Promise<BulkReprocessResult>;
+        /**
+         * Cancel an in-progress extraction job for a document.
+         *
+         * Signals the extraction pipeline to abort processing. The document
+         * transitions to `cancelled` status. A cancelled document can be
+         * reprocessed later via `reprocess`.
+         *
+         * @param id - The UUID of the extraction document to cancel.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionDocument` with `status: "cancelled"`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.cancel('doc_abc123');
+         * console.log(doc.attributes?.status); // "cancelled"
+         * ```
+         */
+        cancel: (id: string, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Get the current processing status of an extraction document.
+         *
+         * Returns a lightweight status object without the full document payload.
+         * Suitable for polling in a tight loop to track extraction progress.
+         *
+         * @param id - The UUID of the extraction document.
+         * @param options - Optional request options.
+         * @returns A status object with at least `{ status, progress_percent }`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const status = await client.extraction.documents.status('doc_abc123');
+         * console.log(status.status); // "processing" | "processed" | "failed"
+         * ```
+         */
+        status: (id: string, options?: RequestOptions) => Promise<DocumentStatusResponse>;
+        /**
+         * Phase 1 of a two-phase presigned upload: create the document record.
+         *
+         * Creates an `ExtractionDocument` in `pending_upload` status and returns
+         * a presigned upload URL. After uploading the file directly to storage
+         * using that URL, call `finishUpload` with the same document ID to
+         * transition the document into the extraction pipeline.
+         *
+         * Typical attributes: `{ filename, content_type, size, agent_id, workspace_id }`.
+         *
+         * @param attrs - Document attributes to seed the record with.
+         * @param options - Optional request options.
+         * @returns The newly created `ExtractionDocument` including the presigned URL.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.beginUpload({
+         *   filename: 'lab-results.pdf',
+         *   content_type: 'application/pdf',
+         *   size: 204800,
+         *   agent_id: 'agent_xyz',
+         * });
+         * // doc.attributes?.upload_url contains the presigned PUT URL
+         * await fetch(doc.attributes!.upload_url as string, {
+         *   method: 'PUT',
+         *   body: fileBlob,
+         * });
+         * await client.extraction.documents.finishUpload(doc.id!);
+         * ```
+         */
+        beginUpload: (attrs: BeginUploadAttributes, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Dedup-aware upload: returns an existing document if `file_hash` matches,
+         * otherwise creates a new document record and begins the upload flow.
+         *
+         * Pass a `file_hash` attribute (BLAKE3 or SHA-256 hex) to enable deduplication.
+         * If the platform already has a document with that hash in the current workspace,
+         * the existing document is returned without creating a duplicate. Otherwise
+         * behaves identically to `beginUpload`.
+         *
+         * @param attrs - Optional document attributes including `file_hash` for dedup.
+         * @param options - Optional request options.
+         * @returns The matching existing `ExtractionDocument`, or a newly created one.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.findOrBeginUpload({
+         *   filename: 'lab-results.pdf',
+         *   file_hash: 'abc123def456...',
+         *   agent_id: 'agent_xyz',
+         * });
+         * if (doc.attributes?.status === 'processed') {
+         *   // Already exists — skip upload
+         * } else {
+         *   // New document — proceed with upload
+         * }
+         * ```
+         */
+        findOrBeginUpload: (attrs?: FindOrBeginUploadAttributes, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Phase 2 of a two-phase presigned upload: signal that the file is uploaded.
+         *
+         * After the binary file has been PUT directly to the presigned storage URL
+         * (obtained from `beginUpload`), call this method to notify the platform that
+         * the file is ready. The document transitions from `pending_upload` into the
+         * extraction pipeline (`processing`).
+         *
+         * @param id - The UUID of the extraction document created in `beginUpload`.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionDocument` now in `processing` status.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * // After the PUT to the presigned URL completes:
+         * const doc = await client.extraction.documents.finishUpload('doc_abc123');
+         * console.log(doc.attributes?.status); // "processing"
+         * ```
+         */
+        finishUpload: (id: string, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Retrieve aggregate statistics for all documents in the current workspace.
+         *
+         * Returns counts broken down by status (pending, processing, processed,
+         * failed, cancelled) and any quota/usage information available to the
+         * current actor.
+         *
+         * @param options - Optional request options.
+         * @returns A stats object with document counts and usage figures.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const stats = await client.extraction.documents.stats();
+         * console.log(stats.processed_count, stats.failed_count);
+         * ```
+         */
+        stats: (options?: RequestOptions) => Promise<DocumentStatsResponse>;
+        /**
+         * Dismiss a document from the training queue.
+         *
+         * Marks the document so it no longer appears in the "needs review" or
+         * "needs training" queues, without deleting it. The extracted data is
+         * preserved. Useful for clearing noise documents that are not worth
+         * adding to the training corpus.
+         *
+         * @param id - The UUID of the extraction document to dismiss.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionDocument` with a dismissed flag.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.dismiss('doc_abc123');
+         * console.log(doc.attributes?.dismissed); // true
+         * ```
+         */
+        dismiss: (id: string, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Update the human verification state of an extraction document.
+         *
+         * Allows a reviewer to mark fields as verified, flag discrepancies,
+         * or record the outcome of a manual review pass. Accepted attributes
+         * depend on the agent schema but commonly include `verified`, `reviewer_id`,
+         * and `verification_notes`.
+         *
+         * @param id - The UUID of the extraction document.
+         * @param attrs - Verification attributes to update.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionDocument` reflecting new verification state.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const doc = await client.extraction.documents.updateVerification('doc_abc123', {
+         *   verified: true,
+         *   reviewer_id: 'user_xyz',
+         *   verification_notes: 'Values confirmed against source records.',
+         * });
+         * ```
+         */
+        updateVerification: (id: string, attrs: UpdateVerificationAttributes, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Dismiss all documents that have already contributed to agent training.
+         *
+         * Bulk-dismisses every document in the given workspace whose extraction
+         * data has been used for model fine-tuning or training. Clears the
+         * training queue so only new, unreviewed documents remain.
+         *
+         * @param workspaceId - The UUID of the workspace to dismiss trained documents in.
+         * @param options - Optional request options.
+         * @returns An operation result with the count of dismissed documents.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.documents.dismissAllTrained('ws_abc123');
+         * console.log(result.dismissed_count);
+         * ```
+         */
+        dismissAllTrained: (workspaceId: string, options?: RequestOptions) => Promise<DismissAllTrainedResult>;
+        /**
+         * List extraction documents scoped to a specific workspace.
+         *
+         * Equivalent to `list` but scoped to a single workspace. Useful when
+         * operating with a server-side key that has access to multiple workspaces.
+         *
+         * @param workspaceId - The UUID of the workspace to list documents for.
+         * @param options - Optional page number, page size, and request options.
+         * @returns A page of `ExtractionDocument` records in the given workspace.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const docs = await client.extraction.documents.listByWorkspace('ws_abc123', {
+         *   page: 1,
+         *   pageSize: 50,
+         * });
+         * ```
+         */
+        listByWorkspace: (workspaceId: string, options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<ExtractionDocument[]>;
+        /**
+         * Upload a document file directly (single-request upload).
+         *
+         * Sends the file binary as the request body. The server creates the
+         * document record, stores the file, and enqueues it for extraction in
+         * a single atomic operation. Best for files under ~50 MB; for larger
+         * files use the two-phase `beginUpload` / `finishUpload` flow with
+         * presigned URLs to avoid gateway timeouts.
+         *
+         * @param file - The `File` or `Blob` to upload.
+         * @param options - Optional request options (signal for cancellation, etc.).
+         * @returns The newly created `ExtractionDocument` in `processing` status.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const fileInput = document.querySelector<HTMLInputElement>('#upload')!;
+         * const [file] = fileInput.files!;
+         * const doc = await client.extraction.documents.upload(file);
+         * console.log(`Document ${doc.id} is ${doc.attributes?.status}`);
+         * ```
+         */
+        upload: (file: File | Blob, options?: RequestOptions) => Promise<ExtractionDocument>;
+        /**
+         * Request a presigned upload URL for a document to be uploaded directly
+         * to cloud storage from the client.
+         *
+         * Returns a presigned PUT URL that the caller can use to upload the file
+         * binary directly to the storage backend without routing through the API
+         * server. Validated against `PresignedUploadSchema`; `filename` is
+         * required, `content_type` and `size` are recommended.
+         *
+         * @param attrs - Upload request attributes: `filename` (required),
+         *   `content_type`, and `size` in bytes.
+         * @param options - Optional request options.
+         * @returns An object containing `upload_url`, `document_id`, and expiry info.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.documents.presignedUpload({
+         *   filename: 'intake-form.pdf',
+         *   content_type: 'application/pdf',
+         *   size: 512000,
+         * });
+         * await fetch(result.upload_url as string, {
+         *   method: 'PUT',
+         *   body: fileBlob,
+         *   headers: { 'Content-Type': 'application/pdf' },
+         * });
+         * ```
+         */
+        presignedUpload: (attrs: ExtractionPresignedUploadAttributes, options?: RequestOptions) => Promise<ExtractionPresignedUploadResponse>;
+    };
+    /**
+     * Results — access and manage extracted data from processed documents.
+     *
+     * Each processed `ExtractionDocument` produces one or more `ExtractionResult`
+     * records containing the structured data extracted by the agent. Results can
+     * be queried, corrected, regenerated, and exported.
+     */
+    results: {
+        /**
+         * List extraction results with optional pagination.
+         *
+         * Returns one page of results. Use `listAll` to automatically traverse
+         * all pages.
+         *
+         * @param options - Optional page number, page size, and request options.
+         * @returns A page of `ExtractionResult` records.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const results = await client.extraction.results.list({ page: 1, pageSize: 20 });
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<ExtractionResult[]>;
+        /**
+         * List all extraction results, automatically paginating through every page.
+         *
+         * @param options - Optional request options.
+         * @returns All `ExtractionResult` records as a flat array.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const allResults = await client.extraction.results.listAll();
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<ExtractionResult[]>;
+        /**
+         * Retrieve a single extraction result by its ID.
+         *
+         * @param id - The UUID of the extraction result.
+         * @param options - Optional request options.
+         * @returns The matching `ExtractionResult`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.results.get('res_abc123');
+         * console.log(result.attributes?.rows);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<ExtractionResult>;
+        /**
+         * Update an extraction result's attributes.
+         *
+         * Allows updating metadata fields on a result record (e.g., tags,
+         * review status, custom attributes). Does not alter the extracted rows;
+         * use `saveCorrections` to modify extracted data.
+         *
+         * @param id - The UUID of the extraction result.
+         * @param attributes - Attribute map of fields to update.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionResult`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.results.update('res_abc123', {
+         *   review_status: 'approved',
+         * });
+         * ```
+         */
+        update: (id: string, attributes: UpdateExtractionResultAttributes, options?: RequestOptions) => Promise<ExtractionResult>;
+        /**
+         * Permanently delete an extraction result.
+         *
+         * @param id - The UUID of the extraction result to delete.
+         * @param options - Optional request options.
+         * @returns `true` on successful deletion.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.extraction.results.delete('res_abc123');
+         * ```
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * List all extraction results for a specific document.
+         *
+         * A single document may produce multiple result records (e.g., one per
+         * page, or one per extraction pass). This returns all of them.
+         *
+         * @param documentId - The UUID of the extraction document.
+         * @param options - Optional request options.
+         * @returns All `ExtractionResult` records for the given document.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const results = await client.extraction.results.byDocument('doc_abc123');
+         * results.forEach(r => console.log(r.attributes?.rows?.length));
+         * ```
+         */
+        byDocument: (documentId: string, options?: RequestOptions) => Promise<ExtractionResult[]>;
+        /**
+         * Re-run AI extraction for a specific result record.
+         *
+         * Triggers the extraction agent to reprocess the result, optionally with
+         * updated instructions or a different model configuration. The existing
+         * rows in the result are replaced when the new extraction completes.
+         *
+         * @param id - The UUID of the extraction result to regenerate.
+         * @param attrs - Optional attributes to influence regeneration (e.g., `agent_version`).
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionResult` queued for regeneration.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.results.regenerate('res_abc123', {
+         *   agent_version: 'v2',
+         * });
+         * ```
+         */
+        regenerate: (id: string, attrs: RegenerateResultAttributes, options?: RequestOptions) => Promise<ExtractionResult>;
+        /**
+         * Submit human corrections to an extraction result for retraining.
+         *
+         * Persists manually corrected row data against the result record.
+         * These corrections feed into the agent's fine-tuning pipeline,
+         * improving future extractions on similar documents.
+         * Validated against `SaveCorrectionsSchema` — `corrections` must be a
+         * non-empty array of row objects.
+         *
+         * @param id - The UUID of the extraction result to correct.
+         * @param attrs - Must include a `corrections` array of corrected row objects.
+         * @param options - Optional request options.
+         * @returns The updated `ExtractionResult` with corrections applied.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.results.saveCorrections('res_abc123', {
+         *   corrections: [
+         *     { patient_name: 'Jane Smith', dob: '1985-04-12', score: 92 },
+         *     { patient_name: 'John Doe',   dob: '1990-07-03', score: 78 },
+         *   ],
+         * });
+         * ```
+         */
+        saveCorrections: (id: string, attrs: SaveCorrectionsAttributes, options?: RequestOptions) => Promise<ExtractionResult>;
+        /**
+         * List extraction results scoped to a specific workspace.
+         *
+         * @param workspaceId - The UUID of the workspace to list results for.
+         * @param options - Optional page number, page size, and request options.
+         * @returns A page of `ExtractionResult` records in the given workspace.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const results = await client.extraction.results.listByWorkspace('ws_abc123');
+         * ```
+         */
+        listByWorkspace: (workspaceId: string, options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<ExtractionResult[]>;
+        /**
+         * Query rows in an ExtractionResult server-side.
+         *
+         * Applies `AttributeFilter` predicates against the `rows` JSONB array
+         * using a PostgreSQL lateral join. Suitable for datasets with 10K+ rows
+         * where fetching the entire result set would be impractical.
+         * Empty `filters` array returns all rows (paginated by `limit`/`offset`).
+         *
+         * Filter operators:
+         * - `eq` / `not_eq` — exact match / non-match
+         * - `contains` — substring match (string fields)
+         * - `in` — membership in an array of values
+         * - `lt` / `gt` — numeric less-than / greater-than
+         * - `not_null` — field is present and non-null (no `value` needed)
+         *
+         * @param resultId - The UUID of the extraction result to query.
+         * @param params - Query parameters including filters, limit, and offset.
+         * @param options - Optional request options.
+         * @returns An `ExtractionRowQueryResult` with matching rows and total counts.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.extraction.results.query('res_abc123', {
+         *   filters: [
+         *     { field: 'wellness_score', op: 'gt', value: 75 },
+         *     { field: 'enrolled', op: 'eq', value: 'true' },
+         *   ],
+         *   limit: 100,
+         *   offset: 0,
+         * });
+         * console.log(`${result.filtered} of ${result.total} rows match`);
+         * ```
+         */
+        query: (resultId: string, params?: ExtractionRowQueryParams, options?: RequestOptions) => Promise<ExtractionRowQueryResult>;
+    };
+    /**
+     * Batches — group documents for coordinated extraction runs.
+     *
+     * Batches allow you to associate multiple documents under a single job,
+     * track overall completion, and perform aggregate exports.
+     */
+    batches: {
+        /**
+         * Create a new extraction batch.
+         *
+         * A batch groups documents for coordinated processing. Typical attributes
+         * include `name`, `agent_id`, `workspace_id`, and an initial list of
+         * `document_ids`.
+         *
+         * @param attributes - Batch creation attributes.
+         * @param options - Optional request options.
+         * @returns The newly created `ExtractionBatch`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const batch = await client.extraction.batches.create({
+         *   name: 'Q1 Lab Reports',
+         *   agent_id: 'agent_xyz',
+         *   workspace_id: 'ws_abc123',
+         * });
+         * console.log(batch.id);
+         * ```
+         */
+        create: (attributes: CreateExtractionBatchAttributes, options?: RequestOptions) => Promise<ExtractionBatch>;
+        /**
+         * Retrieve a single extraction batch by its ID.
+         *
+         * @param id - The UUID of the extraction batch.
+         * @param options - Optional request options.
+         * @returns The matching `ExtractionBatch` with current status and document counts.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const batch = await client.extraction.batches.get('batch_abc123');
+         * console.log(batch.attributes?.completed_count, '/', batch.attributes?.total_count);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<ExtractionBatch>;
+        /**
+         * Delete an extraction batch.
+         *
+         * Removes the batch record. Documents that were part of the batch are
+         * not deleted; only the batch grouping is removed.
+         *
+         * @param id - The UUID of the extraction batch to delete.
+         * @param options - Optional request options.
+         * @returns `true` on successful deletion.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.extraction.batches.delete('batch_abc123');
+         * ```
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * List extraction batches scoped to a specific workspace.
+         *
+         * @param workspaceId - The UUID of the workspace to list batches for.
+         * @param options - Optional page number, page size, and request options.
+         * @returns A page of `ExtractionBatch` records in the given workspace.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const batches = await client.extraction.batches.listByWorkspace('ws_abc123');
+         * ```
+         */
+        listByWorkspace: (workspaceId: string, options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<ExtractionBatch[]>;
+    };
+    /**
+     * Exports — generate downloadable files from extraction results.
+     *
+     * Exports produce CSV, JSON, or Excel files containing the extracted
+     * data for a workspace. Export jobs are asynchronous; poll the returned
+     * record until `status` is `"ready"`, then use the provided download URL.
+     */
+    exports: {
+        /**
+         * List extraction exports for a workspace.
+         *
+         * @param workspaceId - The UUID of the workspace to list exports for.
+         * @param options - Optional page number, page size, and request options.
+         * @returns A page of export records.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const exports = await client.extraction.exports.list('ws_abc123');
+         * ```
+         */
+        list: (workspaceId: string, options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<ExtractionExportRecord[]>;
+        /**
+         * Create a new extraction export job for a workspace.
+         *
+         * Enqueues an async export. Required attributes: `format` (one of
+         * `"csv"`, `"json"`, `"excel"`). Optional: `agent_id` to filter results
+         * to a specific agent.
+         * Validated against `ExportCreateSchema`.
+         *
+         * @param workspaceId - The UUID of the workspace to export from.
+         * @param attrs - Export attributes: `format` and optional `agent_id`.
+         * @param options - Optional request options.
+         * @returns The newly created export record (initially `status: "pending"`).
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const exportJob = await client.extraction.exports.create('ws_abc123', {
+         *   format: 'csv',
+         *   agent_id: 'agent_xyz',
+         * });
+         * console.log(exportJob.id); // Poll until exportJob.status === "ready"
+         * ```
+         */
+        create: (workspaceId: string, attrs: CreateExtractionExportAttributes, options?: RequestOptions) => Promise<ExtractionExportRecord>;
+        /**
+         * Fetches a single export by ID.
+         *
+         * @param workspaceId - The UUID of the workspace.
+         * @param id - The export record ID.
+         * @param options - Optional request options.
+         * @returns The export record.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const exportJob = await client.extraction.exports.get('ws_abc123', 'export_id');
+         * ```
+         */
+        get: (workspaceId: string, id: string, options?: RequestOptions) => Promise<ExtractionExportRecord>;
+    };
+    /**
+     * Schema Discoveries — AI-powered schema inference from sample documents.
+     *
+     * Submit sample documents to have the platform infer a recommended
+     * extraction schema (field names, types, nesting). Use the discovered
+     * schema as a starting point for a new agent definition.
+     */
+    schemaDiscoveries: {
+        /**
+         * Initiate a new schema discovery job.
+         *
+         * Submits sample document IDs or raw text to the schema inference engine.
+         * The job runs asynchronously; poll with `get` until `status` is `"complete"`.
+         *
+         * @param attrs - Discovery attributes, typically including `document_ids`
+         *   or `sample_text`.
+         * @param options - Optional request options.
+         * @returns The newly created schema discovery record.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const discovery = await client.extraction.schemaDiscoveries.create({
+         *   document_ids: ['doc_abc123', 'doc_def456'],
+         * });
+         * console.log(discovery.id); // Poll until discovery.status === "complete"
+         * ```
+         */
+        create: (attrs: CreateSchemaDiscoveryAttributes, options?: RequestOptions) => Promise<SchemaDiscoveryRecord>;
+        /**
+         * Retrieve the result of a schema discovery job.
+         *
+         * Once `status` is `"complete"`, the result includes `suggested_fields`
+         * — an array of inferred field definitions suitable for use in an agent
+         * schema.
+         *
+         * @param id - The UUID of the schema discovery job.
+         * @param options - Optional request options.
+         * @returns The schema discovery record with `suggested_fields` when complete.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const discovery = await client.extraction.schemaDiscoveries.get('sd_abc123');
+         * if (discovery.status === 'complete') {
+         *   console.log(discovery.suggested_fields);
+         * }
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<SchemaDiscoveryRecord>;
+    };
+    /**
+     * Field Templates — reusable extraction field definitions.
+     *
+     * Field templates are named, typed field definitions that can be reused
+     * across multiple agent schemas. They serve as a shared vocabulary of
+     * extraction fields within a workspace, reducing duplication and improving
+     * consistency.
+     */
+    fieldTemplates: {
+        /**
+         * List all field templates available to the current actor.
+         *
+         * @param options - Optional request options.
+         * @returns An array of field template records.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const templates = await client.extraction.fieldTemplates.list();
+         * templates.forEach(t => console.log(t.attributes?.name));
+         * ```
+         */
+        list: (options?: RequestOptions) => Promise<FieldTemplateRecord[]>;
+        /**
+         * Retrieve a single field template by its ID.
+         *
+         * @param id - The UUID of the field template.
+         * @param options - Optional request options.
+         * @returns The matching field template record.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const template = await client.extraction.fieldTemplates.get('ft_abc123');
+         * console.log(template.attributes?.field_type);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<FieldTemplateRecord>;
+        /**
+         * Create a new field template.
+         *
+         * Required attribute: `name`. Optional: `category` (for grouping in the UI)
+         * and `field_type` (e.g., `"text"`, `"number"`, `"date"`).
+         * Validated against `FieldTemplateCreateSchema`.
+         *
+         * @param attrs - Field template attributes. `name` is required.
+         * @param options - Optional request options.
+         * @returns The newly created field template record.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const template = await client.extraction.fieldTemplates.create({
+         *   name: 'Patient DOB',
+         *   category: 'demographics',
+         *   field_type: 'date',
+         * });
+         * console.log(template.id);
+         * ```
+         */
+        create: (attrs: CreateFieldTemplateAttributes, options?: RequestOptions) => Promise<FieldTemplateRecord>;
+        /**
+         * Delete a field template.
+         *
+         * @param id - The UUID of the field template to delete.
+         * @param options - Optional request options.
+         * @returns `true` on successful deletion.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.extraction.fieldTemplates.delete('ft_abc123');
+         * ```
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+    };
+    /**
+     * Field Mappings — confirm AI-suggested column-to-field mappings.
+     *
+     * When uploading structured documents (CSV, Excel), the platform infers
+     * how source columns map to agent schema fields. Field mappings record
+     * the confirmed (or corrected) mapping for a specific document.
+     */
+    fieldMappings: {
+        /**
+         * Retrieve the current field mapping for a document within a workspace.
+         *
+         * Returns the mapping object describing how source columns in the document
+         * correspond to agent schema fields, along with the current confirmation status.
+         *
+         * @param workspaceId - The UUID of the workspace.
+         * @param documentId - The UUID of the extraction document.
+         * @param options - Optional request options.
+         * @returns The field mapping record for the document.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const mapping = await client.extraction.fieldMappings.get('ws_abc123', 'doc_abc123');
+         * console.log(mapping.mappings);
+         * ```
+         */
+        get: (workspaceId: string, documentId: string, options?: RequestOptions) => Promise<FieldMappingRecord>;
+        /**
+         * Confirm or update the field mapping for a document.
+         *
+         * Saves the mapping between source document columns and agent schema fields.
+         * Must include `confirmed: true` to mark the mapping as approved and trigger
+         * extraction. Optionally include `mappings` to override the AI-suggested mapping.
+         * Validated against `FieldMappingCreateSchema`.
+         *
+         * @param workspaceId - The UUID of the workspace.
+         * @param documentId - The UUID of the extraction document.
+         * @param attrs - Mapping confirmation: `confirmed` (required) and optional `mappings` array.
+         * @param options - Optional request options.
+         * @returns The saved field mapping confirmation record.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const mapping = await client.extraction.fieldMappings.create(
+         *   'ws_abc123',
+         *   'doc_abc123',
+         *   {
+         *     confirmed: true,
+         *     mappings: [
+         *       { source_column: 'Patient Name', target_field: 'patient_name' },
+         *       { source_column: 'DOB',          target_field: 'date_of_birth' },
+         *     ],
+         *   },
+         * );
+         * ```
+         */
+        create: (workspaceId: string, documentId: string, attrs: CreateFieldMappingAttributes, options?: RequestOptions) => Promise<FieldMappingRecord>;
+    };
+    /** Extraction agents — list and predict best extraction agents for documents. */
+    extractionAgents: {
+        /**
+         * Lists all available extraction agents (system agents tagged with
+         * "extraction" category).
+         *
+         * @param options - Optional request options (abort signal, custom headers).
+         * @returns An array of extraction agent objects.
+         *
+         * @example
+         * ```typescript
+         * const agents = await client.extraction.extractionAgents.list();
+         * ```
+         */
+        list: (options?: RequestOptions) => Promise<ExtractionAgent[]>;
+        /**
+         * Retrieves a single extraction agent by its unique identifier.
+         *
+         * @param id - The UUID of the extraction agent.
+         * @param options - Optional request options (abort signal, custom headers).
+         * @returns The matching extraction agent object.
+         *
+         * @example
+         * ```typescript
+         * const agent = await client.extraction.extractionAgents.get('agent-uuid');
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<ExtractionAgent>;
+        /**
+         * Predicts the best extraction agent for a given document based on its
+         * name, description, or file content.
+         *
+         * @param attributes - Prediction input (name, description, file_content, document_id).
+         * @param options - Optional request options (abort signal, custom headers).
+         * @returns A prediction result with recommended agents.
+         *
+         * @example
+         * ```typescript
+         * const prediction = await client.extraction.extractionAgents.predict({
+         *   name: 'invoice.pdf',
+         *   file_content: 'Invoice #12345...',
+         * });
+         * ```
+         */
+        predict: (attributes: {
+            name?: string;
+            description?: string;
+            file_content?: string;
+            document_id?: string;
+            [key: string]: unknown;
+        }, options?: RequestOptions) => Promise<unknown>;
+    };
+    /** Training analytics — workspace-level extraction training metrics. */
+    trainingAnalytics: {
+        /**
+         * Retrieves training analytics for a specific workspace, including
+         * accuracy trends, correction counts, and low-confidence documents.
+         *
+         * @param workspaceId - The UUID of the workspace.
+         * @param options - Optional request options (abort signal, custom headers).
+         * @returns The training analytics object for the workspace.
+         *
+         * @example
+         * ```typescript
+         * const analytics = await client.extraction.trainingAnalytics.forWorkspace('ws-uuid');
+         * console.log(analytics.avg_confidence, analytics.total_examples);
+         * ```
+         */
+        forWorkspace: (workspaceId: string, options?: RequestOptions) => Promise<TrainingAnalytics>;
+    };
+};
+//# sourceMappingURL=extraction.d.ts.map