@squidcloud/client 1.0.391 → 1.0.392

package/dist/internal-common/src/public-types/ai-agent.public-types.d.ts

@@ -1,7 +1,8 @@
-import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiEmbeddingsModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, GeminiChatModelName, GrokChatModelName, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiReasoningChatModelName } from './ai-common.public-types';
+import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiEmbeddingsModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, GeminiChatModelName, GrokChatModelName, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat } from './ai-common.public-types';
 import { AiContextMetadata, AiContextMetadataFilter, AiKnowledgeBaseContextType, AiRagType } from './ai-knowledge-base.public-types';
 import { AiFunctionId, AiFunctionIdWithContext, UserAiChatModelName } from './backend.public-types';
 import { AiAgentId, AiContextId, AiKnowledgeBaseId, IntegrationId } from './communication.public-types';
+import { DocumentExtractionMethod } from './extraction.public-types';
 import { IntegrationType } from './integration.public-types';
 import { JobId } from './job.public-types';
 import { SecretKey } from './secret.public-types';
@@ -151,17 +152,27 @@ export type AiAgentResponseFormat = 'text' | 'json_object';
 /**
  * @category AI
  */
-export type AiFileUrlType = 'image';
+export type AiFileUrlType = 'image' | 'document';
 /**
  * Represents a URL reference to an AI-processed file, such as an image.
  * @category AI
  */
 export interface AiFileUrl {
+    /** The unique identifier for the file URL for the current request. */
+    id: string;
     /** The type of file referenced by the URL (e.g., 'image'). */
     type: AiFileUrlType;
+    /** The purpose of the file, indicating how it will be used in AI processing. */
+    purpose: AiFilePurpose;
     /** The URL pointing to the file. */
     url: string;
+    /** An optional description of the file's content or purpose - sent to the AI. */
+    description?: string;
+    /** The file name, can be used in the prompt to reference the file. */
+    fileName?: string;
 }
+/** The purpose of the AI file, used to determine how the file should be processed or utilized. */
+export type AiFilePurpose = 'context' | 'tools';
 /**
  * Metadata for an AI agent connected to an integration.
  * @category AI
@@ -247,20 +258,16 @@ export interface AiAgentMemoryOptions {
  * @category AI
  */
 export interface BaseAiChatOptions {
-    /** The maximum number of tokens to use when making the request to the AI model. Defaults to the max tokens the model can accept. */
-    maxTokens?: number;
     /**
-     * A unique chat ID, if the same chat ID is used again and history is not disabled, it will continue the conversation.
-     * @deprecated use 'memoryOptions` instead.
+     * The maximum number of input tokens that Squid can use when making the request to the AI model.
+     * Defaults to the max tokens the model can accept.
      */
-    chatId?: string;
+    maxTokens?: number;
     /**
-     * Disables history for the agent, so each question is answered as
-     * if it were the first question in the conversation.
-     * Default to false.
-     * @deprecated use 'memoryOptions` instead.
+     * The maximum number of tokens the model should output.
+     * Passed directly to the AI model. Can be used to control the output verbosity.
      */
-    disableHistory?: boolean;
+    maxOutputTokens?: number;
     /** The context ID to use for the request. If not provided, the agent's default context will be used. */
     memoryOptions?: AiAgentMemoryOptions;
     /** Whether to disable the whole context for the request. Default to false. */
@@ -311,6 +318,22 @@ export interface BaseAiChatOptions {
      * connected agents, connected integrations, or functions.
      */
     executionPlanOptions?: AiAgentExecutionPlanOptions;
+    /** An array of file URLs to include in the chat context. */
+    fileUrls?: Array<AiFileUrl>;
+    /**
+     * The level of reasoning effort to apply; defaults to model-specific value.
+     * Effective only for models with reasoning.
+     */
+    reasoningEffort?: AiReasoningEffort;
+    /**
+     * Controls response length and detail level.
+     * Use `low` for brief responses, `medium` for balanced detail, or `high` for comprehensive explanations.
+     * Default: 'medium'.
+     *
+     * Note: this parameter is only supported by OpenAI plain text responses and is ignored for others.
+     * For other providers ask about verbosity in prompt and using `maxOutputTokens`.
+     */
+    verbosity?: AiVerbosityLevel;
 }
 /**
  * Chat options specific to Gemini models, extending base options.
@@ -337,23 +360,18 @@ export interface GrokChatOptions extends BaseAiChatOptions {
 export interface OpenAiChatOptions extends BaseAiChatOptions {
     /** The OpenAI model to use for the chat. */
     model?: OpenAiChatModelName;
-    /** An array of file URLs to include in the chat context. */
-    fileUrls?: Array<AiFileUrl>;
 }
 /**
+ * AI reasoning effort: Unsupported values are mapped to the closest supported option.
  * @category AI
  */
