@sqlrooms/ai 0.7.0 → 0.8.0

package/README.md

@@ -22,23 +22,108 @@ yarn add @sqlrooms/ai
 ### Setting Up AI Integration
 
 ```tsx
-import {createAiSlice, createDefaultAiConfig, useAiStore} from '@sqlrooms/ai';
+import {createAiSlice, createDefaultAiConfig} from '@sqlrooms/ai';
 import {createProjectStore} from '@sqlrooms/project-builder';
 
 // Create a project store with AI capabilities
-const useStore = createProjectStore({
-  ai: createAiSlice(createDefaultAiConfig()),
+const {projectStore, useProjectStore} = createProjectStore({
+  // Base project configuration
+  ...createProjectSlice({
+    config: {
+      // Your project configuration
+      ...createDefaultAiConfig(), // Default AI configuration
+    },
+  }),
+  // Add AI slice
+  ...createAiSlice({
+    getApiKey: (modelProvider) => {
+      // Return API key for the specified model provider
+      return process.env.OPENAI_API_KEY || '';
+    },
+    initialAnalysisPrompt: 'What insights can you provide from my data?',
+    // Optional: Add custom tools
+    customTools: {
+      // Your custom tools
+    },
+    // Optional: Custom instructions for the AI
+    getInstructions: (tablesSchema) => {
+      return `Analyze the following tables: ${tablesSchema.map((t) => t.name).join(', ')}`;
+    },
+  }),
 });
 
 function MyApp() {
   return (
-    <ProjectStateProvider projectStore={useStore}>
+    <ProjectStateProvider projectStore={projectStore}>
       <MyDataApp />
     </ProjectStateProvider>
   );
 }
 ```
 
+### Advanced Store Configuration
+
+For more complex applications, you can combine multiple slices:
+
+```tsx
+import {
+  createAiSlice,
+  createDefaultAiConfig,
+  AiSliceConfig,
+} from '@sqlrooms/ai';
+import {
+  createSqlEditorSlice,
+  createDefaultSqlEditorConfig,
+} from '@sqlrooms/sql-editor';
+import {
+  createProjectStore,
+  createProjectSlice,
+} from '@sqlrooms/project-builder';
+
+// Define your application state type
+export type AppState = ProjectState<AppConfig> &
+  AiSliceState &
+  SqlEditorSliceState;
+
+// Create the store with multiple slices
+export const {projectStore, useProjectStore} = createProjectStore<
+  AppConfig,
+  AppState
+>((set, get, store) => ({
+  // Base project slice
+  ...createProjectSlice({
+    config: {
+      // Your base configuration
+      ...createDefaultAiConfig({
+        // Optional: Pre-configured AI sessions
+        sessions: [
+          {
+            id: 'default-session',
+            name: 'Default Analysis',
+            modelProvider: 'openai',
+            model: 'gpt-4o',
+            analysisResults: [],
+            createdAt: new Date(),
+          },
+        ],
+        currentSessionId: 'default-session',
+      }),
+      ...createDefaultSqlEditorConfig(),
+    },
+  }),
+  // AI slice
+  ...createAiSlice({
+    getApiKey: (modelProvider) => {
+      // Return API key based on provider
+      return apiKeys[modelProvider] || '';
+    },
+    // Custom tools and instructions
+  }),
+  // SQL Editor slice
+  ...createSqlEditorSlice(),
+}));
+```
+
 ### Using AI Query Controls
 
 ```tsx
@@ -46,8 +131,8 @@ import {QueryControls} from '@sqlrooms/ai';
 
 function AiQueryPanel() {
   return (
-    <div className="p-4 border rounded-lg">
-      <h2 className="text-xl font-bold mb-4">Ask AI</h2>
+    <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)}
@@ -61,17 +146,20 @@ function AiQueryPanel() {
 
 ```tsx
 import {AnalysisResultsContainer, AnalysisResult} from '@sqlrooms/ai';
