@squidcloud/slack-client 1.0.409

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

@@ -0,0 +1,743 @@
+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, AppId, 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';
+/**
+ * @category AI
+ */
+export type AiGenerateImageOptions = DallEOptions | StableDiffusionCoreOptions | FluxOptions;
+/**
+ * @category AI
+ */
+export type OpenAiAudioTranscribeOptions = WhisperTranscribeOptions | Gpt4oTranscribeOptions;
+/**
+ * @category AI
+ */
+export type AiAudioTranscribeOptions = OpenAiAudioTranscribeOptions;
+/**
+ * @category AI
+ */
+export type AiAudioCreateSpeechOptions = OpenAiCreateSpeechOptions;
+/**
+ * Base options for generating images with an AI model.
+ * @category AI
+ */
+export interface BaseAiGenerateImageOptions {
+    /** The name of the AI model to use for image generation. */
+    modelName: AiImageModelName;
+}
+/**
+ * Base options for transcribing audio with an AI model.
+ * @category AI
+ */
+export interface BaseAiAudioTranscribeOptions {
+    /** The name of the AI model to use for audio transcription. */
+    modelName: AiAudioTranscriptionModelName;
+}
+/**
+ * Base options for creating speech with an AI model.
+ * @category AI
+ */
+export interface BaseAiAudioCreateSpeechOptions {
+    /** The name of the AI model to use for speech creation. */
+    modelName: AiAudioCreateSpeechModelName;
+}
+/**
+ * Options for generating images using the DALL-E model.
+ * @category AI
+ */
+export interface DallEOptions extends BaseAiGenerateImageOptions {
+    /** Specifies the DALL-E 3 model for image generation. */
+    modelName: 'dall-e-3';
+    /** The quality of the generated image; defaults to 'standard'. */
+    quality?: 'hd' | 'standard';
+    /** The size of the generated image; defaults to '1024x1024'. */
+    size?: '1024x1024' | '1792x1024' | '1024x1792';
+    /** The number of images to generate; defaults to 1 and limited to 1. */
+    numberOfImagesToGenerate?: 1;
+}
+interface BaseOpenAiAudioTranscribeOptions extends BaseAiAudioTranscribeOptions {
+    /** Specifies the  model for audio transcription. */
+    modelName: OpenAiAudioTranscriptionModelName;
+    /** The temperature for sampling during transcription; defaults to model-specific value. */
+    temperature?: number;
+    /** An optional prompt to guide the transcription process. */
+    prompt?: string;
+}
+/**
+ * Options for transcribing audio using the Whisper model.
+ * @category AI
+ */
+export interface WhisperTranscribeOptions extends BaseOpenAiAudioTranscribeOptions {
+    /** Specifies the Whisper-1 model for audio transcription. */
+    modelName: 'whisper-1';
+    /** The format of the transcription response; defaults to 'json'. */
+    responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
+}
+/**
+ * Options for transcribing audio using the GPT-4o model.
+ * @category AI
+ */
+export interface Gpt4oTranscribeOptions extends BaseOpenAiAudioTranscribeOptions {
+    /** Specifies the Whisper-1 model for audio transcription. */
+    modelName: 'gpt-4o-transcribe' | 'gpt-4o-mini-transcribe';
+    /** The format of the transcription response; defaults to 'json'. */
+    responseFormat?: 'json';
+}
+/**
+ * Options for creating speech using OpenAI's text-to-speech models.
+ * @category AI
+ */
+export interface OpenAiCreateSpeechOptions extends BaseAiAudioCreateSpeechOptions {
+    /** The OpenAI model to use for speech creation (e.g., 'tts-1' or 'tts-1-hd'). */
+    modelName: OpenAiAudioCreateSpeechModelName;
+    /** The voice to use for speech synthesis; defaults to model-specific value. */
+    voice?: 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'sage' | 'shimmer' | 'verse';
+    /** The format of the audio output; defaults to 'mp3'. */
+    responseFormat?: OpenAiCreateSpeechFormat;
+    /** An optional prompt to guide the speech synthesis process. */
+    instructions?: string;
+    /** The speed of the speech; defaults to 1.0. */
+    speed?: number;
+}
+/**
+ * Options for generating images using the Flux model.
+ * @category AI
+ */
+export interface FluxOptions extends BaseAiGenerateImageOptions {
+    /** Specifies the Flux Pro 1.1 model for image generation. */
+    modelName: 'flux-pro-1.1' | 'flux-kontext-pro';
+    /** The width of the generated image, must be a multiple of 32, min 256, max 1440; defaults to 1024. */
+    width?: number;
+    /** The height of the generated image, must be a multiple of 32, min 256, max 1440; defaults to 768. */
+    height?: number;
+    /** Whether to enhance the prompt for more creative output; defaults to false. */
+    prompt_upsampling?: boolean;
+    /** A random seed for reproducible generation, if specified. */
+    seed?: number;
+    /** The safety tolerance level, from 1 (strict) to 5 (permissive). */
+    safety_tolerance?: number;
+}
+/**
+ * Options for generating images using the Stable Diffusion Core model.
+ * @category AI
+ */
+export interface StableDiffusionCoreOptions extends BaseAiGenerateImageOptions {
+    /** Specifies the Stable Diffusion Core model for image generation. */
+    modelName: 'stable-diffusion-core';
+    /** The aspect ratio of the generated image; defaults to '1:1'. */
+    aspectRatio?: '16:9' | '1:1' | '21:9' | '2:3' | '3:2' | '4:5' | '5:4' | '9:16' | '9:21';
+    /** An optional negative prompt to guide what to exclude from the image. */
+    negativePrompt?: string;
+    /** A random seed for reproducible generation, if specified. */
+    seed?: number;
+    /** A style preset to apply to the generated image, if specified. */
+    stylePreset?: 'analog-film' | 'anime' | 'cinematic' | 'comic-book' | 'digital-art' | 'enhance' | 'fantasy-art' | 'isometric' | 'line-art' | 'low-poly' | 'modeling-compound' | 'neon-punk' | 'origami' | 'photographic' | 'pixel-art' | 'tile-texture';
+    /** The format of the output image; defaults to 'png'. */
+    outputFormat?: 'jpeg' | 'png' | 'webp';
+}
+/**
+ * The possible sources for the LLM provider API key.
+ * @category AI
+ */
+export type ApiKeySource = 'user' | 'system';
+/**
+ * @category AI
+ */
+export type AiAgentResponseFormat = 'text' | 'json_object';
+/**
+ * @category AI
+ */
+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
+ */
+export interface AiConnectedIntegrationMetadata<AiConnectedIntegrationOptionsType = unknown> {
+    /** The ID of the connected integration. */
+    integrationId: IntegrationId;
+    /** The type of the connected integration (e.g., API, database). */
+    integrationType: IntegrationType;
+    /** An optional description of the integration for the parent agent context, used as AI function description. */
+    description?: string;
+    /** Optional instructions for the connected integration agent, overriding the default if provided. */
+    instructions?: string;
+    /**
+     * Additional options for the connected integration.
+     * Squid Core or AI functions in connector packages may use these options to adjust behavior of the integration agent.
+     */
+    options?: AiConnectedIntegrationOptionsType;
+}
+/**
+ * Metadata for a connected AI agent callable by the current agent.
+ * @category AI
+ */
+export interface AiConnectedAgentMetadata {
+    /** The ID of the connected AI agent. */
+    agentId: AiAgentId;
+    /** A description of the connected agent for the parent agent context, used as AI function description. */
+    description: string;
+}
+/**
+ * Metadata for a connected AI Knowledge Base callable by the current agent.
+ * @category AI
+ */
+export interface AiConnectedKnowledgeBaseMetadata {
+    /** The ID of the connected AI KnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** A description of when to use this AiKnowledgeBase */
+    description: string;
+}
+/**
+ * Quotas for a single AI chat prompt (`ask()` method call).
+ * @category AI
+ */
+export interface AiChatPromptQuotas {
+    /**
+     * Maximum depth of AI call recursion allowed.
+     * Recursion occurs when one AI agent calls another.
+     * Note that, for simplicity of implementation, this option guarantees only the maximum recursion depth,
+     * not the total number of nested AI calls.
+     * Default: 5.
+     */
+    maxAiCallStackSize: number;
+}
+/**
+ * Options for AI agent execution plan, allowing the agent to plan what functionality to use (connected agents,
+ * connected, integrations, or functions).
+ */
+export interface AiAgentExecutionPlanOptions {
+    /** Whether to enable an execution plan for the agent. */
+    enabled: boolean;
+    /** The model to use for the execution plan - defaults to the model used by the agent. */
+    model?: AiChatModelName;
+    /** In case the model supports reasoning, this will control the level of effort - defaults to `high`. */
+    reasoningEffort?: AiReasoningEffort;
+}
+/**
+ * Options for AI agent memory management.
+ * @category AI
+ */
+export interface AiAgentMemoryOptions {
+    /**
+     * The memory mode:
+     *   - 'none': No memory is used, the agent does not remember past interactions.
+     *   - 'read-only': The agent can read from memory but cannot write to it.
+     *   - 'read-write': The agent can both read from and write to memory.
+     */
+    memoryMode: 'none' | 'read-only' | 'read-write';
+    /**
+     * A unique ID to store the chat memory.
+     *
+     * The full chat memory key is constructed as a combination of 'appId', 'agentId', and 'memoryId'.
+     * If not provided the Squid client instance ID used as a memoryId.
+     *
+     * Important: the memory ID should be treated with the same security measures as Access Token because it unblocks
+     * direct access to the agent chat history. A good practice is to use a non-trivial and a unique value.
+     */
+    memoryId?: string;
+    /**
+     * Overrides the expiration for the whole chat history.
+     * If not provided, the expiration will not be changed.
+     *
+     * Default: the last provided expiration by user or 1 day if
+     *  the user didn't provide any expiration.
+     */
+    expirationMinutes?: number;
+}
+/**
+ * The base AI agent chat options, should not be used directly.
+ * @category AI
+ */
+export interface BaseAiChatOptions {
+    /**
+     * 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.
+     */
+    maxTokens?: number;
+    /**
+     * The maximum number of tokens the model should output.
+     * Passed directly to the AI model. Can be used to control the output verbosity.
+     */
+    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. */
+    disableContext?: boolean;
+    /** Rewrite prompt for RAG - defaults to false */
+    enablePromptRewriteForRag?: boolean;
+    /** Whether to include references from the source context in the response. Default to false. */
+    includeReference?: boolean;
+    /** The format of the response from the AI model. Note that not all models support JSON format. Default to  'text'. */
+    responseFormat?: AiAgentResponseFormat;
+    /** Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true. */
+    smoothTyping?: boolean;
+    /** Global context passed to the agent and all AI functions of the agent. */
+    agentContext?: Record<string, unknown>;
+    /**
+     * Functions to expose to the AI.
+     * Either a function name or a name with an extra function context passed only to this function.
+     * The parameter values must be valid serializable JSON values.
+     * Overrides the stored value.
+     */
+    functions?: Array<AiFunctionId | AiFunctionIdWithContext>;
+    /** Instructions to include with the prompt. */
+    instructions?: string;
+    /** A set of filters that will limit the context the AI can access.
+     * @deprecated use `contextMetadataFilterForKnowledgeBase` instead.
+     */
+    contextMetadataFilter?: AiContextMetadataFilter;
+    /** A set of filters that will limit the context the AI can access. */
+    contextMetadataFilterForKnowledgeBase?: Record<AiKnowledgeBaseId, AiContextMetadataFilter>;
+    /** The options to use for the response in voice. */
+    voiceOptions?: AiAudioCreateSpeechOptions;
+    /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
+    connectedAgents?: Array<AiConnectedAgentMetadata>;
+    /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
+    connectedIntegrations?: Array<AiConnectedIntegrationMetadata>;
+    /** List of connected AiKnowlegeBases that can be called by the current agent */
+    connectedKnowledgeBases?: Array<AiConnectedKnowledgeBaseMetadata>;
+    /** Current budget for nested or recursive AI chat calls per single prompt. */
+    quotas?: AiChatPromptQuotas;
+    /** Include metadata in the context */
+    includeMetadata?: boolean;
+    /** The temperature to use when sampling from the model. Default to 0.5. */
+    temperature?: number;
+    /** Preset instruction options that can be toggled on */
+    guardrails?: GuardrailsOptions;
+    /** The LLM model to use. */
+    model?: AiChatModelName;
+    /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
+    rerankProvider?: AiRerankProvider;
+    /**
+     * Options for AI agent execution plan, allowing the agent to perform an execution plan before invoking
+     * 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;
+    /**
+     * Enable LLMs built-in code interpreter for executing Python code.
+     * - 'none': Code interpreter is disabled (default).
+     * - 'llm': Use LLM's native code interpreter to run Python code.
+     *
+     * Note: Only supported by OpenAI and Gemini models. Ignored for other providers.
+     */
+    useCodeInterpreter?: 'none' | 'llm';
+}
+/**
+ * Chat options specific to Gemini models, extending base options.
+ * @category AI
+ */
+export interface GeminiChatOptions extends BaseAiChatOptions {
+    /** The Gemini model to use for the chat. */
+    model?: GeminiChatModelName;
+    /** Enables grounding with web search for more informed responses; defaults to false. */
+    groundingWithWebSearch?: boolean;
+}
+/**
+ * Chat options specific to Grok models, extending base options.
+ * @category AI
+ */
+export interface GrokChatOptions extends BaseAiChatOptions {
+    /** The Grok model to use for the chat. */
+    model?: GrokChatModelName;
+}
+/**
+ * Chat options specific to OpenAI models, extending base options.
+ * @category AI
+ */
+export interface OpenAiChatOptions extends BaseAiChatOptions {
+    /** The OpenAI model to use for the chat. */
+    model?: OpenAiChatModelName;
+}
+/**
+ * AI reasoning effort: Unsupported values are mapped to the closest supported option.
+ * @category AI
+ */
+export type AiReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+/**
+ * Controls response length and detail level.
+ * Use `low` for brief responses,`medium` for balanced detail, or `high` for comprehensive explanations.
+ * Default: 'medium'.
+ */
+export type AiVerbosityLevel = 'low' | 'medium' | 'high';
+/**
+ * Chat options specific to Anthropic models, extending base options.
+ * @category AI
+ */
+export interface AnthropicChatOptions extends BaseAiChatOptions {
+    /** The Anthropic model to use for the chat. */
+    model?: AnthropicChatModelName;
+}
+/**
+ * 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 | 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 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.
+ * @category AI
+ */
+export interface AiAgent<T extends AiChatModelName | undefined = undefined> {
+    /** The unique identifier of the AI agent. */
+    id: AiAgentId;
+    /** The date and time the agent was created. */
+    createdAt: Date;
+    /** The date and time the agent was last updated. */
+    updatedAt: Date;
+    /** An optional description of the agent's purpose or capabilities. */
+    description?: string;
+    /** Indicates whether the agent is publicly accessible; defaults to false. */
+    isPublic?: boolean;
+    /** Enables audit logging for the agent's activities if true; defaults to false. */
+    auditLog?: boolean;
+    /** The default chat options for the agent, overridable by the user during use. */
+    options: AiChatOptions<T>;
+    /** The embedding model name used by the agent. */
+    embeddingModelName: AiEmbeddingsModelName;
+}
+/**
+ * @category AI
+ */
+export type UpsertAgentRequest = Omit<AiAgent, 'createdAt' | 'updatedAt' | 'options' | 'embeddingModelName'> & {
+    options?: AiChatOptions;
+    embeddingModelName?: AiEmbeddingsModelName;
+};
+/**
+ * A status message from an AI agent operation.
+ * @category AI
+ */
+export interface AiStatusMessage {
+    /** ID of the status update message. */
+    messageId: string;
+    /** The ID of the agent generating the status message. */
+    agentId: AiAgentId;
+    /** An optional chat ID associated with the status message. */
+    chatId?: string;
+    /** The title or summary of the status message. */
+    title: string;
+    /** The Job ID associated with the status message. */
+    jobId: JobId;
+    /** Optional tags providing additional metadata about the status. */
+    tags?: Record<string, any>;
+}
+/** List of all chat history (memory) sources. */
+export declare const AI_CHAT_MESSAGE_SOURCE: readonly ["user", "ai"];
+/** Source of the chat history entry: either an AI response or a user. */
+export type AiChatMessageSource = (typeof AI_CHAT_MESSAGE_SOURCE)[number];
+/** A history entry for a chat. */
+export interface AiChatMessage {
+    /** ID of the entry. Unique per agent. */
+    id: string;
+    /** Agent's application. */
+    appId: AppId;
+    /** The ID of the agent that owns the history. */
+    agentId: AiAgentId;
+    /** A memory (history) ID associated with the chat conversation. */
+    memoryId: string;
+    /** The source of the message: a user or an AI. */
+    source: AiChatMessageSource;
+    /** The text of the entry: a user's prompt or an AI-generated response. */
+    message: string;
+    /** Time the entry is created. Unix time millis. */
+    timestamp: number;
+}
+/**
+ * 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";
+/** The tag contains a response of the AI tool call. */
+export declare const AI_STATUS_MESSAGE_RESULT_TAG = "result";
+/**
+ * The options for the AI agent search method.
+ * @category AI
+ */
+export interface AiSearchOptions {
+    /** The prompt to search for */
+    prompt: string;
+    /** DEPRECATED: A set of filters that will limit the context the AI can access. */
+    contextMetadataFilter?: AiContextMetadataFilter;
+    /** A set of filters that will limit the context the AI can access. */
+    contextMetadataFilterForKnowledgeBase?: Record<AiKnowledgeBaseId, 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;
+}
+/**
+ * A single chunk of data returned from an AI search operation.
+ * @category AI
+ */
+export interface AiSearchResultChunk {
+    /** The data content of the search result chunk. */
+    data: string;
+    /** Optional metadata associated with the chunk. */
+    metadata?: AiContextMetadata;
+    /** The relevance score of the chunk, indicating match quality. */
+    score: number;
+}
+/**
+ * Represents an AI agent's context entry with metadata and content.
+ * @category AI
+ */
+export interface AiAgentContext {
+    /** The unique identifier of the context entry. */
+    id: AiContextId;
+    /** The date and time the context was created. */
+    createdAt: Date;
+    /** The date and time the context was last updated. */
+    updatedAt: Date;
+    /** The ID of the agent owning this context. */
+    agentId: AiAgentId;
+    /** The type of context (e.g., 'text' or 'file'). */
+    type: AiKnowledgeBaseContextType;
+    /** A title describing the context content. */
+    title: string;
+    /** The text content of the context. */
+    text: string;
+    /** Indicates whether the context is a preview; defaults to false. */
+    preview: boolean;
+    /** The size of the context content in bytes. */
+    sizeBytes: number;
+    /** Metadata associated with the context. */
+    metadata: AiContextMetadata;
+}
+/**
+ * @category AI
+ */
+export type AgentContextRequest = TextContextRequest | FileContextRequest;
+interface BaseContextRequest {
+    contextId: string;
+    type: AiKnowledgeBaseContextType;
+    metadata?: AiContextMetadata;
+}
+/**
+ * Status of an individual context item after successfully upserting it.
+ * @category AI
+ */
+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 extends BaseUpsertContextStatus {
+    /** Whether the context upsert was successful or got an error. */
+    status: 'error';
+    /** Reason the upsert failed. */
+    errorMessage: string;
+}
+/**
+ * Status of an individual context item after attempting to upsert it.
+ * @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 failures that occurred for the items sent in the request. */
+    failures: Array<UpsertContextStatusError>;
+}
+/**
+ * Base options for upserting text content into the AI agent's context.
+ * @category AI
+ */
+export interface AiContextTextOptions extends BaseAiContextOptions {
+}
+/**
+ * Base options for upserting file content into the AI agent's context.
+ * @category AI
+ */
+export interface AiContextFileOptions extends BaseAiContextOptions {
+}
+/**
+ * Request structure for adding text-based context to an AI agent.
+ * @category AI
+ */
+export interface TextContextRequest extends BaseContextRequest {
+    /** Specifies the context type as 'text'. */
+    type: 'text';
+    /** A title for the text context. */
+    title: string;
+    /** The text content to add to the context. */
+    text: string;
+    /** General options for how to process the text. */
+    options?: AiContextTextOptions;
+}
+/**
+ * Request structure for adding file-based context to an AI agent.
+ * @category AI
+ */
+export interface FileContextRequest extends BaseContextRequest {
+    /** Specifies the context type as 'file'. */
+    type: 'file';
+    /** Whether to extract images from the file; defaults to false. */
+    extractImages?: boolean;
+    /** The minimum size for extracted images, if applicable. */
+    imageMinSizePixels?: number;
+    /** The AI model to use for extraction, if specified. */
+    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.
+ * @category AI
+ */
+export type BaseAiContextOptions = {
+    /** The type of RAG to use for the content. */
+    ragType?: AiRagType;
+    /** Amount of chunk overlap, in characters. */
+    chunkOverlap?: number;
+};
+/**
+ * @category AI
+ */
+export type GuardrailKeysType = 'disableProfanity' | 'offTopicAnswers' | 'professionalTone' | 'disablePii';
+/**
+ * Options for applying guardrails to AI responses to enforce specific constraints.
+ * @category AI
+ */
+export type GuardrailsOptions = {
+    /** Disables profanity in the AI response if true; defaults to false. */
+    disableProfanity?: boolean;
+    /** Prevents off-topic answers if true; defaults to false. */
+    offTopicAnswers?: boolean;
+    /** Enforces a professional tone in the response if true; defaults to false. */
+    professionalTone?: boolean;
+    /** Disables inclusion of personally identifiable information if true; defaults to false. */
+    disablePii?: boolean;
+    /** A custom guardrail instruction, if specified. */
+    custom?: string;
+};
+/**
+ * Response structure for transcribing audio and asking an AI agent a question.
+ * @category AI
+ */
+export interface AiTranscribeAndAskResponse {
+    /** The AI agent's response to the transcribed prompt. */
+    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 {
+    /** Maps AI provider name to API key secret name that must be used for any request made by the application. */
+    apiKeys: Partial<Record<AiProviderType, SecretKey>>;
+}
+/**
+ * Options for user-provided LLM models.
+ * @category AI
+ */
+export interface UserAiChatOptions extends BaseAiChatOptions {
+    /** LLM Model to use for the chat query. */
+    model: UserAiChatModelName;
+}
+/**
+ * Response structure for asking a user LLM a question.
+ * @category AI
+ */
+export interface UserAiAskResponse {
+    /** The response from the AI agent. */
+    response?: string;
+    /** The number of input tokens used in the request. */
+    inputTokens?: number;
+    /** 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 {};