@convex-dev/agent 0.1.6 → 0.1.7-alpha.1

package/README.md

@@ -253,22 +253,15 @@ and have them all saved (vs. just the last one), or avoid saving any input
 or output messages, you can pass in a `storageOptions` object, either to the
 Agent constructor or per-message.
 
-The usecase for passing multiple messages is if you want to include some extra
-messages for context to the LLM, but only the last message is the user's actual
-request. e.g. `messages = [...messagesFromRag, messageFromUser]`.
+The usecase for passing in multiple messages but not saving them is if you want
+to include some extra messages for context to the LLM, but only the last message
+is the user's actual request. e.g. `messages = [...messagesFromRag, messageFromUser]`.
+The default is to save the prompt and all output messages.
 
 ```ts
 const result = await thread.generateText({ messages }, {
-  // The default values are shown below.
   storageOptions: {
-    // When false, allows you to pass in arbitrary context that will
-    // be in addition to automatically fetched content.
-    // Pass true to have all input messages saved to the thread history.
-    saveAllInputMessages: false,
-    // By default it saves the input message, or the last message if multiple are provided.
-    saveAnyInputMessages: true,
-    // Save the generated messages to the thread history.
-    saveOutputMessages: true,
+    saveMessages: "all" | "none" | "promptAndOutput";
   },
 });
 ```
