@convex-dev/agent 0.1.18-alpha.1 → 0.2.0-alpha.2

package/src/client/messages.ts

@@ -0,0 +1,191 @@
+import type { ModelMessage } from "ai";
+import type { PaginationOptions, PaginationResult } from "convex/server";
+import type { MessageDoc } from "../component/schema.js";
+import { validateVectorDimension } from "../component/vector/tables.js";
+import {
+  vMessageWithMetadata,
+  type Message,
+  type MessageEmbeddings,
+  type MessageEmbeddingsWithDimension,
+  type MessageStatus,
+  type MessageWithMetadata,
+} from "../validators.js";
+import { serializeMessage } from "./index.js";
+import type { AgentComponent, RunMutationCtx, RunQueryCtx } from "./types.js";
+import { parse } from "convex-helpers/validators";
+
+/**
+ * List messages from a thread.
+ * @param ctx A ctx object from a query, mutation, or action.
+ * @param component The agent component, usually `components.agent`.
+ * @param args.threadId The thread to list messages from.
+ * @param args.paginationOpts Pagination options (e.g. via usePaginatedQuery).
+ * @param args.excludeToolMessages Whether to exclude tool messages.
+ *   False by default.
+ * @param args.statuses What statuses to include. All by default.
+ * @returns The MessageDoc's in a format compatible with usePaginatedQuery.
+ */
+export async function listMessages(
+  ctx: RunQueryCtx,
+  component: AgentComponent,
+  args: {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+    excludeToolMessages?: boolean;
+    statuses?: MessageStatus[];
+  },
+): Promise<PaginationResult<MessageDoc>> {
+  if (args.paginationOpts.numItems === 0) {
+    return {
+      page: [],
+      isDone: true,
+      continueCursor: args.paginationOpts.cursor ?? "",
+    };
+  }
+  return ctx.runQuery(component.messages.listMessagesByThreadId, {
+    order: "desc",
+    ...args,
+  });
+}
+
+export type SaveMessagesArgs = {
+  threadId: string;
+  userId?: string | null;
+  /**
+   * The message that these messages are in response to. They will be
+   * the same "order" as this message, at increasing stepOrder(s).
+   */
+  promptMessageId?: string;
+  /**
+   * The messages to save.
+   */
+  messages: (ModelMessage | Message)[];
+  /**
+   * Metadata to save with the messages. Each element corresponds to the
+   * message at the same index.
+   */
+  metadata?: Omit<MessageWithMetadata, "message">[];
+  /**
+   * If true, it will fail any pending steps.
+   * Defaults to false.
+   */
+  failPendingSteps?: boolean;
+  /**
+   * The embeddings to save with the messages.
+   */
+  embeddings?: MessageEmbeddings;
+};
+
+/**
+ * Explicitly save messages associated with the thread (& user if provided)
+ */
+export async function saveMessages(
+  ctx: RunMutationCtx,
+  component: AgentComponent,
+  args: SaveMessagesArgs & {
+    /**
+     * The agent name to associate with the messages.
+     */
+    agentName?: string;
+  },
+) {
+  let embeddings: MessageEmbeddingsWithDimension | undefined;
+  if (args.embeddings) {
+    const dimension = args.embeddings.vectors.find((v) => v !== null)?.length;
+    if (dimension) {
+      validateVectorDimension(dimension);
+      embeddings = {
+        model: args.embeddings.model,
+        dimension,
+        vectors: args.embeddings.vectors,
+      };
+    }
+  }
+  const result = await ctx.runMutation(component.messages.addMessages, {
+    threadId: args.threadId,
+    userId: args.userId ?? undefined,
+    agentName: args.agentName,
+    promptMessageId: args.promptMessageId,
+    embeddings,
+    messages: await Promise.all(
+      args.messages.map(async (m, i) => {
+        const { message, fileIds } = await serializeMessage(ctx, component, m);
+        return parse(vMessageWithMetadata, {
+          ...args.metadata?.[i],
+          message,
+          fileIds,
+        });
+      }),
+    ),
+    failPendingSteps: args.failPendingSteps ?? false,
+  });
+  return { messages: result.messages };
+}
+
+export type SaveMessageArgs = {
+  threadId: string;
+  userId?: string | null;
+  /**
+   * Metadata to save with the messages. Each element corresponds to the
+   * message at the same index.
+   */
+  metadata?: Omit<MessageWithMetadata, "message">;
+  /**
+   * The embedding to save with the message.
+   */
+  embedding?: { vector: number[]; model: string };
+} & (
+  | {
+      prompt?: undefined;
+      /**
+       * The message to save.
+       */
+      message: ModelMessage | Message;
+    }
+  | {
+      /*
+       * The prompt to save with the message.
+       */
+      prompt: string;
+      message?: undefined;
+    }
+);
+
+/**
+ * Save a message to the thread.
+ * @param ctx A ctx object from a mutation or action.
+ * @param args The message and what to associate it with (user / thread)
+ * You can pass extra metadata alongside the message, e.g. associated fileIds.
+ * @returns The messageId of the saved message.
+ */
+export async function saveMessage(
+  ctx: RunMutationCtx,
+  component: AgentComponent,
+  args: SaveMessageArgs & {
+    /**
+     * The agent name to associate with the message.
+     */
+    agentName?: string;
+  },
+) {
+  let embeddings: { vectors: number[][]; model: string } | undefined;
+  if (args.embedding && args.embedding.vector) {
+    embeddings = {
+      model: args.embedding.model,
+      vectors: [args.embedding.vector],
+    };
+  }
+  const { messages } = await saveMessages(ctx, component, {
+    threadId: args.threadId,
+    userId: args.userId ?? undefined,
+    agentName: args.agentName,
+    messages:
+      args.prompt !== undefined
+        ? [{ role: "user", content: args.prompt }]
+        : [args.message],
+    metadata: args.metadata ? [args.metadata] : undefined,
+    embeddings,
+  });
+  const message = messages.at(-1)!;
+  return { messageId: message._id, message };
+}

