@convex-dev/agent/dist/client/search.d.ts

A agent component for Convex.

import { type EmbeddingModel, type ModelMessage } from "ai";
import type { MessageDoc } from "../validators.js";
import { type VectorDimension } from "../component/vector/tables.js";
import type { Message } from "../validators.js";
import type { AgentComponent, Config, ContextOptions, Options, QueryCtx, MutationCtx, ActionCtx } from "./types.js";
export type GetEmbedding = (text: string) => Promise<{
    embedding: number[];
    textEmbeddingModel: string | EmbeddingModel<string>;
}>;
/**
 * Fetch the context messages for a thread.
 * @param ctx Either a query, mutation, or action ctx.
 *   If it is not an action context, you can't do text or
 *   vector search.
 * @param args The associated thread, user, message
 * @returns
 */
export declare function fetchContextMessages(ctx: QueryCtx | MutationCtx | ActionCtx, component: AgentComponent, args: {
    userId: string | undefined;
    threadId: string | undefined;
    /**
     * If targetMessageId is not provided, this text will be used
     * for text and vector search
     */
    searchText?: string;
    /**
     * If provided, it will use this message for text/vector search (if enabled)
     * and will only fetch messages up to (and including) this message's "order"
     */
    targetMessageId?: string;
    /**
     * @deprecated use searchText and targetMessageId instead
     */
    messages?: (ModelMessage | Message)[];
    /**
     * @deprecated use targetMessageId instead
     */
    upToAndIncludingMessageId?: string;
    contextOptions: ContextOptions;
    getEmbedding?: GetEmbedding;
}): Promise<MessageDoc[]>;
export declare function fetchRecentAndSearchMessages(ctx: QueryCtx | MutationCtx | ActionCtx, component: AgentComponent, args: {
    userId: string | undefined;
    threadId: string | undefined;
    /**
     * If targetMessageId is not provided, this text will be used
     * for text and vector search
     */
    searchText?: string;
    /**
     * If provided, it will use this message for text/vector search (if enabled)
     * and will only fetch messages up to (and including) this message's "order"
     */
    targetMessageId?: string;
    /**
     * @deprecated use searchText and targetMessageId instead
     */
    messages?: (ModelMessage | Message)[];
    /**
     * @deprecated use targetMessageId instead
     */
    upToAndIncludingMessageId?: string;
    contextOptions: ContextOptions;
    getEmbedding?: GetEmbedding;
}): Promise<{
    recentMessages: MessageDoc[];
    searchMessages: MessageDoc[];
}>;
/**
 * Filter out tool messages that don't have both a tool call and response.
 * @param docs The messages to filter.
 * @returns The filtered messages.
 */
export declare function filterOutOrphanedToolMessages(docs: MessageDoc[]): {
    id?: string | undefined;
    userId?: string | undefined;
    embeddingId?: string | undefined;
    fileIds?: string[] | undefined;
    error?: string | undefined;
    agentName?: string | undefined;
    model?: string | undefined;
    provider?: string | undefined;
    providerOptions?: Record<string, Record<string, any>> | undefined;
    message?: {
        providerOptions?: Record<string, Record<string, any>> | undefined;
        role: "user";
        content: string | ({
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            type: "text";
            text: string;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            mimeType?: string | undefined;
            type: "image";
            image: string | ArrayBuffer;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            filename?: string | undefined;
            type: "file";
            mimeType: string;
            data: string | ArrayBuffer;
        })[];
    } | {
        providerOptions?: Record<string, Record<string, any>> | undefined;
        role: "assistant";
        content: string | ({
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            type: "text";
            text: string;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            filename?: string | undefined;
            type: "file";
            mimeType: string;
            data: string | ArrayBuffer;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            signature?: string | undefined;
            type: "reasoning";
            text: string;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            type: "redacted-reasoning";
            data: string;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            providerExecuted?: boolean | undefined;
            type: "tool-call";
            toolCallId: string;
            toolName: string;
            args: any;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            args?: any;
            providerExecuted?: boolean | undefined;
            output?: {
                type: "text";
                value: string;
            } | {
                type: "json";
                value: any;
            } | {
                type: "error-text";
                value: string;
            } | {
                type: "error-json";
                value: any;
            } | {
                type: "content";
                value: ({
                    type: "text";
                    text: string;
                } | {
                    type: "media";
                    data: string;
                    mediaType: string;
                })[];
            } | undefined;
            result?: any;
            isError?: boolean | undefined;
            experimental_content?: ({
                type: "text";
                text: string;
            } | {
                mimeType?: string | undefined;
                type: "image";
                data: string;
            })[] | undefined;
            type: "tool-result";
            toolCallId: string;
            toolName: string;
        } | {
            title?: string | undefined;
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            id: string;
            type: "source";
            sourceType: "url";
            url: string;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            filename?: string | undefined;
            id: string;
            title: string;
            type: "source";
            mediaType: string;
            sourceType: "document";
        })[];
    } | {
        providerOptions?: Record<string, Record<string, any>> | undefined;
        role: "tool";
        content: {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            args?: any;
            providerExecuted?: boolean | undefined;
            output?: {
                type: "text";
                value: string;
            } | {
                type: "json";
                value: any;
            } | {
                type: "error-text";
                value: string;
            } | {
                type: "error-json";
                value: any;
            } | {
                type: "content";
                value: ({
                    type: "text";
                    text: string;
                } | {
                    type: "media";
                    data: string;
                    mediaType: string;
                })[];
            } | undefined;
            result?: any;
            isError?: boolean | undefined;
            experimental_content?: ({
                type: "text";
                text: string;
            } | {
                mimeType?: string | undefined;
                type: "image";
                data: string;
            })[] | undefined;
            type: "tool-result";
            toolCallId: string;
            toolName: string;
        }[];
    } | {
        providerOptions?: Record<string, Record<string, any>> | undefined;
        role: "system";
        content: string;
    } | undefined;
    text?: string | undefined;
    providerMetadata?: Record<string, Record<string, any>> | undefined;
    reasoning?: string | undefined;
    usage?: {
        reasoningTokens?: number | undefined;
        cachedInputTokens?: number | undefined;
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
    } | undefined;
    sources?: ({
        title?: string | undefined;
        type?: "source" | undefined;
        providerOptions?: Record<string, Record<string, any>> | undefined;
        providerMetadata?: Record<string, Record<string, any>> | undefined;
        id: string;
        sourceType: "url";
        url: string;
    } | {
        providerOptions?: Record<string, Record<string, any>> | undefined;
        providerMetadata?: Record<string, Record<string, any>> | undefined;
        filename?: string | undefined;
        id: string;
        title: string;
        type: "source";
        mediaType: string;
        sourceType: "document";
    })[] | undefined;
    warnings?: ({
        details?: string | undefined;
        type: "unsupported-setting";
        setting: string;
    } | {
        details?: string | undefined;
        type: "unsupported-tool";
        tool: any;
    } | {
        type: "other";
        message: string;
    })[] | undefined;
    finishReason?: "length" | "error" | "other" | "stop" | "content-filter" | "tool-calls" | "unknown" | undefined;
    reasoningDetails?: ({
        providerOptions?: Record<string, Record<string, any>> | undefined;
        providerMetadata?: Record<string, Record<string, any>> | undefined;
        signature?: string | undefined;
        type: "reasoning";
        text: string;
    } | {
        signature?: string | undefined;
        type: "text";
        text: string;
    } | {
        type: "redacted";
        data: string;
    })[] | undefined;
    _id: string;
    _creationTime: number;
    status: "pending" | "success" | "failed";
    order: number;
    threadId: string;
    stepOrder: number;
    tool: boolean;
}[];
/**
 * Embed a list of messages, including calling any usage handler.
 * This will not save the embeddings to the database.
 */
