@dremio/js-sdk 0.42.0 → 0.43.0

package/README.md

@@ -132,6 +132,7 @@ API responses are automatically converted to native JavaScript/TypeScript types:
 
 - [Configuration](#configuration)
 - [Authentication](#authentication)
+- [AI Agent](#ai-agent)
 - [Catalog](#catalog)
 - [Engine Rules](#engine-rules)
 - [Engines](#engines)
@@ -242,6 +243,214 @@ const dremio = new Dremio({
 });
 ```
 
+## AI Agent
+
+### `AgentConversation`
+
+Represents a conversation with the Dremio AI Agent.
+
+#### Properties
+
+- `id: string` - Unique identifier for the conversation
+- `title: string` - The conversation title
+- `createdAt: Temporal.Instant` - When the conversation was created
+- `modifiedAt: Temporal.Instant` - When the conversation was last modified
+- `modelName: string | null` - The AI model name last used for this conversation
+- `modelProviderId: string | null` - The AI model provider ID last used for this conversation
+
+#### `AgentConversation` implements the [`Observable` contract](https://github.com/WICG/observable) using `Symbol.observable`:
+
+```typescript
+import { from } from "rxjs";
+
+from(conversation).subscribe((chatEvent) => {
+  console.log(chatEvent);
+});
+```
+
+#### Create an `AgentConversation`
+
+```typescript
+const conversation = await dremio.ai("PROJECT_ID").createConversation({
+  message: new UserChatMessage(
+    new UserChatMessageStringContent(
+      "Can you help me visualize the data in the Citibike sample dataset?",
+    ),
+  ),
+});
+```
+
+#### Retrieve `AgentConversation` by ID
+
+```typescript
+const conversation = await dremio
+  .ai("PROJECT_ID")
+  .retrieveConversation("CONVERSATION_ID");
+```
+
+#### Update `AgentConversation`
+
+```typescript
+const result = await conversation.update({ title: "New title" });
+```
+
+#### Delete `AgentConversation`
+
+```typescript
+await conversation.delete();
+```
+
+#### List all `AgentConversation`s
+
+```typescript
+for await (const conversation of dremio
+  .ai("PROJECT_ID")
+  .listConversations()
+  .data()) {
+  console.log(conversation);
+}
+```
+
+#### Send message to `AgentConversation`
+
+To send a message to the Agent, use the `startRun()` method:
+
+```typescript
+await conversation.startRun({
+  message: new UserChatMessage(
+    new UserChatMessageStringContent(
+      "Please adjust the x-axis range to show only 2025-2026",
+    ),
+  ),
+});
+```
+
+### `AgentConversationSnapshotBuilder`
+
+Compiles a sequence of `ChatEvent`s into a structured view of the current conversation state.
+
+#### Building a Snapshot
+
+Create a snapshot from existing conversation history:
+
+```typescript
+const conversation = (
+  await dremio.ai("PROJECT_ID").retrieveConversation("CONVERSATION_ID")
+).unwrap();
+
+const conversationSnapshot = AgentConversationSnapshotBuilder.fromChatEvents(
+  conversation.id,
+  (await conversation.history()).unwrap(),
+);
+```
+
+#### Adding Events in Real-Time
+
+Monitor chat events as they stream in and add them to the snapshot:
+
+```typescript
+const runId = await conversation
+  .startRun({
+    message: new UserChatMessage(
+      new UserChatMessageStringContent(
+        "What data is available to me in Dremio?",
+      ),
+    ),
+  })
+  .then((res) => res.unwrap());
+
+conversation.runEvents$(runId).subscribe((chatEvent) => {
+  conversationSnapshot.addChatEvent(chatEvent);
+  console.log(conversationSnapshot.get(runId)!.toJSON());
+});
+```
+
+#### Accessing Snapshot Data
+
+The snapshot is iterable and provides access to exchanges:
+
+```typescript
+// Iterate through all exchanges
+for (const exchange of conversationSnapshot) {
+  console.log("Exchange ID:", exchange.id);
+  for (const message of exchange.messages) {
+    console.log("Message:", message);
+  }
+  for (const toolCall of exchange.toolCalls) {
+    console.log("Tool Call:", toolCall.id, toolCall.state);
+  }
+}
+
+// Get a specific exchange
+const exchange = conversationSnapshot.get(runId);
+```
+
+#### Snapshot Methods
+
+- `length: number` - Get the number of exchanges in the snapshot
+- `clone(): AgentConversationSnapshotBuilder` - Create a deep clone of the builder
+- `slice(startExchangeId, endExchangeId?)` - Get a shallow clone containing exchanges in a range
+- `toJSON()` - Serialize the snapshot to JSON
+
+#### Snapshot Output Example
+
+The `toJSON()` method returns an array of exchanges with their messages and tool calls:
+
+```json
+[
+  {
+    "id": "run-id-1",
+    "messages": [
+      {
+        "id": "msg-1",
+        "runId": "run-id-1",
+        "conversationId": "conv-id",
+        "role": "user",
+        "content": {
+          "chunkType": "userMessage",
+          "text": "What data is available?"
+        }
+      },
+      {
+        "id": "msg-2",
+        "runId": "run-id-1",
+        "conversationId": "conv-id",
+        "role": "agent",
+        "content": {
+          "chunkType": "model",
+          "name": "modelGeneric",
+          "result": {
+            "text": "Here are the available datasets..."
+          }
+        }
+      }
+    ],
+    "toolCalls": [
+      {
+        "id": "tool-call-1",
+        "state": "success",
+        "request": {
+          "content": {
+            "chunkType": "toolRequest",
+            "name": "queryTool",
+            "arguments": { "query": "SELECT * FROM schemas" }
+          }
+        },
+        "result": {
+          "content": {
+            "chunkType": "toolResponse",
+            "name": "queryTool",
+            "result": {
+              "rows": [{ "schema_name": "public" }]
+            }
+          }
+        }
+      }
+    ]
+  }
+]
+```
+
 ## Catalog
 
 ### `CatalogReference` Interface