Merge branch 'ai-operations' of github.com:quadratichq/quadratic into table-code

Author: AyushAgrawal-A2

DEVELOPMENT.md

@@ -300,3 +300,21 @@ This is only required if the `quadratic-community` Auth0 account does not work.
    - Allowed Logout URLs: `http://localhost:3000`
    - Allowed Web Origins: `http://localhost:3000`
    - Allowed Origins (CORS): `http://localhost:3000`
+
+## How to Add AI Tools
+
+1. run `node dev -cas` - you need at least API and Shared to recompile (and probably need core, as there may need to be changes)
+
+2. update `quadraticShared/../aiToolsSpec.ts` for the new tool:
+   - AITool enum (the name of the tool)
+   - AIToolSchema (list of tools)
+   - AIToolsArgsSchema (the zod parameters)
+   - aiToolsSpec (the actual tool and prompt definition)
+
+3. create a ToolCard in `quadraticClient/../toolCards/`
+
+4. add new ToolCard to `quadraticClient/../AIToolCard.tsx`
+
+5. add the action to `quadraticClient/../aiToolsActions.ts`
+
+Note: you may need to restart node dev occasionally if it doesn't pick up your changes.

quadratic-api/src/ai/docs/A1Docs.ts

@@ -0,0 +1,67 @@
+export const A1Docs = `# A1 Docs
+
+Cell references in Quadratic are in A1 notation.
+
+## Rectangular Ranges
+
+Rectangular ranges are references to a range of cells in a sheet. They are referenced by the top left cell and the bottom right cell. For example, A1:C3 is a rectangular range that references the cells A1, B1, C1, A2, B2, C2, A3, B3, and C3.
+
+### Rectangular Range Examples
+
+- D5 - references the cell D5
+- A1:C3 - references the cells A1, B1, C1, A2, B2, C2, A3, B3, and C3
+- A1:A3 - references the cells A1, A2, and A3
+- A1:C1 - references the cells A1, B1, and C1
+
+## Column and Row References
+
+In A1 notation, when referencing an entire column or row, use the column or row name(s).
+
+### Column and Row Examples
+
+- B - references the entire column B
+- B3:B - references all rows in column B starting from row 3
+- 10 - references the entire row 10
+- C4:C - references all columns in row C starting from row 4
+- D2:2 - references all columns in row 2 starting from column D
+
+## Table References
+
+**PREFERRED**: Always use table names (e.g., Table_Name) when working with entire tables or entire columns within tables. Use A1 notation only for non-table data or partial table selections.
+
+Columns within tables may be referenced by their name in A1 notation, eg, Table1[Column Name]. To reference multiple columns within a table, you use Table1[[Name]:[Address]]. In tables, you can also reference parts of the table. If you only want the table names, you can reference it with Table1[#HEADERS]. If you want the data and the headers, you would use Table1[[#DATA],[#HEADERS]]. By default, tables are referenced as Table1[#DATA].
+
+If you need individual cells within a table, you need to use normal A1 reference. For example, if you want the first row of a table, you would reference it using its corresponding A1 reference. Remember that tables usually include a name row as the first row, and a column header row as the second row. (Although these may sometimes be hidden.)
+
+### Table Examples
+
+- Table1 - references the entire table's data
+- Table1[#HEADERS] - references the table headers
+- Table1[[#DATA],[#HEADERS]] - references the entire table including the headers
+- Table1[Column 2] - references a single column within Table1
+- Table1[[Name]:[Address]] - references a range of columns
+
+## Multiple Ranges
+
+ You can reference multiple ranges by combining ranges with commas.
+
+### Multiple Range Examples
+
+- A1:C3,D5:F7
+- A1:C3,D5:F7,G9:I11
+- Table1[Column 2], A1:C3
+
+## Other Sheets
+
+You can reference cells in other sheets by using the sheet name as part of the reference. Note, table names do not need sheet names as table names are unique within the file.
+
+### Other Sheet Examples
+
+- Sheet1!A1:C3
+- Sheet1!A1:C3,Sheet2!D5:F7
+- Sheet1!A1:C3,Sheet2!D5:F7,Sheet3!G9:I11
+- Table1[Column 2],Sheet2!A1:C3
+
+
+
+ `;

quadratic-api/src/ai/docs/QuadraticDocs.ts

@@ -6,9 +6,9 @@ Quadratic combines a familiar spreadsheet and formulas with the power of AI and
 
 Files can be imported by drag and dropping into the sheet, those supported file types are: csv, excel, parquet. SQL can be used to connect to databases. Once in the sheet, data can be analyzed with coding languages and AI.
 
