@dremio/js-sdk 0.43.0 → 0.43.1

package/README.md

@@ -251,31 +251,23 @@ 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
+- `currentRunId: string | null` - The ID of the currently active run, if any
+- `id: string` - Unique identifier for the conversation
 - `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);
-});
-```
+- `modifiedAt: Temporal.Instant` - When the conversation was last modified
+- `tag: string` - Version tag for optimistic concurrency control
+- `title: string` - The conversation title
 
 #### Create an `AgentConversation`
 
 ```typescript
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
 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?",
-    ),
+  message: UserChatMessage.new(
+    "Can you help me visualize the data in the Citibike sample dataset?",
   ),
 });
 ```
@@ -291,7 +283,21 @@ const conversation = await dremio
 #### Update `AgentConversation`
 
 ```typescript
-const result = await conversation.update({ title: "New title" });
+await conversation.update({ title: "New title" });
+```
+
+The `update()` method supports optimistic concurrency control with conflict resolution:
+
+```typescript
+await conversation.update(
+  { title: "New title" },
+  {
+    onConflict: async (local, remote, changes) => {
+      // Overwrite with local title
+      return { title: local.title };
+    },
+  },
+);
 ```
 
 #### Delete `AgentConversation`
@@ -316,141 +322,200 @@ for await (const conversation of dremio
 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",
-    ),
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+const runId = await conversation.startRun({
+  message: UserChatMessage.new(
+    "Please adjust the x-axis range to show only 2025-2026",
   ),
 });
 ```
 
-### `AgentConversationSnapshotBuilder`
+#### Stream Run Events
 
-Compiles a sequence of `ChatEvent`s into a structured view of the current conversation state.
+Monitor chat events as they stream in from a run:
 
-#### Building a Snapshot
+```typescript
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
 
-Create a snapshot from existing conversation history:
+const runId = await conversation.startRun({
+  message: UserChatMessage.new("What data is available to me in Dremio?"),
+});
+
+conversation.runEvents$(runId).subscribe((chatEvent) => {
+  console.log("Event:", chatEvent.content.chunkType);
+  if (chatEvent.content.chunkType === "model") {
+    console.log("Model response:", chatEvent.content.result);
+  }
+});
+```
+
+#### Retrieve Conversation History
+
+Get the full history of chat events for a conversation:
 
 ```typescript
-const conversation = (
-  await dremio.ai("PROJECT_ID").retrieveConversation("CONVERSATION_ID")
-).unwrap();
+const history = await conversation.history();
 
-const conversationSnapshot = AgentConversationSnapshotBuilder.fromChatEvents(
-  conversation.id,
-  (await conversation.history()).unwrap(),
-);
+console.log(`Conversation has ${history.length} events`);
 ```
 
-#### Adding Events in Real-Time
+### Working with Chat Events
+
+The state of a conversation is represented as a stream of `ChatEvent` objects. These events include user messages, tool call requests and results, and Agent replies. While the event stream enables incremental UI updates, it contains implicit relationships that need to be made explicit for easier consumption.
 
-Monitor chat events as they stream in and add them to the snapshot:
+#### Chat Event Types
+
+- `userMessage` - A message from the user
+- `model` - A response from the AI model
+- `toolRequest` - A request to execute a tool (tool calls can run in parallel)
+- `toolResponse` - The result of a tool execution
+- `error` - An error message
+
+#### Building a Conversation Snapshot
+
+The `AgentConversation.reduceChatEvents()` method transforms a stream of chat events into a structured snapshot that makes implicit relationships explicit:
+
+- **Groups events by exchange** - Each user-agent interaction (identified by `runId`) becomes a separate exchange
+- **Pairs tool calls** - Tool requests and responses are matched by `callId` and combined into a single object
+- **Derives tool state** - Automatically determines if a tool call is `pending`, `success`, or `error`
+- **Handles duplicates** - Efficiently filters duplicate events when merging history and live streams
+- **Preserves order** - Maintains insertion order for messages and tool calls
 
 ```typescript
