@squidcloud/client
Version:
A typescript implementation of the Squid client
809 lines (808 loc) • 30.1 kB
TypeScript
import { AiAgentId, AiContextId, IntegrationId } from './communication.public-types';
import { IntegrationType } from './integration.public-types';
import { AiFunctionId, AiFunctionIdWithContext } from './backend.public-types';
import { SecretKey } from './secret.public-types';
/** List of available AI provider types. See AiProviderType. */
export declare const AI_PROVIDER_TYPES: readonly ["anthropic", "flux", "gemini", "openai", "squid", "stability", "voyage"];
/**
* Type of the AI provider.
* References a single AI service, regardless of the model or other AI function it provides (like
* chat/search/transcribe etc...).
*/
export type AiProviderType = (typeof AI_PROVIDER_TYPES)[number];
/**
* The supported OpenAI models.
* @category AI
*/
export declare const OPENAI_O1_CHAT_MODEL_NAMES: readonly ["o1", "o1-mini"];
/**
* @category AI
*/
export declare const OPENAI_REASONING_CHAT_MODEL_NAMES: readonly ["o1", "o1-mini", "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", "o1-mini", "o3", "o3-mini", "o4-mini"];
/**
* @category AI
*/
export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-1.5-pro", "gemini-2.0-flash"];
/**
* @category AI
*/
export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-3-7-sonnet-latest", "claude-opus-4-20250514", "claude-sonnet-4-20250514"];
/**
* AI model names supported internally by Squid.
*
* Currently, Squid supports only one model: 'dictionary'. In this model, the response to each prompt message
* is taken from a predefined dictionary specified in the agent's instructions.
*
* The instructions follow the following format:
*
* ~> Prompt1
* <~ Response1
*
* Both prompt and response can be written in a multiline format. Blank leading and trailing lines are ignored.
*
* ~>
* Prompt2 line1
* Prompt2 line2
* <~
* Response2 line 1
* Response2 line 2
*
* If the prompt is missed in the dictionary the answer will be 'No entry found for this prompt.'
* @category AI
*/
export declare const SQUID_AI_MODEL_NAMES: readonly ["dictionary"];
/**
* The supported AI model names.
* @category AI
*/
export declare const AI_CHAT_MODEL_NAMES: readonly ["gpt-4o", "gpt-4o-mini", "gpt-4.1-nano", "gpt-4.1-mini", "gpt-4.1", "o1", "o1-mini", "o3", "o3-mini", "o4-mini", "claude-3-7-sonnet-latest", "claude-opus-4-20250514", "claude-sonnet-4-20250514", "gemini-1.5-pro", "gemini-2.0-flash", "dictionary"];
/**
* Check if the given model name is a global AI chat model name.
*/
export declare function isGlobalAiChatModelName(modelName: string): modelName is (typeof AI_CHAT_MODEL_NAMES)[number];
/**
* @category AI
*/
export declare const OPENAI_EMBEDDINGS_MODEL_NAMES: readonly ["text-embedding-3-small"];
/**
* @category AI
*/
export declare const VOYAGE_EMBEDDING_MODEL_NAMES: readonly ["voyage-3-large"];
/**
* @category AI
*/
export declare const AI_EMBEDDINGS_MODEL_NAMES: readonly ["text-embedding-3-small", "voyage-3-large"];
/**
* The supported AI image generation model names.
* @category AI
*/
export declare const OPENAI_IMAGE_MODEL_NAMES: readonly ["dall-e-3"];
/**
* @category AI
*/
export declare const OPENAI_AUDIO_TRANSCRIPTION_MODEL_NAMES: readonly ["whisper-1", "gpt-4o-transcribe", "gpt-4o-mini-transcribe"];
/**
* @category AI
*/
export declare const OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES: readonly ["tts-1", "tts-1-hd", "gpt-4o-mini-tts"];
/**
* @category AI
*/
export declare const OPENAI_AUDIO_MODEL_NAMES: readonly ["whisper-1", "gpt-4o-transcribe", "gpt-4o-mini-transcribe", "tts-1", "tts-1-hd", "gpt-4o-mini-tts"];
/**
* @category AI
*/
export declare const STABLE_DIFFUSION_MODEL_NAMES: readonly ["stable-diffusion-core"];
/**
* @category AI
*/
export declare const FLUX_MODEL_NAMES: readonly ["flux-pro-1.1"];
/**
* @category AI
*/
export declare const AI_IMAGE_MODEL_NAMES: readonly ["dall-e-3", "stable-diffusion-core", "flux-pro-1.1"];
/**
* @category AI
*/
export declare const AI_AUDIO_TRANSCRIPTION_MODEL_NAMES: readonly ["whisper-1", "gpt-4o-transcribe", "gpt-4o-mini-transcribe"];
/**
* @category AI
*/
export declare const AI_AUDIO_CREATE_SPEECH_MODEL_NAMES: readonly ["tts-1", "tts-1-hd", "gpt-4o-mini-tts"];
/**
* @category AI
*/
export declare const OPEN_AI_CREATE_SPEECH_FORMATS: readonly ["mp3", "opus", "aac", "flac", "wav", "pcm"];
/**
* @category AI
*/
export type AiChatModelName = (typeof AI_CHAT_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AiEmbeddingsModelName = (typeof AI_EMBEDDINGS_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AiVoyageEmbeddingsModelName = (typeof VOYAGE_EMBEDDING_MODEL_NAMES)[number];
/**
* @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
*/
export type GeminiChatModelName = (typeof GEMINI_CHAT_MODEL_NAMES)[number];
/**
* @category AI
*/
export type SquidAiModelName = (typeof SQUID_AI_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AnthropicChatModelName = (typeof ANTHROPIC_CHAT_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AiImageModelName = (typeof AI_IMAGE_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AiAudioTranscriptionModelName = (typeof AI_AUDIO_TRANSCRIPTION_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AiAudioCreateSpeechModelName = (typeof OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES)[number];
/**
* @category AI
*/
export type AiAudioModelName = (typeof OPENAI_AUDIO_MODEL_NAMES)[number];
/**
* @category AI
*/
export type OpenAiImageModelName = (typeof OPENAI_IMAGE_MODEL_NAMES)[number];
/**
* @category AI
*/
export type OpenAiAudioTranscriptionModelName = (typeof OPENAI_AUDIO_TRANSCRIPTION_MODEL_NAMES)[number];
/**
* @category AI
*/
export type OpenAiAudioCreateSpeechModelName = (typeof OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES)[number];
/**
* @category AI
*/
export type OpenAiCreateSpeechFormat = (typeof OPEN_AI_CREATE_SPEECH_FORMATS)[number];
/**
* @category AI
*/
export type StableDiffusionModelName = (typeof STABLE_DIFFUSION_MODEL_NAMES)[number];
/**
* @category AI
*/
export type FluxModelName = (typeof FLUX_MODEL_NAMES)[number];
/**
* @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;
/**
* @category AI
*/
export declare const RAG_TYPES: readonly ["contextual", "basic"];
/**
* @category AI
*/
export type AiRagType = (typeof RAG_TYPES)[number];
/**
* @category AI
*/
export declare const RERANK_PROVIDERS: readonly ["cohere", "none"];
/**
* @category AI
*/
export type AiRerankProvider = (typeof RERANK_PROVIDERS)[number];
/**
* 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';
/** 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';
/**
* Represents a URL reference to an AI-processed file, such as an image.
* @category AI
*/
export interface AiFileUrl {
/** The type of file referenced by the URL (e.g., 'image'). */
type: AiFileUrlType;
/** The URL pointing to the file. */
url: string;
}
/**
* 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;
}
/**
* 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;
}
/**
* The base AI agent chat options, should not be used directly.
* @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. */
chatId?: string;
/**
* Disables history for the agent, so each question is answered as
* if it were the first question in the conversation.
* Default to false.
*/
disableHistory?: boolean;
/** Whether to disable the whole context for the request. Default to false. */
disableContext?: 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. */
contextMetadataFilter?: 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>;
/** 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;
}
/**
* 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 OpenAI models, extending base options.
* @category AI
*/
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>;
}
/**
* @category AI
*/
export type AiReasoningEffort = 'low' | 'medium' | 'high';
/**
* Chat options for OpenAI reasoning models, extending OpenAI options.
* @category AI
*/
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;
}
/**
* 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 level of reasoning effort to apply. Defaults to no reasoning. */
reasoningEffort?: AiReasoningEffort;
}
/**
* Optional settings for an AI session, allowing partial specification of identifiers.
* @category AI
*/
export type AiSessionOptions = Partial<{
/** A unique identifier for tracing the session, if provided. */
traceId: string;
/** The ID of the client initiating the session, if specified. */
clientId: string;
/** The ID of the AI agent involved in the session, if specified. */
agentId: string;
/** The ID of the AI agent involved in starting the session, if specified. */
rootAgentId: string;
}>;
/**
* 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 SquidAiModelName ? BaseAiChatOptions : never;
/**
* @category AI
*/
export type AllAiAgentChatOptions = {
[]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof OpenAiReasoningChatOptions ? OpenAiReasoningChatOptions[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;
};
/**
* Options for observing the status of an AI agent operation.
* @category AI
*/
export interface AiObserveStatusOptions {
/** A unique chat ID for the conversation. */
chatId?: string;
}
/**
* A status message from an AI agent operation.
* @category AI
*/
export interface AiStatusMessage {
/** The ID of the agent generating the status message. */
agentId: string;
/** An optional chat ID associated with the status message. */
chatId?: string;
/** The title or summary of the status message. */
title: string;
/** Optional tags providing additional metadata about the status. */
tags?: Record<string, any>;
}
/**
* The options for the AI agent search method.
* @category AI
*/
export interface AiSearchOptions {
/** 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;
}
/**
* 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: AiContextType;
/** 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: AiContextType;
metadata?: AiContextMetadata;
}
/**
* 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 {
}
/**
* @category AI
*/
export type AiContextType = 'text' | 'file';
/**
* 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;
}
/**
* @category AI
*/
export type AiContextMetadataValue = number | string | boolean | undefined;
/**
* @category AI
*/
export type AiContextMetadataValueArray = AiContextMetadataValue[];
interface AiContextMetadataEqFilter {
$eq: AiContextMetadataValue;
}
interface AiContextMetadataNeFilter {
$ne: AiContextMetadataValue;
}
interface AiContextMetadataGtFilter {
$gt: number;
}
interface AiContextMetadataGteFilter {
$gte: number;
}
interface AiContextMetadataLtFilter {
$lt: number;
}
interface AiContextMetadataLteFilter {
$lte: number;
}
interface AiContextMetadataInFilter {
$in: AiContextMetadataValueArray;
}
interface AiContextMetadataNinFilter {
$nin: AiContextMetadataValueArray;
}
interface AiContextMetadataExistsFilter {
$exists: boolean;
}
/**
* @category AI
*/
export type AiContextMetadataSimpleFilter = AiContextMetadataEqFilter | AiContextMetadataNeFilter | AiContextMetadataGtFilter | AiContextMetadataGteFilter | AiContextMetadataLtFilter | AiContextMetadataLteFilter | AiContextMetadataInFilter | AiContextMetadataNinFilter | AiContextMetadataExistsFilter;
/**
* A filter for AI context metadata based on field-specific conditions or values.
* @category AI
*/
export interface AiContextMetadataFieldFilter {
/** A record where keys are field names and values are either simple filters or direct metadata values. */
[]: AiContextMetadataSimpleFilter | AiContextMetadataValue;
}
/**
* A filter combining multiple AI context metadata filters with a logical AND operation.
* @category AI
*/
export interface AiContextMetadataAndFilter {
/** An array of filters that must all be true for the condition to pass. */
$and: AiContextMetadataFilter[];
}
/**
* A filter combining multiple AI context metadata filters with a logical OR operation.
* @category AI
*/
export interface AiContextMetadataOrFilter {
/** An array of filters where at least one must be true for the condition to pass. */
$or: AiContextMetadataFilter[];
}
/**
* @category AI
*/
export type AiContextMetadataFilter = AiContextMetadataFieldFilter | AiContextMetadataAndFilter | AiContextMetadataOrFilter;
/**
* 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;
};
/**
* A record of metadata key-value pairs for AI context, where values are primitive types or undefined.
* @category AI
*/
export type AiContextMetadata = Record<string, AiContextMetadataValue>;
/**
* @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;
}
/** 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>>;
}
export {};