@llamaindex/llama-cloud 2.4.1 → 2.8.0

package/resources/beta/retrieval.d.mts

@@ -0,0 +1,368 @@
+import { APIResource } from "../../core/resource.mjs";
+import { APIPromise } from "../../core/api-promise.mjs";
+import { PagePromise, PaginatedCursorPost, type PaginatedCursorPostParams } from "../../core/pagination.mjs";
+import { RequestOptions } from "../../internal/request-options.mjs";
+export declare class Retrieval extends APIResource {
+    /**
+     * Retrieve relevant chunks via hybrid search (vector + full-text), with filtering
+     * on built-in or user-defined metadata.
+     *
+     * @example
+     * ```ts
+     * const retrieval = await client.beta.retrieval.retrieve({
+     *   index_id: 'idx-abc123',
+     *   query: 'What are the key findings?',
+     * });
+     * ```
+     */
+    retrieve(params: RetrievalRetrieveParams, options?: RequestOptions): APIPromise<RetrievalRetrieveResponse>;
+    /**
+     * Search for files by name.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const retrievalFindResponse of client.beta.retrieval.find(
+     *   { index_id: 'idx-abc123' },
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    find(params: RetrievalFindParams, options?: RequestOptions): PagePromise<RetrievalFindResponsesPaginatedCursorPost, RetrievalFindResponse>;
+    /**
+     * Grep within a file's parsed content using a regex pattern.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const retrievalGrepResponse of client.beta.retrieval.grep(
+     *   {
+     *     file_id: 'file_id',
+     *     index_id: 'idx-abc123',
+     *     pattern: 'revenue|profit',
+     *   },
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    grep(params: RetrievalGrepParams, options?: RequestOptions): PagePromise<RetrievalGrepResponsesPaginatedCursorPost, RetrievalGrepResponse>;
+    /**
+     * Read the parsed text content of a specific file.
+     *
+     * @example
+     * ```ts
+     * const response = await client.beta.retrieval.read({
+     *   file_id: 'file_id',
+     *   index_id: 'idx-abc123',
+     * });
+     * ```
+     */
+    read(params: RetrievalReadParams, options?: RequestOptions): APIPromise<RetrievalReadResponse>;
+}
+export type RetrievalFindResponsesPaginatedCursorPost = PaginatedCursorPost<RetrievalFindResponse>;
+export type RetrievalGrepResponsesPaginatedCursorPost = PaginatedCursorPost<RetrievalGrepResponse>;
+/**
+ * Response containing retrieval results.
+ */
+export interface RetrievalRetrieveResponse {
+    /**
+     * Ordered list of retrieved chunks.
+     */
+    results: Array<RetrievalRetrieveResponse.Result>;
+}
+export declare namespace RetrievalRetrieveResponse {
+    /**
+     * A single retrieval result.
+     */
+    interface Result {
+        /**
+         * Text content of the retrieved chunk.
+         */
+        content: string;
+        /**
+         * User-defined metadata associated with the chunk.
+         */
+        metadata?: {
+            [key: string]: string | number | boolean | Array<string> | null;
+        } | null;
+        /**
+         * Relevance score from the reranker, if reranking was applied.
+         */
+        rerank_score?: number | null;
+        /**
+         * Hybrid search relevance score.
+         */
+        score?: number | null;
+        /**
+         * Built-in fields stored for every exported chunk.
+         */
+        static_fields?: Result.StaticFields;
+    }
+    namespace Result {
+        /**
+         * Built-in fields stored for every exported chunk.
+         */
+        interface StaticFields {
+            /**
+             * Attachments associated with the chunk
+             */
+            attachments?: Array<StaticFields.Attachment>;
+            /**
+             * End character offset of the chunk.
+             */
+            chunk_end_char?: number | null;
+            /**
+             * Index of the chunk within the file.
+             */
+            chunk_index?: number | null;
+            /**
+             * Start character offset of the chunk.
+             */
+            chunk_start_char?: number | null;
+            /**
+             * Token count of the chunk.
+             */
+            chunk_token_count?: number | null;
+            /**
+             * Last page number covered by this chunk.
+             */
+            page_range_end?: number | null;
+            /**
+             * First page number covered by this chunk.
+             */
+            page_range_start?: number | null;
+            /**
+             * ID of the parsed file.
+             */
+            parsed_directory_file_id?: string | null;
+        }
+        namespace StaticFields {
+            /**
+             * Reference to a file attachment, retrievable via
+             * `GET /api/v1/beta/attachments/{attachment_name}?source_id=...`.
+             */
+            interface Attachment {
+                /**
+                 * Attachment-relative path, e.g. 'screenshots/page_7.jpg'.
+                 */
+                attachment_name: string;
+                /**
+                 * File ID to pass as source_id when fetching the attachment.
+                 */
+                source_id: string;
+                /**
+                 * Attachment kind, e.g. 'screenshot', 'items'.
+                 */
+                type: string;
+            }
+        }
+    }
+}
+/**
+ * A file returned by find.
+ */
+export interface RetrievalFindResponse {
+    /**
+     * ID of the file.
+     */
+    file_id: string;
+    /**
+     * Display name of the file.
+     */
+    file_name: string;
+}
+/**
+ * A single grep match within a file.
+ */
+export interface RetrievalGrepResponse {
+    /**
+     * Matched text content.
+     */
+    content: string;
+    /**
+     * End character offset of the match.
+     */
+    end_char: number;
+    /**
+     * Start character offset of the match.
+     */
+    start_char: number;
+}
+/**
+ * File read result.
+ */
+export interface RetrievalReadResponse {
+    /**
+     * Parsed text content of the file.
+     */
+    content: string;
+}
+export interface RetrievalRetrieveParams {
+    /**
+     * Body param: ID of the index to retrieve against.
+     */
+    index_id: string;
+    /**
+     * Body param: Natural-language query to retrieve relevant chunks.
+     */
+    query: string;
+    /**
+     * Query param
+     */
+    organization_id?: string | null;
+    /**
+     * Query param
+     */
+    project_id?: string | null;
+    /**
+     * Body param: Filters on user-defined metadata fields.
+     */
+    custom_filters?: {
+        [key: string]: RetrievalRetrieveParams.FilterTypeUnionStrIntBoolFloat | Array<RetrievalRetrieveParams.UnionMember1> | null;
+    } | null;
+    /**
+     * Body param: Weight of the full-text search pipeline (0-1).
+     */
+    full_text_pipeline_weight?: number | null;
+    /**
+     * Body param: Number of candidates for approximate nearest neighbor search.
+     */
+    num_candidates?: number | null;
+    /**
+     * Body param: Reranking configuration applied after hybrid search. Enabled by
+     * default.
+     */
+    rerank?: RetrievalRetrieveParams.Rerank;
+    /**
+     * Body param: Minimum score threshold for returned results.
+     */
+    score_threshold?: number | null;
+    /**
+     * Body param: Filters on built-in document fields (page range, chunk index, etc.).
+     */
+    static_filters?: RetrievalRetrieveParams.StaticFilters | null;
+    /**
+     * Body param: Maximum number of results to return.
+     */
+    top_k?: number | null;
+    /**
+     * Body param: Weight of the vector search pipeline (0-1).
+     */
+    vector_pipeline_weight?: number | null;
+}
+export declare namespace RetrievalRetrieveParams {
+    interface FilterTypeUnionStrIntBoolFloat {
+        operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin';
+        value: string | boolean | number | Array<string | boolean | number>;
+    }
+    interface UnionMember1 {
+        operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin';
+        value: number | Array<number>;
+    }
+    /**
+     * Reranking configuration applied after hybrid search. Enabled by default.
+     */
+    interface Rerank {
+        /**
+         * Set to false to disable reranking.
+         */
+        enabled?: boolean;
+        /**
+         * Number of results to return after reranking.
+         */
+        top_n?: number | null;
+    }
+    /**
+     * Filters on built-in document fields (page range, chunk index, etc.).
+     */
+    interface StaticFilters {
+        parsed_directory_file_id?: StaticFilters.ParsedDirectoryFileID | null;
+    }
+    namespace StaticFilters {
+        interface ParsedDirectoryFileID {
+            operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin';
+            value: string | Array<string>;
+        }
+    }
+}
+export interface RetrievalFindParams extends PaginatedCursorPostParams {
+    /**
+     * Body param: ID of the index to search within.
+     */
+    index_id: string;
+    /**
+     * Query param
+     */
+    organization_id?: string | null;
+    /**
+     * Query param
+     */
+    project_id?: string | null;
+    /**
+     * Body param: Exact file name to match.
+     */
+    file_name?: string | null;
+    /**
+     * Body param: Substring match on file name (case-insensitive).
+     */
+    file_name_contains?: string | null;
+}
+export interface RetrievalGrepParams extends PaginatedCursorPostParams {
+    /**
+     * Body param: ID of the file to grep.
+     */
+    file_id: string;
+    /**
+     * Body param: ID of the index the file belongs to.
+     */
+    index_id: string;
+    /**
+     * Body param: Regex pattern to search for.
+     */
+    pattern: string;
+    /**
+     * Query param
+     */
+    organization_id?: string | null;
+    /**
+     * Query param
+     */
+    project_id?: string | null;
+    /**
+     * Body param: Number of characters of context to include before and after the
+     * matched pattern in the content field of the response
+     */
+    context_chars?: number | null;
+}
+export interface RetrievalReadParams {
+    /**
+     * Body param: ID of the file to read.
+     */
+    file_id: string;
+    /**
+     * Body param: ID of the index the file belongs to.
+     */
+    index_id: string;
+    /**
+     * Query param
+     */
+    organization_id?: string | null;
+    /**
+     * Query param
+     */
+    project_id?: string | null;
+    /**
+     * Body param: Maximum number of characters to read from the offset.
+     */
+    max_length?: number | null;
+    /**
+     * Body param: Starting character offset.
+     */
+    offset?: number;
+}
+export declare namespace Retrieval {
+    export { type RetrievalRetrieveResponse as RetrievalRetrieveResponse, type RetrievalFindResponse as RetrievalFindResponse, type RetrievalGrepResponse as RetrievalGrepResponse, type RetrievalReadResponse as RetrievalReadResponse, type RetrievalFindResponsesPaginatedCursorPost as RetrievalFindResponsesPaginatedCursorPost, type RetrievalGrepResponsesPaginatedCursorPost as RetrievalGrepResponsesPaginatedCursorPost, type RetrievalRetrieveParams as RetrievalRetrieveParams, type RetrievalFindParams as RetrievalFindParams, type RetrievalGrepParams as RetrievalGrepParams, type RetrievalReadParams as RetrievalReadParams, };
+}
+//# sourceMappingURL=retrieval.d.mts.map

package/resources/beta/retrieval.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.mts","sourceRoot":"","sources":["../../src/resources/beta/retrieval.ts"],"names":[],"mappings":"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"}