@dremio/js-sdk 0.42.0 → 0.43.1

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,279 @@ const dremio = new Dremio({
 });
 ```
 
+## AI Agent
+
+### `AgentConversation`
+
+Represents a conversation with the Dremio AI Agent.
+
+#### Properties
+
+- `createdAt: Temporal.Instant` - When the conversation was created
+- `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
+- `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: UserChatMessage.new(
+    "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
+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`
+
+```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
+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",
+  ),
+});
+```
+
+#### Stream Run Events
+
+Monitor chat events as they stream in from a run:
+
+```typescript
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+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 history = await conversation.history();
+
+console.log(`Conversation has ${history.length} events`);
+```
+
+### 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.
+
+#### 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
+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) => {
+  snapshot = AgentConversation.reduceChatEvents(snapshot, [chatEvent]);
+
+  const currentExchange = snapshot[snapshot.length - 1];
+  console.log("Current exchange:", currentExchange);
+});
+```
+
+### `UserChatMessage`
+
+Create user messages to send to the AI Agent.
+
+#### Create a Simple Message
+
+```typescript
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+const message = UserChatMessage.new("What tables are available?");
+```
+
+#### Create a Message with Context
+
+```typescript
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+const message = UserChatMessage.new("Analyze this data", {
+  context: "Additional context about the request",
+  skillIds: ["skill-id-1", "skill-id-2"],
+});
+```
+
+#### Message Properties
+
+- `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