@sqlrooms/ai-core 0.26.0-rc.2 → 0.26.0-rc.3

package/README.md

@@ -19,48 +19,12 @@ npm install @sqlrooms/ai
 yarn add @sqlrooms/ai
 ```
 
-Since version 0.8.2, you will need to install the LLM providers you want to use. For example, to use OpenAI, you can install the `@ai-sdk/openai` package:
-
-```bash
-npm install @ai-sdk/openai
-```
-
-Google LLM provider:
-
-```bash
-npm install @ai-sdk/google
-```
-
-Anthropic LLM provider:
-
-```bash
-npm install @ai-sdk/anthropic
-```
-
-DeepSeek LLM provider:
-
-```bash
-npm install @ai-sdk/deepseek
-```
-
-XAI LLM provider:
-
-```bash
-npm install @ai-sdk/xai
-```
-
-ollama LLM provider:
-
-```bash
-npm install ollama-ai-provider-v2
-```
-
 ## Basic Usage
 
-### Setting Up AI Integration
+### Setting Up SqlRooms AI Chat for Browser-only application
 
 ```tsx
-import {createAiSlice} from '@sqlrooms/ai';
+import {createAiSlice, createAiSettingsSlice} from '@sqlrooms/ai';
 import {createRoomStore} from '@sqlrooms/room-shell';
 
 // Create a room store with AI capabilities
@@ -71,22 +35,22 @@ const {roomStore, useRoomStore} = createRoomStore({
       // Your room configuration
     },
   }),