-export type AiReasoningEffort = 'low' | 'medium' | 'high';
+export type AiReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
 /**
- * Chat options for OpenAI reasoning models, extending OpenAI options.
- * @category AI
+ * Controls response length and detail level.
+ * Use `low` for brief responses,`medium` for balanced detail, or `high` for comprehensive explanations.
+ * Default: 'medium'.
  */
-export interface OpenAiReasoningChatOptions extends OpenAiChatOptions {
-    /** The OpenAI reasoning model to use for the chat. */
-    model?: OpenAiReasoningChatModelName;
-    /** The level of reasoning effort to apply; defaults to model-specific value. */
-    reasoningEffort?: AiReasoningEffort;
-}
+export type AiVerbosityLevel = 'low' | 'medium' | 'high';
 /**
  * Chat options specific to Anthropic models, extending base options.
  * @category AI
@@ -361,20 +379,18 @@ export interface OpenAiReasoningChatOptions extends OpenAiChatOptions {
 export interface AnthropicChatOptions extends BaseAiChatOptions {
     /** The Anthropic model to use for the chat. */
     model?: AnthropicChatModelName;
-    /** The level of reasoning effort to apply. Defaults to no reasoning. */
-    reasoningEffort?: AiReasoningEffort;
 }
 /**
  * The generic options type. When no generic is provided,
  * the type is inferred from the provided overrideModel (or falls back to BaseAiAgentChatOptions).
  * @category AI
  */
-export type AiChatOptions<T extends AiChatModelName | undefined = undefined> = T extends undefined ? BaseAiChatOptions | GeminiChatOptions | OpenAiReasoningChatOptions | OpenAiChatOptions | AnthropicChatOptions : T extends GeminiChatModelName ? GeminiChatOptions : T extends OpenAiReasoningChatModelName ? OpenAiReasoningChatOptions : T extends OpenAiChatModelName ? OpenAiChatOptions : T extends AnthropicChatModelName ? AnthropicChatOptions : T extends GrokChatModelName ? GrokChatOptions : never;
+export type AiChatOptions<T extends AiChatModelName | undefined = undefined> = T extends undefined ? BaseAiChatOptions | GeminiChatOptions | OpenAiChatOptions | AnthropicChatOptions : T extends GeminiChatModelName ? GeminiChatOptions : T extends OpenAiChatModelName ? OpenAiChatOptions : T extends AnthropicChatModelName ? AnthropicChatOptions : T extends GrokChatModelName ? GrokChatOptions : never;
 /**
  * @category AI
  */
 export type AllAiAgentChatOptions = {
-    [K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiReasoningChatOptions | keyof OpenAiChatOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiReasoningChatOptions ? OpenAiReasoningChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never);
+    [K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiChatOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never);
 };
 /**
  * A definition of an AI agent with its properties and default chat options.
@@ -424,8 +440,8 @@ export interface AiStatusMessage {
     tags?: Record<string, any>;
 }
 /**
- * Name of the tag that contains ID of the parent message .
- * When the tag is present the current message should be considered in the context of the parent message.
+ * Name of the tag that contains ID of the parent message.
+ * When the tag is present, the current message should be considered in the context of the parent message.
  * Example: the message can contain a function call result.
  */
 export declare const AI_STATUS_MESSAGE_PARENT_MESSAGE_ID_TAG = "parent";