-Data can be exported by following these steps: 1. highlight the data 2. right-click the highlighted data 3. select export to csv 
+Data can be exported by following these steps: 1. highlight the data 2. right-click the highlighted data 3. select export to csv
 
-Files can be shared with other users by selecting the share button in the top right. Quadratic .grid files can be download from the file menu. 
+Files can be shared with other users by selecting the share button in the top right. Quadratic .grid files can be download from the file menu.
 
 Code is inserted via AI or by pressing / while in a cell to open the code selection menu. Code cells can be re-opened to view and edit the code by double clicking or pressing / when selected.
 
@@ -19,4 +19,5 @@ Quadratic cells can be formatted from the toolbar options or by AI, but not via
 Quadratic uses tables commonly to structure data. IMPORTANT: tables do not support Formulas or Code but will in the future. You cannot place Code or Formulas inside of tables.
 
 Code generated in Quadratic is not global to other code cells. The data the code cell outputs to the sheet can be referenced by other cells, but variables in one code cell cannot be read in another. Imports in one code cell do not automatically apply to other code cells.
-`;
+
+Code, data tables, and charts may take up more than one cell on the sheet. When they expand, they may overlap existing content, either directly on the sheet or in other code, table, or chart cells. If this happens, it is called a spill. To fix a spill, use the move_cells tool to move the anchor cell of the table to a different position. Ensure that the position has sufficient space to accommodate the entire range without creating another spill. Ideally, leave a space between the new position and any surrounding content.`;

quadratic-api/src/ai/docs/ValidationDocs.ts

@@ -0,0 +1,22 @@
+export const ValidationDocs = `
+# Validations
+
+## Overview
+
+Validations are used to both verify that cells have allowable data, and to provide messages to the user when they enter a cell.
+
+## How validations are stored
+
+Validations are set per sheet so you cannot add a selection from another sheet to a validation in a different sheet.
+
+## One validation per cell
+
+Each cell can only have one validation. If you add a validation to a range then any validations that overlap with the new validation will be removed. The algorithm either changes the selection to remove the overlap, or, if the selection becomes empty, removes the validation.
+
+## Messages and errors
+
+Adding a message to validations will show the message when the user enters the cell with the cursor. An error will show when the user either enters the cell or hovers over it with the cursor.
+
+## Purpose of validations
+
+You can use validations to create checkboxes and dropdown lists, as well as to add messages or errors to the user when they enter a cell. They make the user experience more interactive and engaging.`;

quadratic-api/src/ai/handler/anthropic.handler.ts