+  // Ai model config slice
+  ...createAiSettingsSlice({})(set, get, store),
   // Add AI slice
   ...createAiSlice({
-    getApiKey: (modelProvider) => {
-      // Return API key for the specified model provider
-      return process.env.OPENAI_API_KEY || '';
+    getInstructions: () => {
+      return `You are an AI assistant that can answer questions and help with tasks.`;
     },
     initialAnalysisPrompt: 'What insights can you provide from my data?',
-    // Optional: Add custom tools
-    customTools: {
-      // Your custom tools
+    tools: {
+      // Your tools
     },
-    // Optional: Custom instructions for the AI
-    getInstructions: (tablesSchema) => {
-      return `Analyze the following tables: ${tablesSchema.map((t) => t.name).join(', ')}`;
+    getInstructions: () => {
+      // add custom instructions here
+      return createDefaultAiInstructions(store);
     },
-  }),
+  })(set, get, store),
 });
 
 function MyApp() {
@@ -98,311 +62,205 @@ function MyApp() {
 }
 ```
 
-### Advanced Store Configuration
+### Setting Up SqlRooms AI Chat for Server-side application
 
-For more complex applications, you can combine multiple slices:
+- api/chat/route.ts
 
-```tsx
-import {createAiSlice} from '@sqlrooms/ai';
-import {
-  createSqlEditorSlice,
-  createDefaultSqlEditorConfig,
-} from '@sqlrooms/sql-editor';
-import {createRoomStore, createRoomShellSlice} from '@sqlrooms/room-shell';
-
-// Define your application state type
-export type RoomState = RoomState<RoomConfig> &
-  AiSliceState &
-  SqlEditorSliceState;
-
-// Create the store with multiple slices
-export const {roomStore, useRoomStore} = createRoomStore<RoomConfig, RoomState>(
-  (set, get, store) => ({
-    // Base room slice
-    ...createRoomShellSlice({
-      config: {
-        ...createDefaultSqlEditorConfig(),
-      },
-    }),
-    // AI slice
-    ...createAiSlice({
-      config: {
-        // Optional: Pre-configured AI sessions
-        sessions: [
-          {
-            id: 'default-session',
-            name: 'Default Analysis',
-            modelProvider: 'openai',
-            model: 'gpt-4o',
-            analysisResults: [],
-            createdAt: new Date(),
-          },
-        ],
-        currentSessionId: 'default-session',
-      }
-      getApiKey: (modelProvider) => {
-        // Return API key based on provider
-        return apiKeys[modelProvider] || '';
-      },
-      // Custom tools and instructions
-    }),
-    // SQL Editor slice
-    ...createSqlEditorSlice(),
-  }),
-);
-```
-
-### Using AI Query Controls
+```typescript
+export async function POST(req: Request) {
+  const {messages} = await req.json();
 
-```tsx
-import {QueryControls} from '@sqlrooms/ai';
+  const stream = createUIMessageStream({
+    execute: async ({writer}) => {
+      const result = streamText({
+        model: openai('gpt-4.1'),
+        system: systemPrompt,
+        messages,
+        tools: {
+          // Your tools: remove exeucte for client tools so they run on the client side
+        },
+      });
+      writer.merge(result.toUIMessageStream({originalMessages: messages}));
+    },
+  });
 
-function AiQueryPanel() {
-  return (
-    <div className="rounded-lg border p-4">
-      <h2 className="mb-4 text-xl font-bold">Ask AI</h2>
-      <QueryControls
-        placeholder="Ask a question about your data..."
-        onSubmit={(query) => console.log('Processing query:', query)}
-      />
-    </div>
-  );
+  return stream.toUIMessageStreamResponse();
 }
 ```
 
-### Displaying Analysis Results
-
-```tsx
-import {AnalysisResultsContainer, AnalysisResult} from '@sqlrooms/ai';
+- page.tsx
 
-function AnalysisPanel() {
-  // Get the current session and its analysis results
-  const currentSession = useRoomStore((state) => state.ai.getCurrentSession());
-  const analysisResults = currentSession?.analysisResults || [];
+```typescript
+const {roomStore, useRoomStore} = createRoomStore({
+  ...createRoomShellSlice({
+    // Your room configuration
+    })(set, get, store),
+  ...createAiSettingsSlice({
+    // Your AI settings
+  })(set, get, store),
+  ...createAiSlice({
+    chatEndPoint: '/api/chat', // Point to the server-side endpoint
+    tools: {
+      // Your tools
+    },
+  })(set, get, store),
+});
 
+function MyApp() {
   return (
-    <div className="rounded-lg border p-4">
-      <h2 className="mb-4 text-xl font-bold">AI Analysis</h2>
-      <AnalysisResultsContainer>
-        {analysisResults.map((result) => (
-          <AnalysisResult key={result.id} result={result} />
-        ))}
-      </AnalysisResultsContainer>
-    </div>
+    <RoomStateProvider roomStore={roomStore}>
+      <MyDataApp />
+    </RoomStateProvider>
   );
 }
 ```
 
-### Working with AI State
-
-```tsx
-function AiStatusIndicator() {
-  const isRunningAnalysis = useRoomStore((state) => state.ai.isRunningAnalysis);
-  const analysisPrompt = useRoomStore((state) => state.ai.analysisPrompt);
-  const currentSession = useRoomStore((state) => state.ai.getCurrentSession());
-  const lastResult =
-    currentSession?.analysisResults[currentSession.analysisResults.length - 1];
-
-  if (isRunningAnalysis) {
-    return <div>AI is analyzing your data...</div>;
-  }
-
-  if (lastResult?.errorMessage) {
-    return <div>Error: {lastResult.errorMessage.message}</div>;
-  }
-
-  if (analysisPrompt) {
-    return <div>Last query: "{analysisPrompt}"</div>;
-  }
-
-  return <div>Ask AI a question about your data</div>;
-}
-```
-
-## AiSlice API Reference
-
-The AiSlice provides a comprehensive set of state fields and methods for managing AI interactions in your application.
-
-### State Fields
-
-#### `analysisPrompt`
-
-The current prompt text entered by the user for analysis.
-
-```tsx
-const prompt = useRoomStore((state) => state.ai.analysisPrompt);
-```
-
-#### `isRunningAnalysis`
-
-Boolean flag indicating whether an analysis is currently in progress.
-
-```tsx
-const isRunning = useRoomStore((state) => state.ai.isRunningAnalysis);
-```
-
-#### `tools`
-
-Record of available AI tools that can be used during analysis.
-
-```tsx
-const availableTools = useRoomStore((state) => state.ai.tools);
-```
-
-#### `analysisAbortController`
-
-Optional AbortController instance that can be used to cancel an ongoing analysis.
-
-```tsx
-const abortController = useRoomStore(
-  (state) => state.ai.analysisAbortController,
-);
-```
-
-### Methods
-
-#### `setAnalysisPrompt(prompt: string)`
-
-Sets the current analysis prompt text.
-
-```tsx
-const setPrompt = useRoomStore((state) => state.ai.setAnalysisPrompt);
-setPrompt('Analyze sales trends for the last quarter');
-```
-
-#### `startAnalysis()`
+See [ai-nextjs](https://github.com/sqlrooms/sqlrooms/tree/main/examples/ai-nextjs) for a complete example.
 
-Starts the analysis process using the current prompt.
-
-```tsx
-const startAnalysis = useRoomStore((state) => state.ai.startAnalysis);
-await startAnalysis();
-```
-
-#### `cancelAnalysis()`
+## Data Structure
 
-Cancels any ongoing analysis.
+The basic data structure of the AI package is:
 
-```tsx
-const cancelAnalysis = useRoomStore((state) => state.ai.cancelAnalysis);
-cancelAnalysis();
+```ts
+ai: {
+  sessions: [
+    {
+      id: string,                    // CUID2 identifier
+      name: string,                   // Session display name
+      modelProvider: string,          // e.g., 'openai', 'anthropic'
+      model: string,                  // e.g., 'gpt-4o', 'claude-3-5-sonnet'
+      createdAt: Date,
+      // Primary storage: Full conversation history (AI SDK v5 format)
+      uiMessages: UIMessage[],
+      // Secondary storage: Error messages and legacy compatibility
+      analysisResults: AnalysisResult[],
+      // Tool execution data
+      toolAdditionalData: Record<string, unknown>,
+    },
+  ],
+  currentSessionId: string,
+}
 ```
 
-#### `setAiModel(modelProvider: string, model: string)`
+### Session Schema
 
-Sets the AI model and provider for the current session.
+Each session contains:
 
-```tsx
-const setModel = useRoomStore((state) => state.ai.setAiModel);
-setModel('openai', 'gpt-4o');
-```
-
-#### `createSession(name?: string, modelProvider?: string, model?: string)`
+#### `uiMessages` - Complete Chat History
 
-Creates a new analysis session with optional name and model settings.
+The `uiMessages` array stores the complete, flat conversation history using the Vercel AI SDK v5 `UIMessage` format. This includes:
 
-```tsx
-const createSession = useRoomStore((state) => state.ai.createSession);
-createSession('Financial Analysis', 'openai', 'gpt-4o');
-```
+- User messages
+- Assistant messages
+- Tool call messages
+- All message parts (text, tool invocations, etc.)
 
-#### `switchSession(sessionId: string)`
+This is the **primary data structure** and serves as:
 
-Switches to a different analysis session by ID.
+- The full context for AI model interactions
+- The source for displaying conversation history
+- The base for reconstructing analysis results
 
 ```tsx
-const switchSession = useRoomStore((state) => state.ai.switchSession);
-switchSession('session-123');
+// Example: Accessing UI messages
+const currentSession = useRoomStore((state) => state.ai.getCurrentSession());
+const messages = currentSession?.uiMessages || [];
 ```
 
-#### `renameSession(sessionId: string, name: string)`
-
-Renames an existing analysis session.
+#### `analysisResults` - Structured Analysis View
 
-```tsx
-const renameSession = useRoomStore((state) => state.ai.renameSession);
-renameSession('session-123', 'Q4 Sales Analysis');
-```
+The `analysisResults` array is a **derived structure** that organizes messages into user prompt → AI response pairs. It primarily serves to:
 
-#### `deleteSession(sessionId: string)`
+- Store error messages that occur during analysis
+- Provide backward compatibility with legacy data
+- Offer a simplified view of analysis history
 
-Deletes an analysis session by ID.
+Analysis results are dynamically generated from `uiMessages` using the `transformMessagesToAnalysisResults` utility function.
 
-```tsx
-const deleteSession = useRoomStore((state) => state.ai.deleteSession);
-deleteSession('session-123');
+```ts
+type AnalysisResult = {
+  id: string; // Matches the UIMessage.id
+  prompt: string; // User's question/request
+  errorMessage?: ErrorMessageSchema; // Error if analysis failed
+  isCompleted: boolean; // Whether AI finished responding
+};
 ```
 
-#### `getCurrentSession()`
-
-Returns the current active analysis session.
+#### `toolAdditionalData` - Rich Tool Outputs
 
-```tsx
-const currentSession = useRoomStore((state) => state.ai.getCurrentSession());
-```
+Each session also maintains a `toolAdditionalData` object that stores additional data from tool executions, keyed by `toolCallId`. This data is used for:
 
-#### `deleteAnalysisResult(sessionId: string, resultId: string)`
+- Rendering tool-specific UI components
+- Passing data between tool calls
+- Preserving rich data that doesn't go back to the LLM
 
-Deletes a specific analysis result from a session.
+```ts
+type ToolAdditionalData = Record<string, unknown>;
 
-```tsx
-const deleteResult = useRoomStore((state) => state.ai.deleteAnalysisResult);
-deleteResult('session-123', 'result-456');
+// Example: Storing tool additional data
+const setToolData = useRoomStore((state) => state.ai.setSessionToolAdditionalData);
+setToolData(sessionId, toolCallId, {chartData: [...]});
 ```
 
-#### `findToolComponent(toolName: string)`
-
-Finds the React component associated with a specific tool.
+## Tools
 
-```tsx
-const ChartComponent = useRoomStore((state) =>
-  state.ai.findToolComponent('chart'),
-);
-```
+In AI package, we provide a OpenAssistantTool type that supports not only `execute` function, but also `context` object and `component` object:
 
-## Data Structure
+- `execute` needs to return
+  - llmResult: the result send back to LLM (no raw data)
+  - additionalData: the data will be used by `component` and next `tool`
+- `context`
+  - provide e.g. runtime or async data for `execute`
+  - `execute` can access `context` via `options.context`
+- `component`
+  - use `additionalData` to render a React component for this `tool`
 
-The basic data structure of the AI package is:
+For example, the `weather` tool is defined as follows:
 
 ```ts
-ai: {
-  sessions: [
-    {
-      id: defaultSessionId,
-      name: 'Default Session',
-      modelProvider: 'openai',
-      model: 'gpt-4o-mini',
-      analysisResults: [],
-      createdAt: new Date(),
+const weatherTool: OpenAssistantTool = {
+  name: 'weather',
+  description: 'Get the weather in a city from a weather station',
+  parameters: z.object({cityName: z.string()}),
+  execute: async ({cityName}, options) => {
+    const getStation = options.context?.getStation;
+    const station = getStation ? await getStation(cityName) : null;
+    return {
+      llmResult: {
+        success: true,
+        details: `The weather in ${cityName} is sunny from weather station ${station}.`,
+      },
+      additionalData: {
+        weather: 'sunny',
+        station,
+      },
+    };
+  },
+  context: {
+    getStation: async (cityName: string) => {
+      const stations = {
+        'New York': '123',
+        'Los Angeles': '456',
+        Chicago: '789',
+      };
+      return stations[cityName];
     },
-  ],
-  currentSessionId: defaultSessionId,
-}
+  },
+  component: WeatherStationComponent,
+};
 ```
 
-Each session has a `analysisResults` which is an array of `AnalysisResult`. Each `AnalysisResult` has the following properties:
-
-- `id`: The unique identifier for the analysis result
-- `prompt`: The user prompt that was used to generate the analysis result
-- `streamMessage`: The stream message from the LLM
-- `errorMessage`: The error message from the LLM
-- `isCompleted`: Whether the analysis result has been completed
-
-For each user prompt, the LLM will run multiple tools (e.g. `query`, `chart`) and return the result as the `streamMessage`. The structure of the `streamMessage` is as follows:
-
-- `text`: the final response from the LLM (streamable)
-- `reasoning`: the reasoning of the LLM (only for reason models)
-- `toolCallMessages`: the message array of the tool calls executed by the LLM
+### Tool Execution Flow
 
-Each `toolCallMessages` has the following properties:
+1. User sends a prompt → creates a user `UIMessage`
+2. AI processes and may call tools → creates assistant `UIMessage` with tool invocations
+3. Tools execute and return:
+   - `llmResult`: Text summary sent back to the LLM
+   - `additionalData`: Rich data stored in `toolAdditionalData` for UI rendering
+4. AI responds with final answer → creates assistant `UIMessage` with text
+5. On completion: `uiMessages` updated, `analysisResult` created with user message ID
 
-- `toolName`: the name of the tool
-- `toolCallId`: the id of the tool call
-- `args`: the arguments of the tool call
-- `llmResult`: the result from the execution of the tool, which will be sent back to the LLM as response.
-- `additionalData`: the additional data of the tool, which can be used to pass the output of the tool to next tool call or the component for rendering.
-
-## Rendering
+### Rendering Tool Results
 
 ```text
 |--------------------------------|
@@ -411,71 +269,103 @@ Each `toolCallMessages` has the following properties:
 |  |--------------------------|  |
 |  | AnalysisResult           |  |
 |  |                          |  |
-|  | streamMessage            |  |
+|  | ErrorMessage             |  |
+|  | ------------             |  |
+|  | UIMessage                |  |
 |  |                          |  |
 |  | |---------------------|  |  |
-|  | | Tools               |  |  |
+|  | | Parts               |  |  |
 |  | |---------------------|  |  |
 |  | | |---------------|   |  |  |
-|  | | |ToolCallMessage|   |  |  |
-|  | | |---------------|   |  |  |
+|  | | |TextPart       |   |  |  |
 |  | | |---------------|   |  |  |
-|  | | |ToolCallMessage|   |  |  |
+|  | | |ToolPart       |   |  |  |
 |  | | |---------------|   |  |  |
 |  | |    ...              |  |  |
 |  | |---------------------|  |  |
 |  |                          |  |
-|  | text                     |  |
 |  |--------------------------|  |
 |--------------------------------|
 ```
 
-## Tools
+### Transfer Additional Tool Output Data to Client
 
-In AI package, we provide a tool() to allow creating function tool for LLM to use. It is an extension of the `tool` from `vercel ai sdk`, and it supports not only `execute` function, but also `context` object and `component` object:
 
-- `execute` needs to return
-  - llmResult: the result send back to LLM (no raw data)
-  - additionalData: the data will be used by `component` and next `tool`
-- `context`
-  - provide e.g. runtime or async data for `execute`
-  - `execute` can access `context` via `options.context`
-- `component`
-  - use `additionalData` to render a React component for this `tool`
+#### The Problem
 
-For example, the `query` tool is defined as follows:
+When tools execute, they often generate additional data (like detailed search results, charts, metadata) that needs to be sent to the client for UI rendering, but should NOT be included in the conversation history sent back to the LLM.
 
-```ts
-const functions = {
-  weather: tool({
-    description: 'Get the weather in a city from a weather station',
-    parameters: z.object({cityName: z.string()}),
-    execute: async ({cityName}, options) => {
-      const getStation = options.context?.getStation;
-      const station = getStation ? await getStation(cityName) : null;
-      return {
-        llmResult: `The weather in ${cityName} is sunny from weather station ${station}.`,
-        additionalData: {
-          weather: 'sunny',
-          station,
-        },
-      };
-    },
-    context: {
-      getStation: async (cityName: string) => {
-        const stations = {
-          'New York': '123',
-          'Los Angeles': '456',
-          Chicago: '789',
-        };
-        return stations[cityName];
-      },
-    },
-    component: WeatherStation,
-  }),
-};
+If the tool execution is done on the server side, the additional data needs to be transferred to the client side for UI rendering. We use the `data-tool-additional-output` data part type to transfer the additional data to the client.
+
+#### Using `transient: true`
+
+The AI SDK v5 provides a built-in solution through the `transient` flag on data parts. When you write a data part with `transient: true`, the SDK automatically prevents it from being added to the message history.
+
+##### Backend Implementation (route.ts)
+
+```typescript
+writer.write({
+  type: 'data-tool-additional-output',
+  transient: true, // Won't be added to message history
+  data: {
+    toolCallId: chunk.toolCallId,
+    toolName: chunk.toolName,
+    output: getToolAdditionalData(chunk.toolCallId),
+    timestamp: new Date().toISOString(),
+  },
+});
+```
+
+#### The Flow
+
+```text
+Backend (route.ts)
+  │
+  ├─> Tool executes
+  │   └─> writer.write({ 
+  │         type: 'data-tool-additional-output',
+  │         transient: true,  // ✅ SDK handles exclusion
+  │         data: {...}
+  │       })
+  │
+  ↓
+Client receives stream
+  │
+  ├─> onData callback
+  │   └─> setSessionToolAdditionalData() ✅ Stores in toolAdditionalData
+  │
+  └─> messages array ✅ Automatically excludes transient data parts
+
+Session Storage (clean) → AI SDK → UI Display
+                              ↓
+                        Session Storage
+                              ↓
+                        Backend/LLM
 ```
 
+#### Benefits of This Approach
+
+1. **✅ Clean Conversation History**: Transient data parts never appear in message history
+2. **✅ Efficient Token Usage**: No unnecessary data sent to the LLM
+3. **✅ Proper Data Storage**: Tool data is stored separately in `toolAdditionalData`
+4. **✅ UI Flexibility**: Components can access tool data via `toolAdditionalData[toolCallId]`
+5. **✅ Simple & Native**: Uses built-in SDK feature, no custom utilities needed
+6. **✅ Maintainable**: Follows SDK conventions and patterns
+7. **✅ No Manual Filtering**: SDK handles exclusion automatically
+
+#### Usage in Components
+
+To access the additional tool data in your components:
+
+```tsx
+const currentSession = useRoomStore((state) => state.ai.getCurrentSession());
+const toolData = currentSession?.toolAdditionalData?.[toolCallId];
+```
+
+#### Alternative Considered: Message Annotations
+
+AI SDK v5 supports message annotations, but these are still part of the message structure. The `transient` flag is specifically designed for data that should only be sent once and not persist in conversation history.
+
 ## Advanced Features
 
 - **Custom AI Tools**: Define custom tools for AI to use with the tool() function