AI Assistant: adjust command descriptions (DevExpress#33636)

Co-authored-by: Raushen <eylau-andrew@mail.ru>

Author: anna-shakhova

packages/devextreme/js/__internal/core/ai_integration/templates/index.ts

@@ -42,8 +42,7 @@ export const templates: PromptTemplates = {
     user: 'User prompt text: {{text}}. Dataset: {{data}}.',
   },
   executeGridAssistant: {
-    // TODO: Implement system prompt when grid operations are ready
-    system: 'You are a helpful AI assistant for a data grid component. The user sends a natural language request describing an operation on the grid (e.g., sorting, filtering, grouping). You receive the user\'s message, a context object describing the current grid state, and a JSON schema describing the available commands and their arguments. Your task is to interpret the user\'s request and return a JSON object with one field: "actions" — an array of command objects, each with "name" (the command name) and "args" (an object of arguments matching the schema). Output must be a valid JSON string, directly parsable by JSON.parse. Do not include any markdown, formatting, or extra text — only the raw JSON object.',
+    system: 'You are a helpful AI assistant for a data grid component. The user sends a natural language request describing an operation on the grid (e.g., sorting, filtering, grouping). You receive the user\'s message, a context object describing the current grid state, and a JSON schema describing the available commands and their arguments. Your task is to interpret the user\'s request and return a JSON object with one field: "actions" — an array of command objects, each with "name" (the command name) and "args" (an object of arguments matching the schema). Output must be a valid JSON string, directly parsable by JSON.parse. Do not include any markdown, formatting, or extra text — only the raw JSON object.\n\nCRITICAL RULE FOR OPTIONAL ARGUMENTS: If an optional argument is not used, the field MUST be ENTIRELY ABSENT from the JSON object — the key must not appear at all. NEVER emit an optional field with value null, empty string "", empty array [], or any placeholder. This rule overrides any instinct to "complete" the object — omitted IS the value.',
     user: 'User request: {{text}}. Grid context: {{context}}.',
   },
 };

packages/devextreme/js/__internal/grids/data_grid/ai_assistant/commands/__tests__/summary.test.ts

@@ -57,6 +57,7 @@ describe('summaryCommand', () => {
     ])('accepts summaryType "%s"', (summaryType) => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType }],
+        groupItems: [],
       }).success).toBe(true);
     });
 
@@ -67,41 +68,59 @@ describe('summaryCommand', () => {
       }).success).toBe(true);
     });
 
-    it('accepts empty object (executability layer rejects it)', () => {
-      expect(summaryCommand.schema.safeParse({}).success).toBe(true);
+    it('rejects empty object (totalItems and groupItems are required)', () => {
+      expect(summaryCommand.schema.safeParse({}).success).toBe(false);
+    });
+
+    it('rejects when totalItems is omitted', () => {
+      expect(summaryCommand.schema.safeParse({
+        groupItems: [{ column: 'amount', summaryType: 'avg' }],
+      }).success).toBe(false);
+    });
+
+    it('rejects when groupItems is omitted', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{ column: 'amount', summaryType: 'sum' }],
+      }).success).toBe(false);
     });
 
     it('rejects an unknown summaryType (including "custom")', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'custom' }],