@@ -27,7 +27,12 @@ export const handleAnthropicRequest = async (
 ): Promise<ParsedAIResponse | undefined> => {
   const model = getModelFromModelKey(modelKey);
   const options = getModelOptions(modelKey, args);
-  const { system, messages, tools, tool_choice } = getAnthropicApiArgs(args, options.promptCaching, options.thinking);
+  const { system, messages, tools, tool_choice } = getAnthropicApiArgs(
+    args,
+    options.aiModelMode,
+    options.promptCaching,
+    options.thinking
+  );
 
   const thinking: ThinkingConfigParam = options.thinking
     ? {

quadratic-api/src/ai/handler/bedrock.handler.ts

@@ -15,7 +15,7 @@ export const handleBedrockRequest = async (
 ): Promise<ParsedAIResponse | undefined> => {
   const model = getModelFromModelKey(modelKey);
   const options = getModelOptions(modelKey, args);
-  const { system, messages, tools, tool_choice } = getBedrockApiArgs(args);
+  const { system, messages, tools, tool_choice } = getBedrockApiArgs(args, options.aiModelMode);
 
   const apiArgs: ConverseStreamRequest | ConverseRequest = {
     modelId: model,

quadratic-api/src/ai/handler/genai.handler.ts

@@ -19,7 +19,7 @@ export const handleGenAIRequest = async (
 ): Promise<ParsedAIResponse | undefined> => {
   const model = getModelFromModelKey(modelKey);
   const options = getModelOptions(modelKey, args);
-  const { system, messages, tools, tool_choice } = getGenAIApiArgs(args);
+  const { system, messages, tools, tool_choice } = getGenAIApiArgs(args, options.aiModelMode);
 
   const apiArgs: GenerateContentParameters = {
     model,

quadratic-api/src/ai/handler/openai.handler.ts

@@ -23,7 +23,12 @@ export const handleOpenAIRequest = async (
 ): Promise<ParsedAIResponse | undefined> => {
   const model = getModelFromModelKey(modelKey);
   const options = getModelOptions(modelKey, args);
-  const { messages, tools, tool_choice } = getOpenAIApiArgs(args, options.strictParams, options.imageSupport);
+  const { messages, tools, tool_choice } = getOpenAIApiArgs(
+    args,
+    options.aiModelMode,
+    options.strictParams,
+    options.imageSupport
+  );
 
   let apiArgs: ChatCompletionCreateParamsStreaming | ChatCompletionCreateParamsNonStreaming = {
     model,

quadratic-api/src/ai/helpers/anthropic.helper.ts

@@ -28,6 +28,7 @@ import type {
   AnthropicModelKey,
   BedrockAnthropicModelKey,
   Content,
+  ModelMode,
   ParsedAIResponse,
   ToolResultContent,
   VertexAIAnthropicModelKey,
@@ -105,6 +106,7 @@ function convertToolResultContent(content: ToolResultContent): Array<TextBlockPa
 
 export function getAnthropicApiArgs(
   args: AIRequestHelperArgs,
+  aiModelMode: ModelMode,
   promptCaching: boolean,
   thinking: boolean | undefined
 ): {
@@ -161,7 +163,7 @@ export function getAnthropicApiArgs(
             type: 'tool_use' as const,
             id: toolCall.id,
             name: toolCall.name,
-            input: JSON.parse(toolCall.arguments),
+            input: toolCall.arguments ? JSON.parse(toolCall.arguments) : {},
           })),
         ],
       };
@@ -193,14 +195,17 @@ export function getAnthropicApiArgs(
     }
   }, []);
 
-  const tools = getAnthropicTools(source, toolName);
+  const tools = getAnthropicTools(source, aiModelMode, toolName);
   const tool_choice = tools?.length ? getAnthropicToolChoice(toolName) : undefined;
 
   return { system, messages, tools, tool_choice };
 }
 
-function getAnthropicTools(source: AISource, toolName?: AITool): Tool[] | undefined {
+function getAnthropicTools(source: AISource, aiModelMode: ModelMode, toolName?: AITool): Tool[] | undefined {
   const tools = Object.entries(aiToolsSpec).filter(([name, toolSpec]) => {
+    if (!toolSpec.aiModelModes.includes(aiModelMode)) {
+      return false;
+    }
     if (toolName === undefined) {
       return toolSpec.sources.includes(source);
     }

quadratic-api/src/ai/helpers/bedrock.helper.ts

@@ -30,6 +30,7 @@ import type {
   AIUsage,
   BedrockModelKey,
   Content,
+  ModelMode,
   ParsedAIResponse,
   ToolResultContent,
 } from 'quadratic-shared/typesAndSchemasAI';
@@ -78,7 +79,10 @@ function convertToolResultContent(content: ToolResultContent): ToolResultContent
     });
 }
 
-export function getBedrockApiArgs(args: AIRequestHelperArgs): {
+export function getBedrockApiArgs(
+  args: AIRequestHelperArgs,
+  aiModelMode: ModelMode
+): {
   system: SystemContentBlock[] | undefined;
   messages: Message[];
   tools: Tool[] | undefined;
@@ -104,7 +108,7 @@ export function getBedrockApiArgs(args: AIRequestHelperArgs): {
             toolUse: {
               toolUseId: toolCall.id,
               name: toolCall.name,
-              input: JSON.parse(toolCall.arguments),
+              input: toolCall.arguments ? JSON.parse(toolCall.arguments) : {},
             },
           })),
         ],
@@ -135,14 +139,17 @@ export function getBedrockApiArgs(args: AIRequestHelperArgs): {
     }
   }, []);
 
-  const tools = getBedrockTools(source, toolName);
+  const tools = getBedrockTools(source, aiModelMode, toolName);
   const tool_choice = tools?.length ? getBedrockToolChoice(toolName) : undefined;
 
   return { system, messages, tools, tool_choice };
 }
 
-function getBedrockTools(source: AISource, toolName?: AITool): Tool[] | undefined {
+function getBedrockTools(source: AISource, aiModelMode: ModelMode, toolName?: AITool): Tool[] | undefined {
   const tools = Object.entries(aiToolsSpec).filter(([name, toolSpec]) => {
+    if (!toolSpec.aiModelModes.includes(aiModelMode)) {
+      return false;
+    }
     if (toolName === undefined) {
       return toolSpec.sources.includes(source);
     }