feat: Support multiple messages in Nebula API and update input props

Author: joaquim-verges

.changeset/rude-sheep-hear.md

@@ -0,0 +1,31 @@
+---
+"thirdweb": minor
+---
+
+Support multiple messages for Nebula API, updated input props
+
+The Nebula.chat and Nebula.execute functions now support multiple input messages, and the input properties have been updated to match the http API.
+
+```ts
+Nebula.chat({
+  client,
+  messages: [{ role: "user", content: "Hello" }], // new message format
+  // context is now contextFilter
+  contextFilter: {
+    chains: [sepolia],
+  },
+});
+```
+
+Same changes apply to Nebula.execute.
+
+```ts
+Nebula.execute({
+  client,
+  account,
+  messages: [{ role: "user", content: "Hello" }],
+  contextFilter: {
+    chains: [sepolia],
+  },
+});
+```

packages/thirdweb/src/ai/chat.test.ts

@@ -9,8 +9,13 @@ describe.runIf(process.env.TW_SECRET_KEY).skip("chat", () => {
   it("should respond with a message", async () => {
     const response = await Nebula.chat({
       client: TEST_CLIENT,
-      prompt: `What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8`,
-      context: {
+      messages: [
+        {
+          role: "user",
+          content: `What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8`,
+        },
+      ],
+      contextFilter: {
         chains: [sepolia],
       },
     });
@@ -20,9 +25,14 @@ describe.runIf(process.env.TW_SECRET_KEY).skip("chat", () => {
   it("should respond with a transaction", async () => {
     const response = await Nebula.chat({
       client: TEST_CLIENT,
-      prompt: `send 0.0001 ETH on sepolia to ${TEST_ACCOUNT_B.address}`,
+      messages: [
+        {
+          role: "user",
+          content: `send 0.0001 ETH on sepolia to ${TEST_ACCOUNT_B.address}`,
+        },
+      ],
       account: TEST_ACCOUNT_A,
-      context: {
+      contextFilter: {
         chains: [sepolia],
         walletAddresses: [TEST_ACCOUNT_A.address],
       },

packages/thirdweb/src/ai/chat.ts

@@ -5,7 +5,7 @@ import { type Input, type Output, nebulaFetch } from "./common.js";
  *
  * @param input - The input for the chat.
  * @returns The chat response.
- * @beta
+ * @beta This API is in early access and might change in the future.
  * @nebula
  *
  * @example
@@ -14,8 +14,13 @@ import { type Input, type Output, nebulaFetch } from "./common.js";
  *
  * const response = await Nebula.chat({
  *   client: TEST_CLIENT,
- *   prompt: "What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
- *   context: {
+ *   messages: [
+ *     {
+ *       role: "user",
+ *       content: "What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
+ *     },
+ *   ],
+ *   contextFilter: {
  *     chains: [sepolia],
  *   },
  * });

packages/thirdweb/src/ai/common.ts

@@ -15,9 +15,12 @@ const NEBULA_API_URL = "https://nebula-api.thirdweb.com";
 
 export type Input = {
   client: ThirdwebClient;
-  prompt: string | string[];
+  messages: {
+    role: "user" | "assistant";
+    content: string;
+  }[];
   account?: Account;
-  context?: {
+  contextFilter?: {
     chains?: Chain[];
     walletAddresses?: string[];
     contractAddresses?: string[];
@@ -52,7 +55,7 @@ export async function nebulaFetch(
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
-      message: input.prompt, // TODO: support array of messages
+      messages: input.messages,
       session_id: input.sessionId,
       ...(input.account
         ? {
@@ -62,13 +65,15 @@ export async function nebulaFetch(
             },
           }
         : {}),
-      ...(input.context
+      ...(input.contextFilter
         ? {
             context_filter: {
               chain_ids:
-                input.context.chains?.map((c) => c.id.toString()) || [],
-              signer_wallet_address: input.context.walletAddresses || [],
-              contract_addresses: input.context.contractAddresses || [],
+                input.contextFilter.chains?.map((c) => c.id.toString()) || [],
+              wallet_addresses:
+                input.contextFilter.walletAddresses ||
+                (input.account ? [input.account.address] : []),
+              contract_addresses: input.contextFilter.contractAddresses || [],
             },
           }
         : {}),

packages/thirdweb/src/ai/execute.test.ts

@@ -11,9 +11,14 @@ describe.runIf(process.env.TW_SECRET_KEY).skip("execute", () => {
     await expect(
       Nebula.execute({
         client: TEST_CLIENT,
-        prompt: `send 0.0001 ETH to ${TEST_ACCOUNT_B.address}`,
+        messages: [
+          {
+            role: "user",
+            content: `send 0.0001 ETH to ${TEST_ACCOUNT_B.address}`,
+          },
+        ],
         account: TEST_ACCOUNT_A,
-        context: {
+        contextFilter: {
           chains: [sepolia],
           walletAddresses: [TEST_ACCOUNT_A.address],
         },
@@ -22,7 +27,7 @@ describe.runIf(process.env.TW_SECRET_KEY).skip("execute", () => {
   });
 
   // TODO make this work reliably
-  it.skip("should execute a contract call", async () => {
+  it("should execute a contract call", async () => {
     const nftContract = getContract({
       client: TEST_CLIENT,
       chain: sepolia,
@@ -31,11 +36,15 @@ describe.runIf(process.env.TW_SECRET_KEY).skip("execute", () => {
 
     const response = await Nebula.execute({
       client: TEST_CLIENT,
-      prompt: `approve 1 token of token id 0 to ${TEST_ACCOUNT_B.address} using the approve function`,
+      messages: [
+        {
+          role: "user",
+          content: `approve 1 token of token id 0 to ${TEST_ACCOUNT_B.address} using the approve function`,
+        },
+      ],
       account: TEST_ACCOUNT_A,
-      context: {
+      contextFilter: {
         chains: [nftContract.chain],
-        walletAddresses: [TEST_ACCOUNT_A.address],
         contractAddresses: [nftContract.address],
       },
     });

packages/thirdweb/src/ai/execute.ts

@@ -8,18 +8,26 @@ import { type Input, nebulaFetch } from "./common.js";
  *
  * @param input - The input for the transaction.
  * @returns The transaction hash.
- * @beta
+ * @beta This API is in early access and might change in the future.
  * @nebula
  *
  * @example
  * ```ts
  * import { Nebula } from "thirdweb/ai";
  *
+ * const wallet = createWallet("io.metamask");
+ * const account = wallet.connect({ client });
+ *
  * const result = await Nebula.execute({
- *   client: TEST_CLIENT,
- *   prompt: "send 0.0001 ETH to vitalik.eth",
- *   account: TEST_ACCOUNT_A,
- *   context: {
+ *   client,
+ *   account, // transactions will be sent from this account
+ *   messages: [
+ *     {
+ *       role: "user",
+ *       content: "send 0.0001 ETH to vitalik.eth",
+ *     },
+ *   ],
+ *   contextFilter: {
  *     chains: [sepolia],
  *   },
  * });