@llamaindex/llama-cloud 2.3.0 → 2.4.0

package/src/resources/classify.ts

@@ -5,6 +5,7 @@ import { APIPromise } from '../core/api-promise';
 import { PagePromise, PaginatedCursor, type PaginatedCursorParams } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
+import { pollUntilComplete, PollingOptions, DEFAULT_TIMEOUT } from '../core/polling';
 
 export class Classify extends APIResource {
   /**
@@ -20,6 +21,11 @@ export class Classify extends APIResource {
    *
    * The job runs asynchronously. Poll `GET /classify/{job_id}` to check status and
    * retrieve results.
+   *
+   * @example
+   * ```ts
+   * const classify = await client.classify.create();
+   * ```
    */
   create(params: ClassifyCreateParams, options?: RequestOptions): APIPromise<ClassifyCreateResponse> {
     const { organization_id, project_id, ...body } = params;
@@ -35,6 +41,14 @@ export class Classify extends APIResource {
    *
    * Filter by `status`, `configuration_id`, specific `job_ids`, or creation date
    * range.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const classifyListResponse of client.classify.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: ClassifyListParams | null | undefined = {},
@@ -51,6 +65,11 @@ export class Classify extends APIResource {
    *
    * Returns the job status, configuration, and classify result when complete. The
    * result includes the matched document type, confidence score, and reasoning.
+   *
+   * @example
+   * ```ts
+   * const classify = await client.classify.get('job_id');
+   * ```
    */
   get(
     jobID: string,
@@ -59,6 +78,117 @@ export class Classify extends APIResource {
   ): APIPromise<ClassifyGetResponse> {
     return this._client.get(path`/api/v2/classify/${jobID}`, { query, ...options });
   }
+
+  /**
+   * Wait for a classify job to complete by polling until it reaches a terminal state.
+   *
+   * @param jobID - The ID of the classify job to wait for
+   * @param query - Optional query parameters (organization_id, project_id)
+   * @param options - Polling configuration and request options
+   * @returns The completed classify job
+   * @throws {PollingTimeoutError} If the job doesn't complete within the timeout period
+   * @throws {PollingError} If the job fails
+   *
+   * @example
+   * ```typescript
+   * const job = await client.classify.create({
+   *   file_input: 'dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+   *   configuration_id: 'cfg-...',
+   * });
+   *
+   * const completed = await client.classify.waitForCompletion(job.id, undefined, { verbose: true });
+   * console.log(completed.result);
+   * ```
+   */
+  async waitForCompletion(
+    jobID: string,
+    query?: ClassifyGetParams,
+    options?: PollingOptions & RequestOptions,
+  ): Promise<ClassifyGetResponse> {
+    const { pollingInterval, maxInterval, timeout, backoff, verbose, ...requestOptions } = options || {};
+
+    const getStatus = async (): Promise<ClassifyGetResponse> => {
+      return await this.get(jobID, query, requestOptions);
+    };
+
+    const isComplete = (job: ClassifyGetResponse): boolean => {
+      return job.status === 'COMPLETED';
+    };
+
+    const isError = (job: ClassifyGetResponse): boolean => {
+      return job.status === 'FAILED';
+    };
+
+    const getErrorMessage = (job: ClassifyGetResponse): string => {
+      const errorParts = [`Job ${jobID} failed with status: ${job.status}`];
+      if (job.error_message) {
+        errorParts.push(`Error: ${job.error_message}`);
+      }
+      return errorParts.join(' | ');
+    };
+
+    return await pollUntilComplete(getStatus, isComplete, isError, getErrorMessage, {
+      pollingInterval,
+      maxInterval,
+      timeout: timeout || DEFAULT_TIMEOUT,
+      backoff,
+      verbose,
+    });
+  }
+
+  /**
+   * Create a classify job, wait for it to complete, and return the result.
+   *
+   * This is a convenience method that combines create() and waitForCompletion()
+   * into a single call for the most common end-to-end workflow.
+   *
+   * @param params - Classify job creation parameters
+   * @param options - Polling configuration and request options
+   * @returns The completed classify job with result populated
+   * @throws {PollingTimeoutError} If the job doesn't complete within the timeout period
+   * @throws {PollingError} If the job fails
+   *
+   * @example
+   * ```typescript
+   * import { LlamaCloud } from 'llama-cloud';
+   *
+   * const client = new LlamaCloud({ apiKey: '...' });
+   *
+   * const result = await client.classify.run({
+   *   file_input: 'dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+   *   configuration: {
+   *     rules: [{ type: 'invoice', description: 'contains invoice number' }],
+   *   },
+   * }, { verbose: true });
+   *
+   * console.log(result.result);
+   * ```
+   */
+  async run(
+    params: ClassifyCreateParams,
+    options?: PollingOptions & RequestOptions,
+  ): Promise<ClassifyGetResponse> {
+    const { pollingInterval, maxInterval, timeout, backoff, verbose, ...requestOptions } = options || {};
+
+    const job = await this.create(params, requestOptions);
+
+    const getQuery: ClassifyGetParams = {};
+    if (params.organization_id !== undefined) {
+      getQuery.organization_id = params.organization_id;
+    }
+    if (params.project_id !== undefined) {
+      getQuery.project_id = params.project_id;
+    }
+
+    return await this.waitForCompletion(job.id, getQuery, {
+      pollingInterval,
+      maxInterval,
+      timeout: timeout || DEFAULT_TIMEOUT,
+      backoff,
+      verbose,
+      ...requestOptions,
+    });
+  }
 }
 
 export type ClassifyListResponsesPaginatedCursor = PaginatedCursor<ClassifyListResponse>;

package/src/resources/configurations.ts

@@ -164,9 +164,70 @@ export interface ConfigurationCreate {
     | ExtractV2Parameters
     | ClassifyV2Parameters
     | ParseV2Parameters
+    | ConfigurationCreate.SpreadsheetV1Parameters
     | UntypedParameters;
 }
 
+export namespace ConfigurationCreate {
+  /**
+   * Typed parameters for a _spreadsheet v1_ product configuration.
+   */
+  export interface SpreadsheetV1Parameters {
+    /**
+     * Product type.
+     */
+    product_type: 'spreadsheet_v1';
+
+    /**
+     * A1 notation of the range to extract a single region from. If None, the entire
+     * sheet is used.
+     */
+    extraction_range?: string | null;
+
+    /**
+     * Return a flattened dataframe when a detected table is recognized as
+     * hierarchical.
+     */
+    flatten_hierarchical_tables?: boolean;
+
+    /**
+     * Whether to generate additional metadata (title, description) for each extracted
+     * region.
+     */
+    generate_additional_metadata?: boolean;
+
+    /**
+     * Whether to include hidden cells when extracting regions from the spreadsheet.
+     */
+    include_hidden_cells?: boolean;
+
+    /**
+     * The names of the sheets to extract regions from. If empty, all sheets will be
+     * processed.
+     */
+    sheet_names?: Array<string> | null;
+
+    /**
+     * Optional specialization mode for domain-specific extraction. Supported values:
+     * 'financial-standard', 'financial-enhanced', 'financial-precise'. Default None
+     * uses the general-purpose pipeline.
+     */
+    specialization?: string | null;
+
+    /**
+     * Influences how likely similar-looking regions are merged into a single table.
+     * Useful for spreadsheets that either have sparse tables (strong merging) or many
+     * distinct tables close together (weak merging).
+     */
+    table_merge_sensitivity?: 'strong' | 'weak';
+
+    /**
+     * Enables experimental processing. Accuracy may be impacted.
+     */
+    use_experimental_processing?: boolean;
+  }
+}
+
 /**
  * Response schema for a single product configuration.
  */
@@ -189,12 +250,13 @@ export interface ConfigurationResponse {
     | ExtractV2Parameters
     | ClassifyV2Parameters
     | ParseV2Parameters
+    | ConfigurationResponse.SpreadsheetV1Parameters
     | UntypedParameters;
 
   /**
    * Product type.
    */
-  product_type: 'split_v1' | 'extract_v2' | 'classify_v2' | 'parse_v2' | 'unknown';
+  product_type: 'split_v1' | 'extract_v2' | 'classify_v2' | 'parse_v2' | 'spreadsheet_v1' | 'unknown';
 
   /**
    * Version identifier (datetime string).
@@ -212,6 +274,66 @@ export interface ConfigurationResponse {
   updated_at?: string | null;
 }
 
+export namespace ConfigurationResponse {
+  /**
+   * Typed parameters for a _spreadsheet v1_ product configuration.
+   */
+  export interface SpreadsheetV1Parameters {
+    /**
+     * Product type.
+     */
+    product_type: 'spreadsheet_v1';
+
+    /**
+     * A1 notation of the range to extract a single region from. If None, the entire
+     * sheet is used.
+     */
+    extraction_range?: string | null;
+
+    /**
+     * Return a flattened dataframe when a detected table is recognized as
+     * hierarchical.
+     */
+    flatten_hierarchical_tables?: boolean;
+
+    /**
+     * Whether to generate additional metadata (title, description) for each extracted
+     * region.
+     */
+    generate_additional_metadata?: boolean;
+
+    /**
+     * Whether to include hidden cells when extracting regions from the spreadsheet.
+     */
+    include_hidden_cells?: boolean;
+
+    /**
+     * The names of the sheets to extract regions from. If empty, all sheets will be
+     * processed.
+     */
+    sheet_names?: Array<string> | null;
+
+    /**
+     * Optional specialization mode for domain-specific extraction. Supported values:
+     * 'financial-standard', 'financial-enhanced', 'financial-precise'. Default None
+     * uses the general-purpose pipeline.
+     */
+    specialization?: string | null;
+
+    /**
+     * Influences how likely similar-looking regions are merged into a single table.
+     * Useful for spreadsheets that either have sparse tables (strong merging) or many
+     * distinct tables close together (weak merging).
+     */
+    table_merge_sensitivity?: 'strong' | 'weak';
+
+    /**
+     * Enables experimental processing. Accuracy may be impacted.
+     */
+    use_experimental_processing?: boolean;
+  }
+}
+
 /**
  * Typed parameters for an _extract v2_ product configuration.
  */
@@ -250,11 +372,6 @@ export interface ExtractV2Parameters {
    */
   extraction_target?: 'per_doc' | 'per_page' | 'per_table_row';
 
-  /**
-   * ISO 639-1 language code for the document
-   */
-  lang?: string;
-
   /**
    * Maximum number of pages to process. Omit for no limit.
    */
@@ -267,7 +384,8 @@ export interface ExtractV2Parameters {
   parse_config_id?: string | null;
 
   /**
-   * Parse tier to use before extraction (fast, cost_effective, or agentic)
+   * Parse tier to use before extraction. Defaults to the extract tier if not
+   * specified.
    */
   parse_tier?: string | null;
 
@@ -348,6 +466,9 @@ export interface ParseV2Parameters {
     | '2026-03-27'
     | '2026-03-30'
     | '2026-03-31'
+    | '2026-04-02'
+    | '2026-04-06'
+    | '2026-04-09'
     | 'latest'
     | (string & {});
 
@@ -1125,6 +1246,9 @@ export namespace ParseV2Parameters {
           | '2026-03-27'
           | '2026-03-30'
           | '2026-03-31'
+          | '2026-04-02'
+          | '2026-04-06'
+          | '2026-04-09'
           | 'latest'
           | (string & {})
           | null;
@@ -1350,6 +1474,7 @@ export interface ConfigurationCreateParams {
     | ExtractV2Parameters
     | ClassifyV2Parameters
     | ParseV2Parameters
+    | ConfigurationCreateParams.SpreadsheetV1Parameters
     | UntypedParameters;
 
   /**
@@ -1363,6 +1488,66 @@ export interface ConfigurationCreateParams {
   project_id?: string | null;
 }
 
+export namespace ConfigurationCreateParams {
+  /**
+   * Typed parameters for a _spreadsheet v1_ product configuration.
+   */
+  export interface SpreadsheetV1Parameters {
+    /**
+     * Product type.
+     */
+    product_type: 'spreadsheet_v1';
+
+    /**
+     * A1 notation of the range to extract a single region from. If None, the entire
+     * sheet is used.
+     */
+    extraction_range?: string | null;
+
+    /**
+     * Return a flattened dataframe when a detected table is recognized as
+     * hierarchical.
+     */
+    flatten_hierarchical_tables?: boolean;
+
+    /**
+     * Whether to generate additional metadata (title, description) for each extracted
+     * region.
+     */
+    generate_additional_metadata?: boolean;
+
+    /**
+     * Whether to include hidden cells when extracting regions from the spreadsheet.
+     */
+    include_hidden_cells?: boolean;
+
+    /**
+     * The names of the sheets to extract regions from. If empty, all sheets will be
+     * processed.
+     */
+    sheet_names?: Array<string> | null;
+
+    /**
+     * Optional specialization mode for domain-specific extraction. Supported values:
+     * 'financial-standard', 'financial-enhanced', 'financial-precise'. Default None
+     * uses the general-purpose pipeline.
+     */
+    specialization?: string | null;
+
+    /**
+     * Influences how likely similar-looking regions are merged into a single table.
+     * Useful for spreadsheets that either have sparse tables (strong merging) or many
+     * distinct tables close together (weak merging).
+     */
+    table_merge_sensitivity?: 'strong' | 'weak';
+
+    /**
+     * Enables experimental processing. Accuracy may be impacted.
+     */
+    use_experimental_processing?: boolean;
+  }
+}
+
 export interface ConfigurationRetrieveParams {
   organization_id?: string | null;
 
@@ -1393,10 +1578,71 @@ export interface ConfigurationUpdateParams {
     | ExtractV2Parameters
     | ClassifyV2Parameters
     | ParseV2Parameters
+    | ConfigurationUpdateParams.SpreadsheetV1Parameters
     | UntypedParameters
     | null;
 }
 
+export namespace ConfigurationUpdateParams {
+  /**
+   * Typed parameters for a _spreadsheet v1_ product configuration.
+   */
+  export interface SpreadsheetV1Parameters {
+    /**
+     * Product type.
+     */
+    product_type: 'spreadsheet_v1';
+
+    /**
+     * A1 notation of the range to extract a single region from. If None, the entire
+     * sheet is used.
+     */
+    extraction_range?: string | null;
+
+    /**
+     * Return a flattened dataframe when a detected table is recognized as
+     * hierarchical.
+     */
+    flatten_hierarchical_tables?: boolean;
+
+    /**
+     * Whether to generate additional metadata (title, description) for each extracted
+     * region.
+     */
+    generate_additional_metadata?: boolean;
+
+    /**
+     * Whether to include hidden cells when extracting regions from the spreadsheet.
+     */
+    include_hidden_cells?: boolean;
+
+    /**
+     * The names of the sheets to extract regions from. If empty, all sheets will be
+     * processed.
+     */
+    sheet_names?: Array<string> | null;
+
+    /**
+     * Optional specialization mode for domain-specific extraction. Supported values:
+     * 'financial-standard', 'financial-enhanced', 'financial-precise'. Default None
+     * uses the general-purpose pipeline.
+     */
+    specialization?: string | null;
+
+    /**
+     * Influences how likely similar-looking regions are merged into a single table.
+     * Useful for spreadsheets that either have sparse tables (strong merging) or many
+     * distinct tables close together (weak merging).
+     */
+    table_merge_sensitivity?: 'strong' | 'weak';
+
+    /**
+     * Enables experimental processing. Accuracy may be impacted.
+     */
+    use_experimental_processing?: boolean;
+  }
+}
+
 export interface ConfigurationListParams extends PaginatedCursorParams {
   /**
    * Return only the latest version per configuration name.
@@ -1413,7 +1659,9 @@ export interface ConfigurationListParams extends PaginatedCursorParams {
   /**
    * Filter by one or more product types. Repeat the parameter for multiple values.
    */
-  product_type?: Array<'split_v1' | 'extract_v2' | 'classify_v2' | 'parse_v2' | 'unknown'> | null;
+  product_type?: Array<
+    'split_v1' | 'extract_v2' | 'classify_v2' | 'parse_v2' | 'spreadsheet_v1' | 'unknown'
+  > | null;
 
   project_id?: string | null;
 }

package/src/resources/extract.ts

@@ -133,7 +133,20 @@ export class Extract extends APIResource {
    * ```ts
    * const extractV2SchemaValidateResponse =
    *   await client.extract.validateSchema({
-   *     data_schema: { foo: { foo: 'bar' } },
+   *     data_schema: {
+   *       properties: {
+   *         vendor_name: 'bar',
+   *         invoice_number: 'bar',
+   *         total_amount: 'bar',
+   *         line_items: 'bar',
+   *       },
+   *       required: [
+   *         'vendor_name',
+   *         'invoice_number',
+   *         'total_amount',
+   *       ],
+   *       type: 'object',
+   *     },
    *   });
    * ```
    */
@@ -287,11 +300,6 @@ export interface ExtractConfiguration {
    */
   extraction_target?: 'per_doc' | 'per_page' | 'per_table_row';
 
-  /**
-   * ISO 639-1 language code for the document
-   */
-  lang?: string;
-
   /**
    * Maximum number of pages to process. Omit for no limit.
    */
@@ -304,7 +312,8 @@ export interface ExtractConfiguration {
   parse_config_id?: string | null;
 
   /**
-   * Parse tier to use before extraction (fast, cost_effective, or agentic)
+   * Parse tier to use before extraction. Defaults to the extract tier if not
+   * specified.
    */
   parse_tier?: string | null;
 

package/src/resources/index.ts

@@ -172,6 +172,7 @@ export {
   type RetrieverCreateParams,
   type RetrieverUpdateParams,
   type RetrieverListParams,
+  type RetrieverDeleteParams,
   type RetrieverGetParams,
   type RetrieverSearchParams,
   type RetrieverUpsertParams,

package/src/resources/parsing.ts

@@ -1093,7 +1093,8 @@ export namespace ParsingGetResponse {
       presigned_url?: string | null;
 
       /**
-       * Size of the image file in bytes
+       * @deprecated Deprecated: always returns None. Will be removed in a future
+       * release.
        */
       size_bytes?: number | null;
     }
@@ -1310,7 +1311,7 @@ export namespace ParsingGetResponse {
    */
   export interface ResultContentMetadata {
     /**
-     * Size of the result file in S3 (bytes)
+     * Size of the result file in bytes
      */
     size_bytes: number;
 
@@ -1398,6 +1399,9 @@ export interface ParsingCreateParams {
     | '2026-03-27'
     | '2026-03-30'
     | '2026-03-31'
+    | '2026-04-02'
+    | '2026-04-06'
+    | '2026-04-09'
     | 'latest'
     | (string & {});
 
@@ -2203,6 +2207,9 @@ export namespace ParsingCreateParams {
           | '2026-03-27'
           | '2026-03-30'
           | '2026-03-31'
+          | '2026-04-02'
+          | '2026-04-06'
+          | '2026-04-09'
           | 'latest'
           | (string & {})
           | null;

package/src/resources/pipelines/documents.ts

@@ -155,9 +155,6 @@ export interface CloudDocumentCreate {
 
 /**
  * Provided for backward compatibility.
- *
- * Note: we keep the field with the typo "seperator" to maintain backward
- * compatibility for serialized objects.
  */
 export interface TextNode {
   class_name?: string;

package/src/resources/pipelines/pipelines.ts

@@ -653,10 +653,6 @@ export interface HuggingFaceInferenceAPIEmbeddingConfig {
   type?: 'HUGGINGFACE_API_EMBEDDING';
 }
 
-/**
- * Settings that can be configured for how to use LlamaParse to parse files within
- * a LlamaCloud pipeline.
- */
 export interface LlamaParseParameters {
   adaptive_long_table?: boolean | null;
 
@@ -1789,9 +1785,6 @@ export namespace PipelineRetrieveResponse {
   export interface RetrievalNode {
     /**
      * Provided for backward compatibility.
-     *
-     * Note: we keep the field with the typo "seperator" to maintain backward
-     * compatibility for serialized objects.
      */
     node: DocumentsAPI.TextNode;
 

package/src/resources/retrievers/index.ts

@@ -12,6 +12,7 @@ export {
   type RetrieverCreateParams,
   type RetrieverUpdateParams,
   type RetrieverListParams,
+  type RetrieverDeleteParams,
   type RetrieverGetParams,
   type RetrieverSearchParams,
   type RetrieverUpsertParams,