@squidcloud/client/dist/internal-common/src/public-types/ai-query.public-types.d.ts

A typescript implementation of the Squid client

import { AiAgentMemoryOptions, AiChatOptions, AiFileUrl, AiSessionContext } from './ai-agent.public-types';
import { ApiOptions } from './api-client.public-types';
import { AiAgentId, IntegrationId } from './communication.public-types';
import { PartialBy } from './typescript.public-types';
/** A single output column descriptor in a raw query result file. */
export interface AiQueryResultFieldSchema {
    /** Column name as it appears in the query result. */
    name: string;
    /** Data type of the column (e.g. "varchar", "int", "decimal"). */
    type: string;
    /** Human-readable description of what the column represents. */
    desc: string;
}
/**
 * Options for configuring AI query execution.
 * @category AI
 */
export interface AiQueryOptions {
    /**
     * Custom instructions to modify AI query generation behavior.
     * Used for all stages unless there is a per-stage override.
     */
    instructions?: string;
    /** Whether to enable raw results output. */
    enableRawResults?: boolean;
    /** Options for the collection selection stage. */
    selectCollectionsOptions?: AiQuerySelectCollectionsOptions;
    /** Options for the query generation stage. */
    generateQueryOptions?: AiQueryGenerateQueryOptions;
    /** Options to specify how the query result should be analyzed (processed) before returning it to the user. */
    analyzeResultsOptions?: AiQueryAnalyzeResultsOptions;
    /** Session information for the AI query execution. */
    sessionContext?: PartialBy<AiSessionContext, 'agentId'>;
    /** memory options */
    memoryOptions?: AiAgentMemoryOptions;
    /** When true, returns generated queries without executing or analyzing them. Default: false. */
    generateQueriesOnly?: boolean;
    /** Optional AI validation of generated queries. Can be used independently or with generateQueriesOnly. */
    validateWithAiOptions?: AiQueryValidateWithAiOptions;
}
/**
 * Request to execute an AI query using a specific integration.
 * Supports additional query execution options.
 * @category AI
 */
export interface AiQueryRequest {
    /** ID of the integration to execute the AI query. */
    integrationId: IntegrationId;
    /** User-provided prompt for the AI query. */
    prompt: string;
    /** Additional options for query execution. */
    options?: AiQueryOptions;
}
/**
 * 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;
    /**
     * If provided, the AI Query process will use this agent to generate a query.
     */
    agentId?: AiAgentId;
    /**
     * When enabled, allows the AI to ask for clarification instead of attempting to generate
     * a query when the request is ambiguous, too complex, or impossible to answer with the
     * available schema. Default: false.
     */
    allowClarification?: boolean;
}
/** Options for the query result analysis. */
export interface AiQueryAnalyzeResultsOptions {
    /**
     * When set to true, the stage is disabled.
     * The response will contain generated queries, raw results, and a hardcoded text in the answer
     * to check the result files.
     */
    disabled?: boolean;
    /** Enables or disables code interpreter mode. Default: 'false'. */
    enableCodeInterpreter?: boolean;
    /** Customizes AI agent behavior used by the stage. */
    aiOptions?: AiChatOptions;
    /**
     * If provided, the AI Query process will use this agent to analyze the query result and provide the final answer.
     */
    agentId?: AiAgentId;
}
/**
 * Options for AI-based validation of generated queries.
 * @category AI
 */
export interface AiQueryValidateWithAiOptions {
    /** Whether AI validation is enabled. */
    enabled: boolean;
    /** Defaults to the same model used for query generation. */
    aiOptions?: AiChatOptions;
}
/**
 * Information about an executed query.
 * @category AI
 */
export interface ExecutedQueryInfo {
    /** The executed query string. */
    query: string;
    /** Optional description of what this query retrieves. */
    purpose?: string;
    /** Whether this specific query executed successfully. */
    success: boolean;
    /** Raw result file information. Undefined if upload failed or raw results are not enabled. */
    rawResult?: AiFileUrl;
}
/**
 * Response from an AI query execution.
 * Contains the generated answer, optional explanation, and executed query details.
 * @category AI
 */
export interface AiQueryResponse {
    /** AI-generated answer for the query. */
    answer: string;
    /** Optional explanation for the AI-generated answer. */
    explanation?: string;
    /** Executed queries with their details and raw result URLs. */
    executedQueries: ExecutedQueryInfo[];
    /** Markdown format type of the executed query response. */
    queryMarkdownType?: string;
    /**
     * @deprecated Use {@link ExecutedQueryInfo.rawResult} in {@link executedQueries} instead.
     * URL to access raw results from the first executed query. Populated for backward compatibility.
     */
    rawResultsUrl?: string;
    /** Indicates whether the query execution was successful. */
    success: boolean;
    /** Indicates whether a code interpreter was used to analyze the results. */
    usedCodeInterpreter?: boolean;
    /**
     * When the AI needs clarification to generate a query, this field contains the clarification question.
     * Only populated when `generateQueryOptions.allowClarification` is enabled, and the AI determines
     * it cannot generate a valid query without more information.
     */
    clarificationQuestion?: string;
}
/**
 * The AI API call response
 * @category AI
 */
export interface AiApiResult {
    /** ID of the executed API endpoint. */
    endpointId: string;
    /** Name of the executed API endpoint. */
    responseBody: string | object;
    /** Status code of the executed API request. */
    responseStatusCode: number;
    /** Request's body of the executed API request. */
    requestBody: any;
    /** Request options of the executed API request. */
    requestOptions: ApiOptions;
}
/**
 * Response from executing an AI-powered API request.
 * Includes the AI-generated answer and details of executed API calls.
 * @category AI
 */
export interface ExecuteAiApiResponse {
    /** AI-generated answer for the API request. */
    answer: string;
    /** Optional explanation for the AI-generated API response. */
    explanation?: string;
    /** List of executed API requests and their results. */
    executedApis?: Array<AiApiResult>;
    /** Markdown format type of the executed query response. */
    queryMarkdownType?: string;
    /** Indicates whether the API request execution was successful. */
    success: boolean;
}