export declare function embedMessages(ctx: ActionCtx, { userId, threadId, ...options }: {
    userId: string | undefined;
    threadId: string | undefined;
    agentName?: string;
} & Pick<Config, "usageHandler" | "textEmbeddingModel" | "callSettings">, messages: (ModelMessage | Message)[]): Promise<{
    vectors: (number[] | null)[];
    dimension: VectorDimension;
    model: string;
} | undefined>;
/**
 * Embeds many strings, calling any usage handler.
 * @param ctx The ctx parameter to an action.
 * @param args Arguments to AI SDK's embedMany, and context for the embedding,
 *   passed to the usage handler.
 * @returns The embeddings for the strings, matching the order of the values.
 */
export declare function embedMany(ctx: ActionCtx, { userId, threadId, values, abortSignal, headers, agentName, usageHandler, textEmbeddingModel, callSettings, }: {
    userId: string | undefined;
    threadId: string | undefined;
    values: string[];
    abortSignal?: AbortSignal;
    headers?: Record<string, string>;
    agentName?: string;
} & Pick<Config, "usageHandler" | "textEmbeddingModel" | "callSettings">): Promise<{
    embeddings: number[][];
}>;
/**
 * Embed a list of messages, and save the embeddings to the database.
 * @param ctx The ctx parameter to an action.
 * @param component The agent component, usually components.agent.
 * @param args The context for the embedding, passed to the usage handler.
 * @param messages The messages to embed, in the Agent MessageDoc format.
 */
export declare function generateAndSaveEmbeddings(ctx: ActionCtx, component: AgentComponent, args: {
    threadId: string | undefined;
    userId: string | undefined;
    agentName?: string;
    textEmbeddingModel: EmbeddingModel<string>;
} & Pick<Config, "usageHandler" | "callSettings">, messages: MessageDoc[]): Promise<void>;
/**
 * Similar to fetchContextMessages, but also combines the input messages,
 * with search context, recent messages, input messages, then prompt messages.
 * If there is a promptMessageId and prompt message(s) provided, it will splice
 * the prompt messages into the history to replace the promptMessageId message,
 * but still be followed by any existing messages that were in response to the
 * promptMessageId message.
 */
export declare function fetchContextWithPrompt(ctx: ActionCtx, component: AgentComponent, args: {
    prompt: string | (ModelMessage | Message)[] | undefined;
    messages: (ModelMessage | Message)[] | undefined;
    promptMessageId: string | undefined;
    userId: string | undefined;
    threadId: string | undefined;
    agentName?: string;
} & Options & Config): Promise<{
    messages: ModelMessage[];
    order: number | undefined;
    stepOrder: number | undefined;
}>;
export declare function getPromptArray(prompt: string | (ModelMessage | Message)[] | undefined): (ModelMessage | Message)[];
//# sourceMappingURL=search.d.ts.map