@@ -630,6 +623,24 @@ const supportAgent = new Agent(components.agent, {
 Tip: Define the `usageHandler` within a function where you have more variables
 available to attribute the usage to a different user, team, project, etc.
 
+### Logging the raw request and response
+
+You can provide a `rawRequestResponseHandler` to the agent to log the raw request and response from the LLM.
+
+You could use this to log the request and response to a table, or use console logs with
+[Log Streaming](https://docs.convex.dev/production/integrations/log-streams/)
+to allow debugging and searching through Axiom or another logging service.
+
+```ts
+const supportAgent = new Agent(components.agent, {
+  ...
+  rawRequestResponseHandler: async (ctx, { request, response }) => {
+    console.log("request", request);
+    console.log("response", response);
+  },
+});
+```
+
 ## Troubleshooting
 
 ### Circular dependencies

package/dist/commonjs/client/_generated/_ignore.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=_ignore.d.ts.map

package/dist/commonjs/client/_generated/_ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ignore.d.ts","sourceRoot":"","sources":["../../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":""}

package/dist/commonjs/client/_generated/_ignore.js

@@ -0,0 +1,3 @@
+"use strict";
+// This is only here so convex-test can detect a _generated folder
+//# sourceMappingURL=_ignore.js.map

package/dist/commonjs/client/_generated/_ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ignore.js","sourceRoot":"","sources":["../../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":";AAAA,kEAAkE"}

package/dist/commonjs/client/files.d.ts

@@ -0,0 +1,57 @@
+import type { FilePart, ImagePart } from "ai";
+import type { Id } from "../component/_generated/dataModel.js";
+import type { ActionCtx, AgentComponent, QueryCtx } from "./types.js";
+import type { RunMutationCtx } from "@convex-dev/prosemirror-sync";
+export declare const MAX_FILE_SIZE: number;
+type File = {
+    url: string;
+    fileId: string;
+    storageId: Id<"_storage">;
+    hash: string;
+    filename: string | undefined;
+};
+/**
+ * Store a file in the file storage and return the URL and fileId.
+ * @param ctx A ctx object from an action.
+ * @param component The agent component.
+ * @param blob The blob to store.
+ * @param filename The filename to store.
+ * @param sha256 The sha256 hash of the file. If not provided, it will be
+ *   computed. However, to ensure no corruption during transfer, you can
+ *   calculate this on the client to enforce integrity.
+ * @returns The URL, fileId, and storageId of the stored file.
+ */
+export declare function storeFile(ctx: ActionCtx | RunMutationCtx, component: AgentComponent, blob: Blob, filename?: string, sha256?: string): Promise<{
+    file: File;
+    filePart: FilePart;
+    imagePart: ImagePart | undefined;
+}>;
+/**
+ * Get file metadata from the component.
+ * This also returns filePart (and imagePart if the file is an image),
+ * which are useful to construct a CoreMessage like
+ * ```ts
+ * const { filePart, imagePart } = await getFile(ctx, components.agent, fileId);
+ * const message: UserMessage = {
+ *   role: "user",
+ *   content: [imagePart ?? filePart],
+ * };
+ * ```
+ * @param ctx A ctx object from an action or query.
+ * @param component The agent component, usually `components.agent`.
+ * @param fileId The fileId of the file to get.
+ * @returns The file metadata and content parts.
+ */
+export declare function getFile(ctx: ActionCtx | QueryCtx, component: AgentComponent, fileId: string): Promise<{
+    file: {
+        fileId: string;
+        url: string;
+        storageId: Id<"_storage">;
+        hash: string;
+        filename: string | undefined;
+    };
+    filePart: FilePart;
+    imagePart: ImagePart | undefined;
+}>;
+export {};
+//# sourceMappingURL=files.d.ts.map

package/dist/commonjs/client/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../src/client/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,sCAAsC,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,eAAO,MAAM,aAAa,QAAY,CAAC;AAEvC,KAAK,IAAI,GAAG;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,SAAS,GAAG,cAAc,EAC/B,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,IAAI,EACV,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;CAClC,CAAC,CAiED;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,SAAS,GAAG,QAAQ,EACzB,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM;;;;mBAemB,EAAE,CAAC,UAAU,CAAC;;;;cAYrC,QAAQ;eACP,SAAS,GAAG,SAAS;GARjC"}

package/dist/commonjs/client/files.js

@@ -0,0 +1,124 @@
+export const MAX_FILE_SIZE = 1024 * 64;
+/**
+ * Store a file in the file storage and return the URL and fileId.
+ * @param ctx A ctx object from an action.
+ * @param component The agent component.
+ * @param blob The blob to store.
+ * @param filename The filename to store.
+ * @param sha256 The sha256 hash of the file. If not provided, it will be
+ *   computed. However, to ensure no corruption during transfer, you can
+ *   calculate this on the client to enforce integrity.
+ * @returns The URL, fileId, and storageId of the stored file.
+ */
+export async function storeFile(ctx, component, blob, filename, sha256) {
+    if (!("runAction" in ctx)) {
+        throw new Error("You're trying to save a file that's too large in a mutation. " +
+            "You can store the file in file storage from an action first, then pass a URL instead. " +
+            "To have the agent component track the file, you can use `saveFile` from an action then use the fileId with getFile in the mutation. " +
+            "Read more in the docs.");
+    }
+    const hash = sha256 ||
+        Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", await blob.arrayBuffer())))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    const reused = await ctx.runMutation(component.files.useExistingFile, {
+        hash,
+        filename,
+    });
+    if (reused) {
+        const url = (await ctx.storage.getUrl(reused.storageId));
+        return {
+            ...getParts(url, blob.type, filename),
+            file: {
+                url,
+                fileId: reused.fileId,
+                storageId: reused.storageId,
+                hash,
+                filename,
+            },
+        };
+    }
+    const newStorageId = await ctx.storage.store(blob);
+    if (sha256) {
+        const metadata = await ctx.storage.getMetadata(newStorageId);
+        if (metadata?.sha256 !== sha256) {
+            throw new Error("Hash mismatch: " + metadata?.sha256 + " != " + sha256);
+        }
+    }
+    const { fileId, storageId } = await ctx.runMutation(component.files.addFile, {
+        storageId: newStorageId,
+        hash,
+        filename,
+        mimeType: blob.type,
+    });
+    const url = (await ctx.storage.getUrl(storageId));
+    if (storageId !== newStorageId) {
+        // We're re-using another file's storageId
+        // Because we try to reuse the file above, this should be very very rare
+        // and only in the case of racing to check then store the file.
+        await ctx.storage.delete(newStorageId);
+    }
+    return {
+        ...getParts(url, blob.type, filename),
+        file: {
+            url,
+            fileId,
+            storageId: storageId,
+            hash,
+            filename,
+        },
+    };
+}
+/**
+ * Get file metadata from the component.
+ * This also returns filePart (and imagePart if the file is an image),
+ * which are useful to construct a CoreMessage like
+ * ```ts
+ * const { filePart, imagePart } = await getFile(ctx, components.agent, fileId);
+ * const message: UserMessage = {
+ *   role: "user",
+ *   content: [imagePart ?? filePart],
+ * };
+ * ```
+ * @param ctx A ctx object from an action or query.
+ * @param component The agent component, usually `components.agent`.
+ * @param fileId The fileId of the file to get.
+ * @returns The file metadata and content parts.
+ */
+export async function getFile(ctx, component, fileId) {
+    const file = await ctx.runQuery(component.files.get, { fileId });
+    if (!file) {
+        throw new Error(`File not found in component: ${fileId}`);
+    }
+    const url = await ctx.storage.getUrl(file.storageId);
+    if (!url) {
+        throw new Error(`File not found in storage: ${file.storageId}`);
+    }
+    return {
+        ...getParts(url, file.mimeType, file.filename),
+        file: {
+            fileId,
+            url,
+            storageId: file.storageId,
+            hash: file.hash,
+            filename: file.filename,
+        },
+    };
+}
+function getParts(url, mimeType, filename) {
+    const filePart = {
+        type: "file",
+        data: new URL(url),
+        mimeType,
+        filename,
+    };
+    const imagePart = mimeType.startsWith("image/")
+        ? {
+            type: "image",
+            image: new URL(url),
+            mimeType,
+        }
+        : undefined;
+    return { filePart, imagePart };
+}
+//# sourceMappingURL=files.js.map

package/dist/commonjs/client/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../../src/client/files.ts"],"names":[],"mappings":"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"}