-const runId = await conversation
-  .startRun({
-    message: new UserChatMessage(
-      new UserChatMessageStringContent(
-        "What data is available to me in Dremio?",
-      ),
-    ),
-  })
-  .then((res) => res.unwrap());
+import { AgentConversation } from "@dremio/js-sdk/enterprise/ai";
+
+const conversation = await dremio
+  .ai("PROJECT_ID")
+  .retrieveConversation("CONVERSATION_ID");
+
+const history = await conversation.history();
+
+const snapshot = AgentConversation.reduceChatEvents([], history);
+```
+
+Each exchange in the snapshot represents a single user-agent interaction:
+
+```typescript
+type ConversationExchange = {
+  id: string; // The run ID
+  messages: Map<string, ConversationExchangeMessage>;
+  toolCalls: Map<string, AgentToolCall>;
+  submittedUserMessage?: UserChatMessage;
+};
+
+type AgentToolCall = {
+  id: string;
+  state: "error" | "pending" | "success";
+  request: ChatEventWithChunkType<"toolRequest"> | undefined;
+  result: ChatEventWithChunkType<"toolResponse"> | undefined;
+};
+```
+
+#### Incremental Updates
+
+The reducer is a pure function with signature `(snapshot, events) => newSnapshot`. You can incrementally update a snapshot as new events arrive:
+
+```typescript
+import {
+  AgentConversation,
+  UserChatMessage,
+} from "@dremio/js-sdk/enterprise/ai";
+
+let snapshot = AgentConversation.reduceChatEvents([], historyEvents);
+
+const runId = await conversation.startRun({
+  message: UserChatMessage.new("What tables exist?"),
+});
 
 conversation.runEvents$(runId).subscribe((chatEvent) => {
-  conversationSnapshot.addChatEvent(chatEvent);
-  console.log(conversationSnapshot.get(runId)!.toJSON());
+  snapshot = AgentConversation.reduceChatEvents(snapshot, [chatEvent]);
+
+  const currentExchange = snapshot[snapshot.length - 1];
+  console.log("Current exchange:", currentExchange);
 });
 ```
 
-#### Accessing Snapshot Data
+### `UserChatMessage`
+
+Create user messages to send to the AI Agent.
 
-The snapshot is iterable and provides access to exchanges:
+#### Create a Simple Message
 
 ```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);
-  }
-}
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
 
-// Get a specific exchange
-const exchange = conversationSnapshot.get(runId);
+const message = UserChatMessage.new("What tables are available?");
 ```
 
-#### Snapshot Methods
+#### Create a Message with Context
 
-- `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
+```typescript
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
 
-#### Snapshot Output Example
+const message = UserChatMessage.new("Analyze this data", {
+  context: "Additional context about the request",
+  skillIds: ["skill-id-1", "skill-id-2"],
+});
+```
 
-The `toJSON()` method returns an array of exchanges with their messages and tool calls:
+#### Message Properties
 
-```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" }]
-            }
-          }
-        }
-      }
-    ]
-  }
-]
+- `id: string` - Unique identifier for the message
+- `createdAt: Temporal.ZonedDateTime` - When the message was created
+- `content: string` - The message text
+- `prompt?: object` - Optional prompt configuration including context, skillIds, and approvals
+
+### `AgentConversationMachine`
+
+An XState state machine for managing conversation lifecycle with built-in state management.
+
+#### Create and Use the Machine
+
+```typescript
+import { createActor } from "xstate";
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+const conversationMachine = dremio.ai("PROJECT_ID").conversationMachine;
+
+// Create a new conversation
+const actor = createActor(conversationMachine, {
+  input: {
+    conversationId: null,
+    initialMessage: UserChatMessage.new("Hello, can you help me?"),
+  },
+});
+
+actor.subscribe((snapshot) => {
+  console.log("State:", snapshot.value);
+  console.log("Exchanges:", snapshot.context.conversationSnapshot);
+});
+
+actor.start();
+
+// Send additional messages
+actor.send({
+  type: "SUBMIT_USER_MESSAGE",
+  message: UserChatMessage.new("What data sources are available?"),
+});
 ```
 
+#### Machine States
+
+- `uninitialized` - Initial state before conversation is created
+- `creating_conversation` - Creating a new conversation
+- `retrieving_history` - Fetching conversation history
+- `idle` - Ready to accept new messages
+- `submitting_message` - Sending a user message
+- `streaming` - Receiving agent responses
+- `retrieve_history_failed` - Error state when history retrieval fails
+
+#### Machine Events
+
+- `SUBMIT_USER_MESSAGE` - Send a new message
+- `REFRESH_HISTORY` - Reload conversation history
+- `CANCEL_RUN` - Cancel the current run
+
 ## Catalog
 
 ### `CatalogReference` Interface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dremio/js-sdk",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "description": "JavaScript library for the Dremio API",
   "keywords": [
     "dremio",