@@ -496,27 +512,31 @@ interface BaseContextRequest {
  * Status of an individual context item after successfully upserting it.
  * @category AI
  */
-export interface UpsertContextStatusSuccess {
-    /** Whether the context upsert was successful or got an error. */
-    status: 'success';
+export interface BaseUpsertContextStatus {
+    /** Whether the context upsert was successful, otherwise, what occurred. */
+    status: 'success' | 'error';
     /** The unique identifier of the context item. */
     contextId: string;
     /** The name of the context item, typically the title or filename. */
     name: string;
 }
+/**
+ * Status of an individual context item after successfully upserting it.
+ * @category AI
+ */
+export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
+    /** Whether the context upsert was successful or got an error. */
+    status: 'success';
+}
 /**
  * Status of an individual context item after it failed to upsert.
  *
  * Contains the error message for why the upsert failed.
  * @category AI
  */
-export interface UpsertContextStatusError {
+export interface UpsertContextStatusError extends BaseUpsertContextStatus {
     /** Whether the context upsert was successful or got an error. */
     status: 'error';
-    /** The unique identifier of the context item. */
-    contextId: string;
-    /** The name of the context item, typically the title or filename. */
-    name: string;
     /** Reason the upsert failed. */
     errorMessage: string;
 }
@@ -525,12 +545,20 @@ export interface UpsertContextStatusError {
  * @category AI
  */
 export type UpsertContextStatus = UpsertContextStatusSuccess | UpsertContextStatusError;
+/**
+ * Response structure for upserting context.
+ * @category AI
+ */
+export interface UpsertAgentContextResponse {
+    /** Upsert failure that occurred for the items sent in the request. */
+    failure?: UpsertContextStatusError;
+}
 /**
  * Response structure for upserting contexts.
  * @category AI
  */
 export interface UpsertAgentContextsResponse {
-    /** List of the upsert status of each item sent in the request. */
+    /** List of the upsert failures that occurred for the items sent in the request. */
     failures: Array<UpsertContextStatusError>;
 }
 /**
@@ -574,6 +602,16 @@ export interface FileContextRequest extends BaseContextRequest {
     extractionModel?: AiChatModelName;
     /** General options for how to process the file. */
     options?: AiContextFileOptions;
+    /** The preferred method for extracting data from the document. */
+    preferredExtractionMethod?: DocumentExtractionMethod;
+    /**
+     * Whether Squid keeps or discards the original file.
+     *
+     * Keeping the original file allows reprocessing and the ability for the user to download it later.
+     *
+     * Defaults to false.
+     */
+    discardOriginalFile?: boolean;
 }
 /**
  * Base options for how to deal with the content being upserted.
@@ -614,6 +652,8 @@ export interface AiTranscribeAndAskResponse {
     responseString: string;
     /** The transcribed text from the audio input. */
     transcribedPrompt: string;
+    /** The annotations associated with the AI response, if any. */
+    annotations?: Record<string, AiAnnotation>;
 }
 /** Per application AI settings. */
 export interface ApplicationAiSettings {
@@ -640,4 +680,13 @@ export interface UserAiAskResponse {
     /** The number of output tokens generated by the AI agent. */
     outputTokens?: number;
 }
+/** Represents an annotation in the AI response. */
+export type AiAnnotation = AiFileAnnotation;
+/** Represents an annotation for a file in the AI response. */
+export interface AiFileAnnotation {
+    /** The type of the annotation, always 'file'. */
+    type: 'file';
+    /** The AI file with the URL to the file */
+    aiFileUrl: AiFileUrl;
+}
 export {};

package/dist/internal-common/src/public-types/ai-common.public-types.d.ts

@@ -16,18 +16,9 @@ export declare const AI_PROVIDER_TYPES: readonly ["anthropic", "flux", "gemini",
  */
 export type AiProviderType = (typeof AI_PROVIDER_TYPES)[number];
 /**
- * The supported OpenAI models.
  * @category AI
  */
-export declare const OPENAI_O1_CHAT_MODEL_NAMES: readonly ["o1"];
-/**
- * @category AI
- */
-export declare const OPENAI_REASONING_CHAT_MODEL_NAMES: readonly ["o1", "o3", "o3-mini", "o4-mini"];
-/**
- * @category AI
- */
-export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-4o", "gpt-4o-mini", "gpt-4.1-nano", "gpt-4.1-mini", "gpt-4.1", "o1", "o3", "o3-mini", "o4-mini"];
+export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["o1", "o3", "o3-mini", "o4-mini", "gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini"];
 /**
  * @category AI
  */
@@ -44,12 +35,12 @@ export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-3", "grok-3-fast", "
 /**
  * @category AI
  */
-export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-3-7-sonnet-latest", "claude-opus-4-20250514", "claude-sonnet-4-20250514"];
+export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-3-7-sonnet-latest", "claude-opus-4-20250514", "claude-opus-4-1-20250805", "claude-sonnet-4-20250514"];
 /**
  * The supported AI model names.
  * @category AI
  */
-export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-4o", "gpt-4o-mini", "gpt-4.1-nano", "gpt-4.1-mini", "gpt-4.1", "o1", "o3", "o3-mini", "o4-mini", "claude-3-7-sonnet-latest", "claude-opus-4-20250514", "claude-sonnet-4-20250514", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "grok-3", "grok-3-fast", "grok-3-mini", "grok-3-mini-fast", "grok-4"];
+export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["o1", "o3", "o3-mini", "o4-mini", "gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "claude-3-7-sonnet-latest", "claude-opus-4-20250514", "claude-opus-4-1-20250805", "claude-sonnet-4-20250514", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "grok-3", "grok-3-fast", "grok-3-mini", "grok-3-mini-fast", "grok-4"];
 /**
  * Check if the given model name is a global AI chat model name.
  */
@@ -127,10 +118,6 @@ export type AiVoyageEmbeddingsModelName = (typeof VOYAGE_EMBEDDING_MODEL_NAMES)[
  * @category AI
  */
 export type OpenAiChatModelName = (typeof OPENAI_CHAT_MODEL_NAMES)[number];
-/**
- * @category AI
- */
-export type OpenAiReasoningChatModelName = (typeof OPENAI_REASONING_CHAT_MODEL_NAMES)[number];
 /**
  * @category AI
  */

package/dist/internal-common/src/public-types/ai-knowledge-base.public-types.d.ts

@@ -1,6 +1,7 @@
-import { UpsertContextStatusError } from './ai-agent.public-types';
+import { AnthropicChatOptions, BaseAiChatOptions, GeminiChatOptions, GrokChatOptions, OpenAiChatOptions, UpsertContextStatusError } from './ai-agent.public-types';
 import { AiChatModelName, AiEmbeddingsModelName, AiRerankProvider } from './ai-common.public-types';
 import { AiKnowledgeBaseId } from './communication.public-types';
+import { DocumentExtractionMethod } from './extraction.public-types';
 /**
  * Represents an AI knowledge base that can be attached to an AI agent.
  * @category AI
@@ -16,6 +17,8 @@ export interface AiKnowledgeBase {
     metadataFields: Array<AiKnowledgeBaseMetadataField>;
     /** The embedding model name that should be used for this knowledge base.*/
     embeddingModel: AiEmbeddingsModelName;
+    /** The model name that should be used when asking questions of this knowledge base. */
+    chatModel: AiChatModelName;
 }
 /**
  * Represents a field in an AI knowledge base metadata.
@@ -186,6 +189,16 @@ export interface AiKnowledgeBaseFileContextRequest extends BaseAiKnowledgeBaseCo
     imageExtractionModel?: AiChatModelName;
     /** General options for how to process the file. */
     options?: AiKnowledgeBaseContextFileOptions;
+    /** The preferred method for extracting data from the document. */
+    preferredExtractionMethod?: DocumentExtractionMethod;
+    /**
+     * Whether Squid keeps or discards the original file.
+     *
+     * Keeping the original file allows reprocessing and the ability for the user to download it later.
+     *
+     * Defaults to false.
+     */
+    discardOriginalFile?: boolean;
 }
 /**
  * @category AI
@@ -206,21 +219,28 @@ export type BaseAiKnowledgeBaseContextOptions = {
     chunkOverlap?: number;
 };
 /**
- * The options for the AI agent search method.
+ * Specific options for the AI knowledgebase search method.
  * @category AI
  */
 export interface AiKnowledgeBaseSearchOptions {
     /** The prompt to search for */
     prompt: string;
-    /** A set of filters that will limit the context the AI can access */
-    contextMetadataFilter?: AiContextMetadataFilter;
     /** The maximum number of results to return */
     limit?: number;
     /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
     rerankProvider?: AiRerankProvider;
     /** How many chunks to look over. Defaults to 100 */
     chunkLimit?: number;
+    /** Which chat model to use when asking the question */
+    chatModel?: string;
 }
+/**
+ * The options for the AI knowledgebase search method.
+ * @category AI
+ */
+export type AllAiKnowledgeBaseChatOptions = {
+    [K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiChatOptions | keyof AiKnowledgeBaseSearchOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never) | (K extends keyof AiKnowledgeBaseSearchOptions ? AiKnowledgeBaseSearchOptions[K] : never);
+};
 /**
  * A single chunk of data returned from an AI search operation.
  * @category AI
@@ -237,8 +257,35 @@ export interface AiKnowledgeBaseSearchResultChunk {
  * Response structure for upserting context for an AiKnowledgeBase
  * @category AI
  */
+export interface UpsertKnowledgeBaseContextResponse {
+    /** List of the upsert status of each item sent in the request. */
+    failure?: UpsertContextStatusError;
+}
+/**
+ * Response structure for upserting contexts for an AiKnowledgeBase
+ * @category AI
+ */
 export interface UpsertKnowledgeBaseContextsResponse {
     /** List of the upsert status of each item sent in the request. */
     failures: Array<UpsertContextStatusError>;
 }
+/**
+ * Request structure for searching an AiKnowledgeBase
+ * @category AI
+ */
+export interface AiKnowledgeBaseSearchRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** The user prompt to search on */
+    prompt: string;
+    /** The search options for this search */
+    options: AiKnowledgeBaseSearchOptions;
+}
+/**
+ * KnowledgeBase with optional chatModel param, used during upsert
+ * @category AI
+ */
+export type AiKnowledgeBaseWithOptionalChatModel = Omit<AiKnowledgeBase, 'chatModel'> & {
+    chatModel?: AiKnowledgeBase['chatModel'];
+};
 export {};

package/dist/internal-common/src/public-types/ai-query.public-types.d.ts

@@ -1,4 +1,4 @@
-import { AiChatModelName } from './ai-common.public-types';
+import { AiChatOptions } from './ai-agent.public-types';
 import { ApiOptions } from './api-client.public-types';
 import { IntegrationId } from './communication.public-types';
 /**
@@ -20,21 +20,65 @@ export interface ExecuteAiQueryRequest {
  * @category AI
  */
 export interface ExecuteAiQueryOptions {
-    /** Custom instructions to modify AI query behavior. */
+    /**
+     * Custom instructions to modify AI query generation behavior.
+     * Used for all stages unless there is a per-stage override.
+     */
     instructions?: string;
-    /** List of collections to use in the AI query. */
-    collectionsToUse?: Array<string>;
     /** Whether to enable raw results output. */
     enableRawResults?: boolean;
-    /** Whether to enable code interpreter for query execution. */
-    enableCodeInterpreter?: boolean;
-    /** Specific AI model override for the query execution. */
-    overrideModel?: AiChatModelName;
     /** Whether to generate a step-by-step walkthrough for the response. */
     generateWalkthrough?: boolean;
-    /** The number of allowed retries in case of errors during query execution. Defaults to 2. */
+    /** Options for the collection selection stage. */
+    selectCollectionsOptions?: AiQuerySelectCollectionsOptions;
+    /** Options for the query generation stage. */
+    generateQueryOptions?: AiQueryGenerateQueryOptions;
+    /** Options specify how to query result should be analyzed (processed) before returning it to user. */
+    analyzeResultsOptions?: AiQueryAnalyzeResultsOptions;
+}
+/**
+ * Options for the collection selection stage.
+ *
+ * At this stage Squid selects a subset of collections that will be used by the later stage to generate the real query.
+ * It is recommended that the set of collections selected by this stage be broad enough so the query generation stage
+ * has a good view of the database.
+ */
+export interface AiQuerySelectCollectionsOptions {
+    /**
+     * Limits collections to be used in the query only to these collections.
+     * When not provided, all collections are used.
+     */
+    collectionsToUse?: string[];
+    /** Defines the stage algorithm. Default: 'auto'. */
+    runMode?: AiQueryCollectionsSelectionRunMode;
+    /** Used to customize AI agent behavior used by the stage. */
+    aiOptions?: AiChatOptions;
+}
+/**
+ * Defines the stage behavior:
+ * - 'default' - Squid will decide if to run the collection selection algorithm or not.
+ * - 'force' - Collection selection algorithm is run always, even if collectionsToUse are provided.
+ * - 'disable' - The stage is disabled. The whole schema (or collectionsToUse) will be passed to the next step.
+ */
+export type AiQueryCollectionsSelectionRunMode = 'default' | 'force' | 'disable';
+/**
+ * Options for the query generation stage.
+ *
+ * At this stage Squid generates the database native query based on the user prompt and a set of collections selected
+ * in the previous stage. */
+export interface AiQueryGenerateQueryOptions {
+    /** Customizes AI agent behavior used by the stage. */
+    aiOptions?: AiChatOptions;
+    /** Number of retries due to errors in a generated AI query. Default: 2. */
     maxErrorCorrections?: number;
 }
+/** Options for the query result analysis. */
+export interface AiQueryAnalyzeResultsOptions {
+    /** Enables or disables code interpreter mode. Default: 'false'. */
+    enableCodeInterpreter?: boolean;
+    /** Customizes AI agent behavior used by the stage. */
+    aiOptions?: AiChatOptions;
+}
 /**
  * Response from an AI query execution.
  * Contains the generated answer, optional explanation, and executed query details.
@@ -61,7 +105,7 @@ export interface ExecuteAiQueryResponse {
 export interface ExecutedQuery {
     /** Text of the executed query. */
     query: string;
-    /** The markdown type of the result (sql, mongo, etc.). */
+    /** The Markdown type of the result (sql, mongo, etc.). */
     markdownType: string;
     /** URL to access raw results from the query execution. */
     rawResultsUrl?: string;
@@ -89,10 +133,10 @@ export interface AiApiResult {
     /** ID of the executed API endpoint. */
     endpointId: string;
     /** Name of the executed API endpoint. */
-    responseBody: string;
+    responseBody: string | object;
     /** Status code of the executed API request. */
     responseStatusCode: number;
-    /** Request body of the executed API request. */
+    /** Request's body of the executed API request. */
     requestBody: any;
     /** Request options of the executed API request. */
     requestOptions: ApiOptions;

package/dist/internal-common/src/public-types/api.public-types.d.ts

@@ -23,7 +23,7 @@ export interface ApiRequestField {
     required?: boolean;
 }
 /** The options for calling an API. */
-export interface CallApiOptions {
+export interface InternalCallApiOptions {
     /** If true, the response will be returned as-is without any processing. */
     nativeResponse?: boolean;
     /**
@@ -32,15 +32,6 @@ export interface CallApiOptions {
      */
     originOverride?: string;
 }
-/** A native API call response. */
-export interface NativeApiCallResponse<BodyType = unknown> {
-    /** The response body, typed according to the expected content. */
-    body: BodyType;
-    /** A record of HTTP headers returned in the response. */
-    headers: Record<string, string>;
-    /** The HTTP status code of the response. */
-    status: number;
-}
 /** Describes a field included in an API response, optionally including the field path and a description. */
 export interface ApiResponseField {
     /** The location of the field in the API response (e.g., header, body). */

package/dist/internal-common/src/public-types/communication.public-types.d.ts

@@ -16,7 +16,7 @@ export type SquidDocId = string;
 export type ClientRequestId = string;
 /** ID of AI agent. Also known as AI profile id. */
 export type AiAgentId = string;
-/** ID of AI Knowledge Base */
+/** App-level ID of AI Knowledge Base */
 export type AiKnowledgeBaseId = string;
 /**
  * The built-in agent id. Cannot be customized.

package/dist/internal-common/src/public-types/extraction.public-types.d.ts

@@ -22,6 +22,14 @@ export interface ExtractDataFromDocumentOptions {
      * The preferred method for extracting data from the document.
      */
     preferredExtractionMethod?: DocumentExtractionMethod;
+    /**
+     * Whether Squid keeps or discards the original file.
+     *
+     * Keeping the original file allows reprocessing and the ability for the user to download it later.
+     *
+     * Defaults to false.
+     */
+    discardOriginalFile?: boolean;
 }
 /**
  * Request payload for extracting data from a document via URL.
@@ -91,6 +99,10 @@ export interface ExtractDataFromDocumentResponse {
      * Array of pages containing extracted data.
      */
     pages: Array<ExtractDataFromDocumentPage>;
+    /**
+     * Path to the original file in cloud storage, if applicable.
+     */
+    longTermStoragePath?: string;
 }
 /**
  * Create PDF request type.

package/dist/internal-common/src/public-types/integration.public-types.d.ts

@@ -1,6 +1,6 @@
 import { IntegrationId } from './communication.public-types';
 /** List of all integration types supported by Squid. */
-export declare const INTEGRATION_TYPES: readonly ["active_directory", "ai_agents", "ai_chatbot", "algolia", "alloydb", "api", "auth0", "azure_cosmosdb", "azure_postgresql", "azure_sql", "bigquery", "built_in_db", "built_in_gcs", "built_in_queue", "built_in_s3", "cassandra", "clickhouse", "cloudsql", "cockroach", "cognito", "confluence", "confluent", "datadog", "db2", "descope", "documentdb", "dynamodb", "elasticsearch", "firebase_auth", "firestore", "gcs", "google_docs", "google_drive", "graphql", "hubspot", "jira", "jwt_hmac", "jwt_rsa", "kafka", "linear", "mariadb", "monday", "mongo", "mssql", "databricks", "mysql", "newrelic", "okta", "onedrive", "oracledb", "pinecone", "postgres", "redis", "s3", "salesforce_crm", "sap_hana", "sentry", "servicenow", "snowflake", "spanner", "xata", "zendesk", "mail", "slack", "mcp", "a2a"];
+export declare const INTEGRATION_TYPES: readonly ["active_directory", "ai_agents", "ai_knowledgebases", "ai_chatbot", "algolia", "alloydb", "api", "auth0", "azure_cosmosdb", "azure_postgresql", "azure_sql", "bigquery", "built_in_db", "built_in_gcs", "built_in_queue", "built_in_s3", "cassandra", "clickhouse", "cloudsql", "cockroach", "cognito", "confluence", "confluent", "datadog", "db2", "descope", "documentdb", "dynamodb", "elasticsearch", "firebase_auth", "firestore", "gcs", "google_docs", "google_drive", "graphql", "hubspot", "jira", "jwt_hmac", "jwt_rsa", "kafka", "linear", "mariadb", "monday", "mongo", "mssql", "databricks", "mysql", "newrelic", "okta", "onedrive", "oracledb", "pinecone", "postgres", "redis", "s3", "salesforce_crm", "sap_hana", "sentry", "servicenow", "snowflake", "spanner", "xata", "zendesk", "mail", "slack", "mcp", "a2a"];
 /**
  * @category Database
  */

package/dist/typescript-client/src/agent/ai-agent-client-reference.d.ts

@@ -1,8 +1,8 @@
 import { Observable } from 'rxjs';
-import { AgentContextRequest, AiAgent, AiAgentContext, AiConnectedAgentMetadata, AiSearchOptions, AiSearchResultChunk, AiStatusMessage, AiTranscribeAndAskResponse, GuardrailsOptions, UpsertAgentContextsResponse, UpsertAgentRequest } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AgentContextRequest, AiAgent, AiAgentContext, AiConnectedAgentMetadata, AiSearchOptions, AiSearchResultChunk, AiStatusMessage, AiTranscribeAndAskResponse, GuardrailsOptions, UpsertAgentContextResponse, UpsertAgentContextsResponse, UpsertAgentRequest } from '../../../internal-common/src/public-types/ai-agent.public-types';
 import { AiChatModelName } from '../../../internal-common/src/public-types/ai-common.public-types';
 import { JobId } from '../../../internal-common/src/public-types/job.public-types';
-import { AiAskOptions, AiAskOptionsWithVoice, AiChatOptionsWithoutVoice, AskWithVoiceResponse, TranscribeAndAskWithVoiceResponse, TranscribeAndChatResponse } from './ai-agent-client.types';
+import { AiAskOptions, AiAskOptionsWithVoice, AiChatOptionsWithoutVoice, AskResponse, AskWithVoiceResponse, TranscribeAndAskWithVoiceResponse, TranscribeAndChatResponse } from './ai-agent-client.types';
 /**
  * Parameters for creating or updating an AI agent.
  * Excludes the `id` field, as it is derived from the agent instance.
@@ -64,7 +64,7 @@ export declare class AiAgentReference {
     /**
      * Adds or updates a single agent context.
      */
-    upsertContext(contextRequest: AgentContextRequest, file?: File): Promise<void>;
+    upsertContext(contextRequest: AgentContextRequest, file?: File): Promise<UpsertAgentContextResponse>;
     /**
      * Adds or updates multiple agent contexts.
      */
@@ -112,7 +112,7 @@ export declare class AiAgentReference {
      */
     search(options: AiSearchOptions): Promise<Array<AiSearchResultChunk>>;
     /**
-     * Sends a prompt and receives a full string response.
+     * Sends a prompt and returns a full string response.
      * @param prompt The text prompt to send to the agent.
      * @param options Optional parameters for the AI ask request.
      * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
@@ -120,9 +120,19 @@ export declare class AiAgentReference {
      *   knows it can look up the job’s status.
      */
     ask<T extends AiChatModelName | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<string>;
+    /**
+     * Sends a prompt and returns the string response and file annotations.
+     * @param prompt The text prompt to send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
+     */
+    askWithAnnotations<T extends AiChatModelName | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<AskResponse>;
     /**
      * Sends a prompt and not wait for the result - the result can be tracked using the job ID
      * (`squid.jobs().awaitJob(jobId)` or `squid.jobs().getJob(jobId)).
+     * The result is of type AiAskResponse which contains the response string and optional annotations.
      * @param prompt The text prompt to send to the agent.
      * @param jobId A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
      *   `squid.jobs().getJob(jobId)`

package/dist/typescript-client/src/agent/ai-agent-client.types.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiChatOptions } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AiAnnotation, AiChatOptions } from '../../../internal-common/src/public-types/ai-agent.public-types';
 import { AiChatModelName } from '../../../internal-common/src/public-types/ai-common.public-types';
 /**
  * Response format for transcribing audio and generating a chat response.
@@ -25,6 +25,16 @@ export interface TranscribeAndAskWithVoiceResponse {
     /** AI-generated voice response as an audio file. */
     voiceResponseFile: File;
 }
+/**
+ * Response from an AI agent when asked a question or given a task.
+ * @category AI
+ */
+export interface AskResponse {
+    /** The main text response from the AI agent. */
+    responseString: string;
+    /** Optional annotations that provide additional context or metadata about the response. */
+    annotations?: Record<string, AiAnnotation>;
+}
 /**
  * Response format for AI-generated voice responses.
  * Contains the AI-generated text response and the corresponding audio file.