package/src/client/search.ts

@@ -5,19 +5,20 @@ import type {
   RunQueryCtx,
 } from "./types.js";
 import type { MessageDoc } from "../component/schema.js";
-import type { CoreMessage } from "ai";
+import type { EmbeddingModel, LanguageModel, ModelMessage } from "ai";
 import { assert } from "convex-helpers";
 import {
   DEFAULT_MESSAGE_RANGE,
   DEFAULT_RECENT_MESSAGES,
   extractText,
 } from "../shared.js";
+import type { Message } from "../validators.js";
 
 const DEFAULT_VECTOR_SCORE_THRESHOLD = 0.0;
 
 export type GetEmbedding = (text: string) => Promise<{
   embedding: number[];
-  embeddingModel: string;
+  embeddingModel: string | EmbeddingModel<string>;
 }>;
 
 /**
@@ -34,7 +35,7 @@ export async function fetchContextMessages(
   args: {
     userId: string | undefined;
     threadId: string | undefined;
-    messages: CoreMessage[];
+    messages: (ModelMessage | Message)[];
     /**
      * If provided, it will search for messages up to and including this message.
      * Note: if this is far in the past, text and vector search results may be more
@@ -102,13 +103,13 @@ export async function fetchContextMessages(
       component.messages.searchMessages,
       {
         searchAllMessagesForUserId: opts?.searchOtherThreads
-          ? args.userId ??
+          ? (args.userId ??
             (args.threadId &&
               (
                 await ctx.runQuery(component.threads.getThread, {
                   threadId: args.threadId,
                 })
-              )?.userId)
+              )?.userId))
           : undefined,
         threadId: args.threadId,
         beforeMessageId: args.upToAndIncludingMessageId,
@@ -122,7 +123,9 @@ export async function fetchContextMessages(
           opts.searchOptions?.vectorScoreThreshold ??
           DEFAULT_VECTOR_SCORE_THRESHOLD,
         embedding: embeddingFields?.embedding,
-        embeddingModel: embeddingFields?.embeddingModel,
+        embeddingModel: embeddingFields?.embeddingModel
+          ? getModelName(embeddingFields.embeddingModel)
+          : undefined,
       },
     );
     // TODO: track what messages we used for context
@@ -170,3 +173,24 @@ export function filterOutOrphanedToolMessages(docs: MessageDoc[]) {
   }
   return result;
 }
+
+export function getModelName(
+  embeddingModel: string | EmbeddingModel<string> | LanguageModel,
+): string {
+  if (typeof embeddingModel === "string") {
+    if (embeddingModel.includes("/")) {
+      return embeddingModel.split("/").slice(1).join("/");
+    }
+    return embeddingModel;
+  }
+  return embeddingModel.modelId;
+}
+
+export function getProviderName(
+  embeddingModel: string | EmbeddingModel<string> | LanguageModel,
+): string {
+  if (typeof embeddingModel === "string") {
+    return embeddingModel.split("/").at(0)!;
+  }
+  return embeddingModel.provider;
+}

package/src/client/streaming.ts

@@ -9,7 +9,7 @@ import type {
   StreamArgs,
   StreamDelta,
   StreamMessage,
-  TextStreamPart,
+  vTextStreamPartV5,
 } from "../validators.js";
 import type { MessageDoc } from "../component/schema.js";
 import type {
@@ -20,6 +20,7 @@ import type {
   SyncStreamsReturnValue,
 } from "./types.js";
 import { omit } from "convex-helpers";
+import type { Infer } from "convex/values";
 
 /**
  * A function that handles fetching stream deltas, used with the React hooks
@@ -158,7 +159,7 @@ export function mergeTransforms<TOOLS extends ToolSet>(
 export class DeltaStreamer {
   public streamId: string | undefined;
   public readonly options: Required<StreamingOptions>;
-  #nextParts: TextStreamPart[] = [];
+  #nextParts: Infer<typeof vTextStreamPartV5>[] = [];
   #nextOrder: number;
   #nextStepOrder: number;
   #latestWrite: number = 0;
@@ -205,7 +206,7 @@ export class DeltaStreamer {
       });
     }
   }
-  public async addParts(parts: TextStreamPart[]) {
+  public async addParts(parts: Infer<typeof vTextStreamPartV5>[]) {
     if (this.abortController.signal.aborted) {
       return;
     }

package/src/client/threads.ts

@@ -0,0 +1,78 @@
+import type { WithoutSystemFields } from "convex/server";
+import type { ThreadDoc } from "../component/schema.js";
+import type { AgentComponent, RunMutationCtx, RunQueryCtx } from "./types.js";
+
+/**
+ * Create a thread to store messages with an Agent.
+ * @param ctx The context from a mutation or action.
+ * @param component The Agent component, usually `components.agent`.
+ * @param args The associated thread metadata.
+ * @returns The id of the created thread.
+ */
+export async function createThread(
+  ctx: RunMutationCtx,
+  component: AgentComponent,
+  args?: { userId?: string | null; title?: string; summary?: string },
+) {
+  const { _id: threadId } = await ctx.runMutation(
+    component.threads.createThread,
+    {
+      userId: args?.userId ?? undefined,
+      title: args?.title,
+      summary: args?.summary,
+    },
+  );
+  return threadId;
+}
+
+/**
+ * Get the metadata for a thread.
+ * @param ctx A ctx object from a query, mutation, or action.
+ * @param args.threadId The thread to get the metadata for.
+ * @returns The metadata for the thread.
+ */
+export async function getThreadMetadata(
+  ctx: RunQueryCtx,
+  component: AgentComponent,
+  args: { threadId: string },
+): Promise<ThreadDoc> {
+  const thread = await ctx.runQuery(component.threads.getThread, {
+    threadId: args.threadId,
+  });
+  if (!thread) {
+    throw new Error("Thread not found");
+  }
+  return thread;
+}
+
+export async function updateThreadMetadata(
+  ctx: RunMutationCtx,
+  component: AgentComponent,
+  args: { threadId: string; patch: Partial<WithoutSystemFields<ThreadDoc>> },
+) {
+  return ctx.runMutation(component.threads.updateThread, {
+    threadId: args.threadId,
+    patch: args.patch,
+  });
+}
+
+/**
+ * Search for threads by title, paginated.
+ * @param ctx The context passed from the query/mutation/action.
+ * @returns The threads matching the search, paginated.
+ */
+export async function searchThreadTitles(
+  ctx: RunQueryCtx,
+  component: AgentComponent,
+  {
+    userId,
+    query,
+    limit,
+  }: { userId?: string | undefined; query: string; limit?: number },
+): Promise<ThreadDoc[]> {
+  return ctx.runQuery(component.threads.searchThreadTitles, {
+    userId,
+    query,
+    limit: limit ?? 10,
+  });
+}