+        groupItems: [],
       }).success).toBe(false);
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'median' }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when an item is missing column', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ summaryType: 'sum' }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when an item is missing summaryType', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount' }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects unknown properties on the root', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum' }],
+        groupItems: [],
         extra: 1,
       }).success).toBe(false);
     });
 
     it('rejects unknown properties on the item', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum', extra: 1 }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
@@ -113,11 +132,13 @@ describe('summaryCommand', () => {
           showInColumn: 'name',
           displayFormat: 'Sum: {0}',
         }],
+        groupItems: [],
       }).success).toBe(true);
     });
 
     it('accepts showInColumn, displayFormat, showInGroupFooter, alignByColumn on groupItems', () => {
       expect(summaryCommand.schema.safeParse({
+        totalItems: [],
         groupItems: [{
           column: 'amount',
           summaryType: 'avg',
@@ -136,6 +157,7 @@ describe('summaryCommand', () => {
           summaryType: 'sum',
           showInGroupFooter: true,
         }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
@@ -146,47 +168,41 @@ describe('summaryCommand', () => {
           summaryType: 'sum',
           alignByColumn: true,
         }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when showInColumn is not a string', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum', showInColumn: 1 }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when displayFormat is not a string', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum', displayFormat: 5 }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when showInGroupFooter is not a boolean', () => {
       expect(summaryCommand.schema.safeParse({
+        totalItems: [],
         groupItems: [{ column: 'amount', summaryType: 'sum', showInGroupFooter: 'yes' }],
       }).success).toBe(false);
     });
 
     it('rejects when alignByColumn is not a boolean', () => {
       expect(summaryCommand.schema.safeParse({
+        totalItems: [],
         groupItems: [{ column: 'amount', summaryType: 'sum', alignByColumn: 1 }],
       }).success).toBe(false);
     });
   });
 
   describe('execute', () => {
-    it('returns failure when both totalItems and groupItems are empty/omitted', async () => {
-      const instance = await createGrid();
-      const optionSpy = jest.spyOn(instance, 'option');
-      const callbacks = createCallbacks();
-
-      const result = await summaryCommand.execute(instance, callbacks)({});
-
-      expect(result.status).toBe('failure');
-      expect(optionSpy).not.toHaveBeenCalledWith('summary', expect.anything());
-    });
-
-    it('returns failure when both arrays are explicitly empty', async () => {
+    it('returns failure when both arrays are empty', async () => {
       const instance = await createGrid();
       const optionSpy = jest.spyOn(instance, 'option');
       const callbacks = createCallbacks();
@@ -210,6 +226,7 @@ describe('summaryCommand', () => {
           { column: 'amount', summaryType: 'sum' },
           { column: 'unknown', summaryType: 'avg' },
         ],
+        groupItems: [],
       });
 
       expect(result.status).toBe('failure');
@@ -222,6 +239,7 @@ describe('summaryCommand', () => {
       const callbacks = createCallbacks();
 
       const result = await summaryCommand.execute(instance, callbacks)({
+        totalItems: [],
         groupItems: [{ column: 'unknown', summaryType: 'sum' }],
       });
 
@@ -240,6 +258,7 @@ describe('summaryCommand', () => {
           summaryType: 'sum',
           showInColumn: 'unknown',
         }],
+        groupItems: [],
       });
 
       expect(result.status).toBe('failure');
@@ -263,21 +282,6 @@ describe('summaryCommand', () => {
       expect(result.status).toBe('success');
     });
 
-    it('passes empty arrays when one of the inputs is omitted', async () => {
-      const instance = await createGrid();
-      const optionSpy = jest.spyOn(instance, 'option');
-      const callbacks = createCallbacks();
-
-      await summaryCommand.execute(instance, callbacks)({
-        totalItems: [{ column: 'amount', summaryType: 'sum' }],
-      });
-
-      expect(optionSpy).toHaveBeenCalledWith('summary', {
-        totalItems: [{ column: 'amount', summaryType: 'sum' }],
-        groupItems: [],
-      });
-    });
-
     it('returns failure when option throws', async () => {
       const instance = await createGrid();
       const realOption = instance.option.bind(instance);
@@ -291,6 +295,7 @@ describe('summaryCommand', () => {
 
       const result = await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'amount', summaryType: 'sum' }],
+        groupItems: [],
       });
 
       expect(result.status).toBe('failure');
@@ -304,6 +309,7 @@ describe('summaryCommand', () => {
 
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'amount', summaryType: 'sum' }],
+        groupItems: [],
       });
 
       expect(callbacks.success).toHaveBeenCalledWith(
@@ -316,6 +322,7 @@ describe('summaryCommand', () => {
       const callbacks = createCallbacks();
 
       await summaryCommand.execute(instance, callbacks)({
+        totalItems: [],
         groupItems: [{ column: 'amount', summaryType: 'avg' }],
       });
 
@@ -336,6 +343,7 @@ describe('summaryCommand', () => {
 
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'amount', summaryType: summaryType as 'sum' | 'min' | 'max' | 'avg' | 'count' }],
+        groupItems: [],
       });
 
       expect(callbacks.success).toHaveBeenCalledWith(
@@ -349,6 +357,7 @@ describe('summaryCommand', () => {
 
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'name', summaryType: 'count' }],
+        groupItems: [],
       });
 
       // 'name' has no explicit caption — DevExtreme auto-derives "Name"
@@ -366,6 +375,7 @@ describe('summaryCommand', () => {
           { column: 'amount', summaryType: 'sum' },
           { column: 'amount', summaryType: 'avg' },
         ],
+        groupItems: [],
       });
 
       expect(callbacks.success).toHaveBeenCalledWith(
@@ -391,7 +401,10 @@ describe('summaryCommand', () => {
       const instance = await createGrid();
       const callbacks = createCallbacks();
 
-      await summaryCommand.execute(instance, callbacks)({});
+      await summaryCommand.execute(instance, callbacks)({
+        totalItems: [],
+        groupItems: [],
+      });
 
       expect(callbacks.failure).toHaveBeenCalledWith('Display data summaries.');
     });
@@ -403,6 +416,7 @@ describe('summaryCommand', () => {
       // Single item with unresolved column → failure path, item-list message
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'unknown', summaryType: 'sum' }],
+        groupItems: [],
       });
 
       expect(callbacks.failure).toHaveBeenCalledWith(
@@ -427,16 +441,16 @@ describe('clearSummaryCommand', () => {
   });
 
   describe('execute', () => {
-    it('calls component.option("summary", { groupItems: undefined, totalItems: undefined }) on success', async () => {
+    it('calls component.option("summary", { groupItems: [], totalItems: [] }) on success', async () => {
       const instance = await createGrid();
       const optionSpy = jest.spyOn(instance, 'option');
       const callbacks = createCallbacks();
 
       const result = await clearSummaryCommand.execute(instance, callbacks)();
 
       expect(optionSpy).toHaveBeenCalledWith('summary', {
-        groupItems: undefined,
-        totalItems: undefined,
+        groupItems: [],
+        totalItems: [],
       });
       expect(result.status).toBe('success');
     });

packages/devextreme/js/__internal/grids/data_grid/ai_assistant/commands/summary.ts

@@ -23,8 +23,8 @@ const groupItemSchema = z.object({
 }).strict();
 
 const summaryCommandSchema = z.object({
-  totalItems: z.array(totalItemSchema).optional(),
-  groupItems: z.array(groupItemSchema).optional(),
+  totalItems: z.array(totalItemSchema),
+  groupItems: z.array(groupItemSchema),
 }).strict();
 
 type TotalItem = z.infer<typeof totalItemSchema>;
@@ -69,20 +69,19 @@ const buildDefaultMessage = (
 
 export const summaryCommand = defineGridCommand({
   name: 'summary',
-  description: 'Configure column summaries. totalItems aggregate the entire data set; groupItems aggregate within each group. Provide at least one item across the two arrays — use clearSummary to remove all summaries. Replaces existing summaries entirely; pre-merge with the grid\'s current summary items if you intend to add rather than replace.\n'
+  description: 'Configure column summaries. totalItems aggregate the entire data set; groupItems aggregate within each group. Replaces the configuration entirely — both kinds are written every call. ALWAYS provide BOTH totalItems and groupItems; pass an explicit empty array [] for a kind to clear it. To keep one kind unchanged, copy its current items from the grid context into your args. To ADD items, pre-merge with the kind\'s current items. To REMOVE a specific item, pass the kind\'s remaining items (and copy the other kind unchanged). At least one kind must be non-empty. Use clearSummary only when EVERY summary should be removed.\n'
     + 'Each item supports:\n'
-    + '- column (required): dataField of the column to aggregate.\n'
+    + '- column (required): dataField of the column whose VALUES are aggregated. Phrases like "sum of X", "average X", "total X", "summary for X" → column="X" (X is what gets aggregated).\n'
     + '- summaryType (required): one of "sum", "min", "max", "avg", "count".\n'
-    + '- showInColumn (optional): dataField of the column under which the summary value is rendered. For totalItems, controls which column\'s footer cell shows the value. For groupItems, used when showInGroupFooter=true or alignByColumn=true to pick the column the value is shown under. Must match an existing column.\n'
+    + '- showInColumn (optional): dataField of the column where the value is DISPLAYED (not aggregated). OMIT unless the user explicitly names a second column with a phrase like "show in Y", "display under Y", "in the Y column" → showInColumn="Y". Example: "sum of Amount in the SaleDate column" → column="Amount", showInColumn="SaleDate". One column mentioned → OMIT. For totalItems, controls which footer cell shows the value. For groupItems, showInColumn has effect ONLY when paired with showInGroupFooter=true OR alignByColumn=true — so whenever you set showInColumn on a group item, you MUST also set alignByColumn=true (the default pairing), unless the user explicitly asked for footer placement (then set showInGroupFooter=true instead).\n'
     + '- displayFormat (optional): format template for the rendered value. Placeholders: "{0}" — the formatted summary value; "{1}" — the parent column\'s caption (for group items only resolvable when showInColumn is specified). Example: "Sum: {0}" or "{1}: {0}".\n'
     + 'Group items additionally support:\n'
-    + '- showInGroupFooter (optional, default false): render in the group footer instead of the group row.\n'
-    + '- alignByColumn (optional, default false): when false, group summary items are listed in parentheses after the group row header. When true, items are aligned by their columns within the group row.',
+    + '- showInGroupFooter (optional): OMIT this field unless the user explicitly requests the group footer area. Default behavior renders the summary in the group row (the header that displays the group value). Set to true ONLY when the user explicitly says "group footer", "below the group", or "in the footer". Requests like "in the header", "in the group row", "next to the group name", or no placement mention at all → OMIT (do not set to false either; just omit the field).\n'
+    + '- alignByColumn (optional): OMIT this field unless the user explicitly requests column-aligned layout. Default behavior lists items in parentheses after the group row caption (e.g. "Category: Bikes (Sum: 100, Count: 5)"). Set to true ONLY when the user explicitly asks to "align by column", "show under each column", or "align with the column". Otherwise OMIT.',
   schema: summaryCommandSchema,
   execute: (component, { success, failure }) => (args): Promise<CommandResult> => {
     const columnsController = component.getController('columns');
-    const totalItems = args.totalItems ?? [];
-    const groupItems = args.groupItems ?? [];
+    const { totalItems, groupItems } = args;
     const allItems: SummaryItem[] = [...totalItems, ...groupItems];
 
     const defaultMessage = buildDefaultMessage(totalItems, groupItems, columnsController);
@@ -108,10 +107,7 @@ export const summaryCommand = defineGridCommand({
     }
 
     try {
-      component.option('summary', {
-        totalItems: args.totalItems ?? [],
-        groupItems: args.groupItems ?? [],
-      });
+      component.option('summary', { totalItems, groupItems });
 
       return Promise.resolve(success(defaultMessage));
     } catch {
@@ -122,15 +118,15 @@ export const summaryCommand = defineGridCommand({
 
 export const clearSummaryCommand = defineGridCommand({
   name: 'clearSummary',
-  description: 'Remove all summary items.',
+  description: 'Remove ALL summary items. Do NOT call this for partial removals. Use only when every summary should be cleared (both totalItems and groupItems). To remove a subset — e.g., clear only totalItems while keeping groupItems (or vice versa), or drop a specific item — call the summary command with the items that should remain, since summary replaces existing summaries entirely.',
   schema: z.object({}).strict(),
   execute: (component, { success, failure }) => (): Promise<CommandResult> => {
     const defaultMessage = 'Clear column summaries.';
 
     try {
       component.option('summary', {
-        groupItems: undefined,
-        totalItems: undefined,
+        groupItems: [],
+        totalItems: [],
       });
 
       return Promise.resolve(success(defaultMessage));

packages/devextreme/js/__internal/grids/grid_core/ai_assistant/commands/__tests__/paging.test.ts

@@ -318,7 +318,7 @@ describe('pageIndexCommand', () => {
 
       await pageIndexCommand.execute(instance, callbacks)({ pageIndex: 1 });
 
-      expect(callbacks.success).toHaveBeenCalledWith('Switch the view to page number 1.');
+      expect(callbacks.success).toHaveBeenCalledWith('Switch the view to page number 2.');
     });
 
     it('passes the same default message to failure when executability fails', async () => {
@@ -327,7 +327,7 @@ describe('pageIndexCommand', () => {
 
       await pageIndexCommand.execute(instance, callbacks)({ pageIndex: 2 });
 
-      expect(callbacks.failure).toHaveBeenCalledWith('Switch the view to page number 2.');
+      expect(callbacks.failure).toHaveBeenCalledWith('Switch the view to page number 3.');
     });
   });
 });