@convex-dev/agent 0.0.1 → 0.0.3-alpha.0

package/src/component/_generated/api.d.ts

@@ -169,6 +169,7 @@ export type Mounts = {
             | string
             | string
             | string;
+          error?: string;
           fileId?: string;
           id?: string;
           message?:
@@ -293,6 +294,7 @@ export type Mounts = {
             | string
             | string
             | string;
+          error?: string;
           fileId?: string;
           id?: string;
           message?:
@@ -1058,6 +1060,7 @@ export type Mounts = {
             | string
             | string
             | string;
+          error?: string;
           fileId?: string;
           id?: string;
           message?:
@@ -1230,6 +1233,7 @@ export type Mounts = {
           | string
           | string
           | string;
+        error?: string;
         fileId?: string;
         id?: string;
         message?:
@@ -1359,6 +1363,7 @@ export type Mounts = {
           | string
           | string
           | string;
+        error?: string;
         fileId?: string;
         id?: string;
         message?:

package/src/component/messages.ts

@@ -401,6 +401,7 @@ async function addMessagesHandler(
     ...rest
   } = args;
   const parent = parentMessageId && (await ctx.db.get(parentMessageId));
+  // TODO: I think this is a bug - parent will be pending always?
   if (failPendingSteps && parent?.status !== "pending") {
     assert(args.threadId, "threadId is required to fail pending steps");
     const pendingMessages = await ctx.db
@@ -594,7 +595,7 @@ export const rollbackMessage = mutation({
     }
     await ctx.db.patch(messageId, {
       status: "failed",
-      text: error ?? message.text,
+      error: error,
     });
   },
 });

package/src/component/schema.ts

@@ -27,6 +27,7 @@ export const schema = defineSchema({
     stepId: v.optional(v.id("steps")),
     agentName: v.optional(v.string()),
     message: v.optional(vMessage),
+    error: v.optional(v.string()),
     model: v.optional(v.string()),
     text: v.optional(v.string()),
     embeddingId: v.optional(vVectorId),

package/src/component/vector/index.ts

@@ -1,12 +1,6 @@
 import { paginator } from "convex-helpers/server/pagination";
 import { v } from "convex/values";
-import {
-  ActionCtx,
-  mutation,
-  MutationCtx,
-  query,
-  QueryCtx,
-} from "../_generated/server";
+import { ActionCtx, mutation, MutationCtx, query } from "../_generated/server";
 import {
   EmbeddingsWithoutDenormalizedFields,
   getVectorTableName,

package/src/logging.ts

@@ -0,0 +1,103 @@
+import { v, Infer } from "convex/values";
+
+export const DEFAULT_LOG_LEVEL: LogLevel = "WARN";
+
+// NOTE: the ordering here is important! A config level of "INFO" will log
+// "INFO", "REPORT", "WARN",and "ERROR" events.
+export const logLevel = v.union(
+  v.literal("DEBUG"),
+  v.literal("TRACE"),
+  v.literal("INFO"),
+  v.literal("REPORT"),
+  v.literal("WARN"),
+  v.literal("ERROR"),
+);
+export type LogLevel = Infer<typeof logLevel>;
+
+export type Logger = {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  log: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  time: (label: string) => void;
+  timeEnd: (label: string) => void;
+  event: (event: string, payload: Record<string, unknown>) => void;
+  logLevel: LogLevel;
+};
+
+const logLevelOrder = logLevel.members.map((l) => l.value);
+const logLevelByName = logLevelOrder.reduce(
+  (acc, l, i) => {
+    acc[l] = i;
+    return acc;
+  },
+  {} as Record<LogLevel, number>,
+);
+export function shouldLog(config: LogLevel, level: LogLevel) {
+  return logLevelByName[config] <= logLevelByName[level];
+}
+const DEBUG = logLevelByName["DEBUG"];
+const TRACE = logLevelByName["TRACE"];
+const INFO = logLevelByName["INFO"];
+const REPORT = logLevelByName["REPORT"];
+const WARN = logLevelByName["WARN"];
+const ERROR = logLevelByName["ERROR"];
+
+export function createLogger(level?: LogLevel): Logger {
+  const logLevel = level ?? DEFAULT_LOG_LEVEL;
+  const levelIndex = logLevelByName[logLevel];
+  if (levelIndex === undefined) {
+    throw new Error(`Invalid log level: ${logLevel}`);
+  }
+  return {
+    logLevel,
+    debug: (...args: unknown[]) => {
+      if (levelIndex <= DEBUG) {
+        console.debug(...args);
+      }
+    },
+    log: (...args: unknown[]) => {
+      if (levelIndex <= INFO) {
+        console.log(...args);
+      }
+    },
+    info: (...args: unknown[]) => {
+      if (levelIndex <= INFO) {
+        console.info(...args);
+      }
+    },
+    warn: (...args: unknown[]) => {
+      if (levelIndex <= WARN) {
+        console.warn(...args);
+      }
+    },
+    error: (...args: unknown[]) => {
+      if (levelIndex <= ERROR) {
+        console.error(...args);
+      }
+    },
+    time: (label: string) => {
+      if (levelIndex <= TRACE) {
+        console.time(label);
+      }
+    },
+    timeEnd: (label: string) => {
+      if (levelIndex <= TRACE) {
+        console.timeEnd(label);
+      }
+    },
+    event: (event: string, payload: Record<string, unknown>) => {
+      const fullPayload = {
+        component: "workflow",
+        event,
+        ...payload,
+      };
+      if (levelIndex === REPORT && event === "report") {
+        console.info(JSON.stringify(fullPayload));
+      } else if (levelIndex <= INFO) {
+        console.info(JSON.stringify(fullPayload));
+      }
+    },
+  };
+}

package/src/mapping.ts

@@ -1,10 +1,9 @@
 import {
   convertToCoreMessages,
   coreMessageSchema,
+  GenerateObjectResult,
   type AssistantContent,
-  type CoreAssistantMessage,
   type CoreMessage,
-  type CoreToolMessage,
   type DataContent,
   type GenerateTextResult,
   type StepResult,
@@ -13,8 +12,12 @@ import {
   type Message as UIMessage,
   type UserContent,
 } from "ai";
-import { MessageWithFileAndId, Step } from "./validators";
 import { assert } from "convex-helpers";
+import {
+  MessageWithFileAndId,
+  Step,
+  StepWithMessagesWithFileAndId,
+} from "./validators";
 
 export type SerializeUrlsAndUint8Arrays<T> = T extends URL
   ? string
@@ -66,15 +69,6 @@ export function serializeContent(content: Content): SerializedContent {
   return serialized as SerializedContent;
 }
 
-export function serializeResponse<TOOLS extends ToolSet, OUTPUT>(
-  response: GenerateTextResult<TOOLS, OUTPUT>["response"]
-): { message: SerializedMessage; id?: string }[] {
-  const { id, timestamp, modelId, headers, messages, body } = response;
-  // TODO: what to do about all the rest?
-  // Store body?
-  return messages.map((m) => serializeMessageWithId(m));
-}
-
 export function serializeStep<TOOLS extends ToolSet>(
   step: StepResult<TOOLS>
 ): Step {
@@ -86,7 +80,7 @@ export function serializeStep<TOOLS extends ToolSet>(
     ...step.response,
     messages: content,
     timestamp,
-    headers: {},
+    headers: {}, // these are large and low value
   };
   return {
     ...step,
@@ -115,6 +109,41 @@ export function serializeNewMessagesInStep<TOOLS extends ToolSet>(
   return messages;
 }
 
+export function serializeObjectResult(
+  result: GenerateObjectResult<unknown>
+): StepWithMessagesWithFileAndId {
+  const text = JSON.stringify(result.object);
+  const serializedMessage = serializeMessageWithId({
+    role: "assistant" as const,
+    content: text,
+    id: result.response.id,
+  });
+
+  const messages = [serializedMessage];
+
+  return {
+    messages,
+    step: {
+      text,
+      isContinued: false,
+      stepType: "initial",
+      toolCalls: [],
+      toolResults: [],
+      usage: result.usage,
+      warnings: result.warnings,
+      finishReason: result.finishReason,
+      request: result.request,
+      response: {
+        ...result.response,
+        timestamp: result.response.timestamp.getTime(),
+        messages,
+      },
+      providerMetadata: result.providerMetadata,
+      experimental_providerMetadata: result.experimental_providerMetadata,
+    },
+  };
+}
+
 export function deserializeContent(content: SerializedContent): Content {
   if (typeof content === "string") {
     return content;
@@ -172,23 +201,26 @@ export function promptOrMessagesToCoreMessages(args: {
   if (args.system) {
     messages.push({ role: "system", content: args.system });
   }
-  if (!args.messages) {
-    assert(args.prompt, "messages or prompt is required");
+  assert(args.prompt || args.messages, "messages or prompt is required");
+  if (args.messages) {
+    if (
+      args.messages.some(
+        (m) =>
+          typeof m === "object" &&
+          m !== null &&
+          (m.role === "data" || // UI-only role
+            "toolInvocations" in m || // UI-specific field
+            "parts" in m || // UI-specific field
+            "experimental_attachments" in m)
+      )
+    ) {
+      messages.push(...convertToCoreMessages(args.messages as UIMessage[]));
+    } else {
+      messages.push(...coreMessageSchema.array().parse(args.messages));
+    }
+  }
+  if (args.prompt) {
     messages.push({ role: "user", content: args.prompt });
-  } else if (
-    args.messages.some(
-      (m) =>
-        typeof m === "object" &&
-        m !== null &&
-        (m.role === "data" || // UI-only role
-          "toolInvocations" in m || // UI-specific field
-          "parts" in m || // UI-specific field
-          "experimental_attachments" in m)
-    )
-  ) {
-    messages.push(...convertToCoreMessages(args.messages as UIMessage[]));
-  } else {
-    messages.push(...coreMessageSchema.array().parse(args.messages));
   }
   assert(messages.length > 0, "Messages must contain at least one message");
   return messages;

package/src/validators.ts

@@ -1,10 +1,12 @@
-import { Infer, v } from "convex/values";
+import { Infer, ObjectType, v } from "convex/values";
 import { vVectorDimension } from "./component/vector/tables";
 
 // const deprecated = v.optional(v.any()) as unknown as VNull<unknown, "optional">;
 
 const providerOptions = v.optional(v.record(v.string(), v.any()));
+export type ProviderOptions = Infer<typeof providerOptions>;
 const experimental_providerMetadata = providerOptions;
+export type ProviderMetadata = Infer<typeof experimental_providerMetadata>;
 
 export const vThreadStatus = v.union(
   v.literal("active"),
@@ -186,6 +188,14 @@ export const vResponse = v.object({
   body: v.optional(v.any()),
 });
 
+export const vResponseWithoutMessages = v.object({
+  id: v.string(),
+  timestamp: v.number(),
+  modelId: v.string(),
+  headers: v.optional(v.record(v.string(), v.string())), // clear these?
+  body: v.optional(v.any()),
+});
+
 export const vFinishReason = v.union(
   v.literal("stop"),
   v.literal("length"),
@@ -250,6 +260,18 @@ export const vStepWithMessages = v.object({
 });
 export type StepWithMessagesWithFileAndId = Infer<typeof vStepWithMessages>;
 
+export const vObjectResult = v.object({
+  request: vRequest,
+  response: vResponseWithoutMessages,
+  finishReason: vFinishReason,
+  usage: v.optional(v.any()),
+  object: v.any(),
+  error: v.optional(v.string()),
+  warnings: v.optional(v.array(vLanguageModelV1CallWarning)),
+  providerMetadata: providerOptions,
+  experimental_providerMetadata,
+});
+export type ObjectResult = Infer<typeof vObjectResult>;
 export const vSearchOptions = v.object({
   vector: v.optional(v.array(v.number())),
   vectorModel: v.optional(v.string()),
@@ -279,18 +301,89 @@ export const vStorageOptions = v.object({
   saveAllOutputMessages: v.optional(v.boolean()),
 });
 
-export const vThreadArgs = v.object({
-  maxSteps: v.optional(v.number()),
+const vPromptFields = {
+  system: v.optional(v.string()),
   prompt: v.optional(v.string()),
   messages: v.optional(v.array(vMessage)),
-});
+};
+
+export const vCallSettingsFields = {
+  maxTokens: v.optional(v.number()),
+  temperature: v.optional(v.number()),
+  topP: v.optional(v.number()),
+  topK: v.optional(v.number()),
+  presencePenalty: v.optional(v.number()),
+  frequencyPenalty: v.optional(v.number()),
+  seed: v.optional(v.number()),
+  maxRetries: v.optional(v.number()),
+  headers: v.optional(v.record(v.string(), v.string())),
+};
+export type CallSettings = ObjectType<typeof vCallSettingsFields>;
 
-export const vObjectArgs = v.object({
-  output: v.optional(v.any()),
-  mode: v.optional(v.literal("json")),
-  prompt: v.optional(v.string()),
-  messages: v.optional(v.array(vMessage)),
+export const vTextArgs = v.object({
+  ...vCallSettingsFields,
+  ...vPromptFields,
+  toolChoice: v.optional(
+    v.union(
+      v.literal("auto"),
+      v.literal("none"),
+      v.literal("required"),
+      v.object({
+        type: v.literal("tool"),
+        toolName: v.string(),
+      })
+    )
+  ),
+  maxSteps: v.optional(v.number()),
+  experimental_continueSteps: v.optional(v.boolean()),
+  providerOptions,
+  experimental_providerMetadata,
 });
+export type TextArgs = Infer<typeof vTextArgs>;
+
+const objectArgsCommonFields = {
+  ...vCallSettingsFields,
+  ...vPromptFields,
+  providerOptions,
+  experimental_providerMetadata,
+};
+
+export const vSafeObjectArgs = v.union(
+  v.object({
+    ...objectArgsCommonFields,
+    output: v.optional(v.literal("object")),
+    schema: v.any(), // JSON schema
+    schemaName: v.optional(v.string()),
+    schemaDescription: v.optional(v.string()),
+    mode: v.optional(
+      v.union(v.literal("auto"), v.literal("json"), v.literal("tool"))
+    ),
+  }),
+  v.object({
+    ...objectArgsCommonFields,
+    output: v.optional(v.literal("array")),
+    schema: v.any(), // JSON schema
+    schemaName: v.optional(v.string()),
+    schemaDescription: v.optional(v.string()),
+    mode: v.optional(
+      v.union(v.literal("auto"), v.literal("json"), v.literal("tool"))
+    ),
+  }),
+  v.object({
+    ...objectArgsCommonFields,
+    output: v.optional(v.literal("enum")),
+    enum: v.array(v.string()),
+    mode: v.optional(
+      v.union(v.literal("auto"), v.literal("json"), v.literal("tool"))
+    ),
+  }),
+  v.object({
+    ...objectArgsCommonFields,
+    output: v.literal("no-schema"),
+    mode: v.optional(v.literal("json")),
+  })
+);
+export type SafeObjectArgs = Infer<typeof vSafeObjectArgs>;
 
 export const vEmbeddingsWithMetadata = v.object({
   vectors: v.array(v.union(v.array(v.number()), v.null())),