package/src/client/types.ts

@@ -1,5 +1,6 @@
+import type { LanguageModelV2 } from "@ai-sdk/provider";
 import type {
-  CoreMessage,
+  ModelMessage,
   DeepPartial,
   generateObject,
   GenerateObjectResult,
@@ -8,7 +9,6 @@ import type {
   JSONValue,
   LanguageModelRequestMetadata,
   LanguageModelResponseMetadata,
-  LanguageModelV1,
   RepairTextFunction,
   streamObject,
   StreamObjectResult,
@@ -17,6 +17,8 @@ import type {
   TelemetrySettings,
   ToolChoice,
   ToolSet,
+  Schema,
+  LanguageModelUsage,
 } from "ai";
 import type {
   Auth,
@@ -31,16 +33,15 @@ import type {
   GenericDataModel,
 } from "convex/server";
 import type { GenericId } from "convex/values";
-import type { Schema } from "zod";
+import type { z } from "zod/v3";
 import type { Mounts } from "../component/_generated/api.js";
-import type { ThreadDoc } from "../component/schema.js";
+import type { MessageDoc, ThreadDoc } from "../component/schema.js";
 import type {
   CallSettings,
   ProviderMetadata,
   ProviderOptions,
   StreamDelta,
   StreamMessage,
-  Usage,
 } from "../validators.js";
 import type { StreamingOptions } from "./streaming.js";
 
@@ -114,7 +115,21 @@ export type StorageOptions = {
   saveMessages?: "all" | "none" | "promptAndOutput";
 };
 
-export type GenerationOutputMetadata = { messageId?: string; order?: number };
+export type GenerationOutputMetadata = {
+  /**
+   * The ID of the prompt message for the generation.
+   */
+  messageId?: string;
+  /**
+   * The order of the prompt message for the generation.
+   */
+  order?: number;
+  /**
+   * The messages saved for the generation - both saved input and output.
+   * If you passed promptMessageId, it will not include that message.
+   */
+  messages?: MessageDoc[];
+};
 
 export type UsageHandler = (
   ctx: RunActionCtx,
@@ -122,7 +137,7 @@ export type UsageHandler = (
     userId: string | undefined;
     threadId: string | undefined;
     agentName: string | undefined;
-    usage: Usage;
+    usage: LanguageModelUsage;
     // Often has more information, like cached token usage in the case of openai.
     providerMetadata: ProviderMetadata | undefined;
     model: string;
@@ -169,7 +184,7 @@ export type TextArgs<
    * The model to use for the LLM calls. This will override the model specified
    * in the Agent constructor.
    */
-  model?: LanguageModelV1;
+  model?: LanguageModelV2;
   /**
    * The tools to use for the tool calls. This will override tools specified
    * in the Agent constructor or createThread / continueThread.
@@ -208,7 +223,7 @@ export type StreamingTextArgs<
    * The model to use for the tool calls. This will override the model specified
    * in the Agent constructor.
    */
-  model?: LanguageModelV1;
+  model?: LanguageModelV2;
   /**
    * The tools to use for the tool calls. This will override tools specified
    * in the Agent constructor or createThread / continueThread.
@@ -226,7 +241,7 @@ type BaseGenerateObjectOptions = CallSettings & {
    * The model to use for the object generation. This will override the model
    * specified in the Agent constructor.
    */
-  model?: LanguageModelV1;
+  model?: LanguageModelV2;
   /**
    * The system prompt to use for the object generation. This will override the
    * system prompt specified in the Agent constructor.
@@ -236,13 +251,13 @@ type BaseGenerateObjectOptions = CallSettings & {
    * The prompt to the LLM to use for the object generation.
    * Specify this or messages, but not both.
    */
-  prompt?: string;
+  prompt?: string | Array<ModelMessage>;
   /**
    * The messages to use for the object generation.
    * Note: recent messages are automatically added based on the thread it's
    * associated with and your contextOptions.
    */
-  messages?: CoreMessage[];
+  messages?: Array<ModelMessage>;
   /**
    * The message to use as the "prompt" for the object generation.
    * If this is provided, it will be used instead of the prompt or messages.
@@ -256,52 +271,28 @@ type BaseGenerateObjectOptions = CallSettings & {
   experimental_providerMetadata?: ProviderMetadata;
 };
 
-type GenerateObjectObjectOptions<T extends Record<string, unknown>> =
-  BaseGenerateObjectOptions & {
-    output?: "object";
-    mode?: "auto" | "json" | "tool";
-    schema: Schema<T>;
-    schemaName?: string;
-    schemaDescription?: string;
-  };
-
-type GenerateObjectArrayOptions<T> = BaseGenerateObjectOptions & {
-  output: "array";
-  mode?: "auto" | "json" | "tool";
-  schema: Schema<T>;
+type StandardGenerateObjectOptions<T> = {
+  schema: z.Schema<T>;
   schemaName?: string;
   schemaDescription?: string;
-};
-
-type GenerateObjectWithEnumOptions<T extends string> =
-  BaseGenerateObjectOptions & {
-    output: "enum";
-    enum: Array<T>;
-    mode?: "auto" | "json" | "tool";
-  };
-
-type GenerateObjectNoSchemaOptions = BaseGenerateObjectOptions & {
-  schema?: undefined;
-  mode?: "json";
+  output?: "object" | "array";
+  mode?: "auto" | "json" | "tool";
 };
 
 // TODO: simplify this to just use the generateObject args, with an optional
 // model and tool/toolChoice types
-type GenerateObjectArgs<T> =
-  T extends Record<string, unknown>
-    ? GenerateObjectObjectOptions<T>
-    : T extends Array<unknown>
-      ? GenerateObjectArrayOptions<T>
-      : T extends string
-        ? GenerateObjectWithEnumOptions<T>
-        : GenerateObjectNoSchemaOptions;
+type GenerateObjectArgs<T> = BaseGenerateObjectOptions &
+  (
+    | StandardGenerateObjectOptions<T>
+    | { output: "enum"; enum: Array<T>; mode?: "auto" | "json" | "tool" }
+    | { output: "any"; schema: undefined; mode: "json" }
+  );
 
-type StreamObjectArgs<T> =
-  T extends Record<string, unknown>
-    ? GenerateObjectObjectOptions<T>
-    : T extends Array<unknown>
-      ? GenerateObjectArrayOptions<T>
-      : GenerateObjectNoSchemaOptions;
+type StreamObjectArgs<T> = BaseGenerateObjectOptions &
+  (
+    | StandardGenerateObjectOptions<T>
+    | { output: "any"; schema: undefined; mode: "json" }
+  );
 
 export type OurObjectArgs<T> = GenerateObjectArgs<T> &
   Pick<
@@ -310,11 +301,12 @@ export type OurObjectArgs<T> = GenerateObjectArgs<T> &
     "experimental_repairText" | "abortSignal"
   >;
 
-export type OurStreamObjectArgs<T> = StreamObjectArgs<T> &
-  Pick<
-    Parameters<typeof streamObject<T>>[0],
-    "onError" | "onFinish" | "abortSignal"
-  >;
+export type OurStreamObjectArgs<T extends Schema | z.Schema> =
+  StreamObjectArgs<T> &
+    Pick<
+      Parameters<typeof streamObject<T>>[0],
+      "onError" | "onFinish" | "abortSignal"
+    >;
 
 type ThreadOutputMetadata = Required<GenerationOutputMetadata>;
 
@@ -415,24 +407,10 @@ export interface Thread<DefaultTools extends ToolSet> {
    * for the {@link ContextOptions} and {@link StorageOptions}.
    * @returns The result of the generateObject function.
    */
-  generateObject<T>(
+  generateObject<T = JSONValue>(
     args: OurObjectArgs<T>,
     options?: Options,
   ): Promise<GenerateObjectResult<T> & ThreadOutputMetadata>;
-  /**
-   * This behaves like {@link generateObject} from the "ai" package except that
-   * it add context based on the userId and threadId and saves the input and
-   * resulting messages to the thread, if specified. This overload is for when there's no schema.
-   * Use {@link continueThread} to get a version of this function already scoped
-   * to a thread (and optionally userId).
-   * @param args The arguments to the generateObject function, along with extra controls
-   * for the {@link ContextOptions} and {@link StorageOptions}.
-   * @returns The result of the generateObject function.
-   */
-  generateObject(
-    args: GenerateObjectNoSchemaOptions,
-    options?: Options,
-  ): Promise<GenerateObjectResult<JSONValue> & ThreadOutputMetadata>;
   /**
    * This behaves like {@link streamObject} from the "ai" package except that
    * it add context based on the userId and threadId and saves the input and
@@ -443,7 +421,7 @@ export interface Thread<DefaultTools extends ToolSet> {
    * for the {@link ContextOptions} and {@link StorageOptions}.
    * @returns The result of the streamObject function.
    */
-  streamObject<T>(
+  streamObject<T extends z.Schema | Schema>(
     args: OurStreamObjectArgs<T>,
     options?: Options,
   ): Promise<