-import {useAiStore} from '@sqlrooms/ai';
 
 function AnalysisPanel() {
-  const {analysisResults} = useAiStore();
+  // Get the current session and its analysis results
+  const currentSession = useProjectStore((state) =>
+    state.ai.getCurrentSession(),
+  );
+  const analysisResults = currentSession?.analysisResults || [];
 
   return (
-    <div className="p-4 border rounded-lg">
-      <h2 className="text-xl font-bold mb-4">AI Analysis</h2>
+    <div className="rounded-lg border p-4">
+      <h2 className="mb-4 text-xl font-bold">AI Analysis</h2>
       <AnalysisResultsContainer>
-        {analysisResults.map((result, index) => (
-          <AnalysisResult key={index} result={result} />
+        {analysisResults.map((result) => (
+          <AnalysisResult key={result.id} result={result} />
         ))}
       </AnalysisResultsContainer>
     </div>
@@ -82,33 +170,297 @@ function AnalysisPanel() {
 ### Working with AI State
 
 ```tsx
-import {useAiStore} from '@sqlrooms/ai';
-
 function AiStatusIndicator() {
-  const {isProcessing, lastQuery, error} = useAiStore();
+  const isRunningAnalysis = useProjectStore(
+    (state) => state.ai.isRunningAnalysis,
+  );
+  const analysisPrompt = useProjectStore((state) => state.ai.analysisPrompt);
+  const currentSession = useProjectStore((state) =>
+    state.ai.getCurrentSession(),
+  );
+  const lastResult =
+    currentSession?.analysisResults[currentSession.analysisResults.length - 1];
 
-  if (isProcessing) {
-    return <div>AI is thinking...</div>;
+  if (isRunningAnalysis) {
+    return <div>AI is analyzing your data...</div>;
   }
 
-  if (error) {
-    return <div>Error: {error.message}</div>;
+  if (lastResult?.errorMessage) {
+    return <div>Error: {lastResult.errorMessage.message}</div>;
   }
 
-  if (lastQuery) {
-    return <div>Last query: "{lastQuery}"</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 = useProjectStore((state) => state.ai.analysisPrompt);
+```
+
+#### `isRunningAnalysis`
+
+Boolean flag indicating whether an analysis is currently in progress.
+
+```tsx
+const isRunning = useProjectStore((state) => state.ai.isRunningAnalysis);
+```
+
+#### `tools`
+
+Record of available AI tools that can be used during analysis.
+
+```tsx
+const availableTools = useProjectStore((state) => state.ai.tools);
+```
+
+#### `analysisAbortController`
+
+Optional AbortController instance that can be used to cancel an ongoing analysis.
+
+```tsx
+const abortController = useProjectStore(
+  (state) => state.ai.analysisAbortController,
+);
+```
+
+### Methods
+
+#### `setAnalysisPrompt(prompt: string)`
+
+Sets the current analysis prompt text.
+
+```tsx
+const setPrompt = useProjectStore((state) => state.ai.setAnalysisPrompt);
+setPrompt('Analyze sales trends for the last quarter');
+```
+
+#### `startAnalysis()`
+
+Starts the analysis process using the current prompt.
+
+```tsx
+const startAnalysis = useProjectStore((state) => state.ai.startAnalysis);
+await startAnalysis();
+```
+
+#### `cancelAnalysis()`
+
+Cancels any ongoing analysis.
+
+```tsx
+const cancelAnalysis = useProjectStore((state) => state.ai.cancelAnalysis);
+cancelAnalysis();
+```
+
+#### `setAiModel(modelProvider: string, model: string)`
+
+Sets the AI model and provider for the current session.
+
+```tsx
+const setModel = useProjectStore((state) => state.ai.setAiModel);
+setModel('openai', 'gpt-4o');
+```
+
+#### `createSession(name?: string, modelProvider?: string, model?: string)`
+
+Creates a new analysis session with optional name and model settings.
+
+```tsx
+const createSession = useProjectStore((state) => state.ai.createSession);
+createSession('Financial Analysis', 'openai', 'gpt-4o');
+```
+
+#### `switchSession(sessionId: string)`
+
+Switches to a different analysis session by ID.
+
+```tsx
+const switchSession = useProjectStore((state) => state.ai.switchSession);
+switchSession('session-123');
+```
+
+#### `renameSession(sessionId: string, name: string)`
+
+Renames an existing analysis session.
+
+```tsx
+const renameSession = useProjectStore((state) => state.ai.renameSession);
+renameSession('session-123', 'Q4 Sales Analysis');
+```
+
+#### `deleteSession(sessionId: string)`
+
+Deletes an analysis session by ID.
+
+```tsx
+const deleteSession = useProjectStore((state) => state.ai.deleteSession);
+deleteSession('session-123');
+```
+
+#### `getCurrentSession()`
+
+Returns the current active analysis session.
+
+```tsx
+const currentSession = useProjectStore((state) => state.ai.getCurrentSession());
+```
+
+#### `deleteAnalysisResult(sessionId: string, resultId: string)`
+
+Deletes a specific analysis result from a session.
+
+```tsx
+const deleteResult = useProjectStore((state) => state.ai.deleteAnalysisResult);
+deleteResult('session-123', 'result-456');
+```
+
+#### `findToolComponent(toolName: string)`
+
+Finds the React component associated with a specific tool.
+
+```tsx
+const ChartComponent = useProjectStore((state) =>
+  state.ai.findToolComponent('chart'),
+);
+```
+
+## Data Structure
+
+The basic data structure of the AI package is:
+
+```ts
+ai: {
+  sessions: [
+    {
+      id: defaultSessionId,
+      name: 'Default Session',
+      modelProvider: 'openai',
+      model: 'gpt-4o-mini',
+      analysisResults: [],
+      createdAt: new Date(),
+    },
+  ],
+  currentSessionId: defaultSessionId,
+}
+```
+
+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
+
+Each `toolCallMessages` has the following properties:
+
+- `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
+
+```
+|--------------------------------|
+| AnalysisResultsContainer       |
+|--------------------------------|
+|  |--------------------------|  |
+|  | AnalysisResult           |  |
+|  |                          |  |
+|  | streamMessage            |  |
+|  |                          |  |
+|  | |---------------------|  |  |
+|  | | Tools               |  |  |
+|  | |---------------------|  |  |
+|  | | |---------------|   |  |  |
+|  | | |ToolCallMessage|   |  |  |
+|  | | |---------------|   |  |  |
+|  | | |---------------|   |  |  |
+|  | | |ToolCallMessage|   |  |  |
+|  | | |---------------|   |  |  |
+|  | |    ...              |  |  |
+|  | |---------------------|  |  |
+|  |                          |  |
+|  | text                     |  |
+|  |--------------------------|  |
+|--------------------------------|
+```
+
+## Tools
+
+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`
+
+For example, the `query` tool is defined as follows:
+
+```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,
+  }),
+};
+```
+
 ## Advanced Features
 
-- **Custom AI Tools**: Define custom tools for AI to use
-- **Query Templates**: Create and manage reusable query templates
-- **Result Visualization**: Automatically visualize AI analysis results
-- **Conversation Context**: Maintain context across multiple queries
+- **Custom AI Tools**: Define custom tools for AI to use with the tool() function
+- **Multiple Sessions**: Create and manage multiple analysis sessions for different purposes
+- **Model Selection**: Switch between different AI models and providers
+- **Result Management**: Save, delete, and organize analysis results
+- **Conversation Context**: Maintain context across multiple queries in a session
 - **Feedback Loop**: Collect user feedback to improve AI responses
 
 For more information, visit the SQLRooms documentation.