@lightdash/common 0.2104.6 → 0.2104.8

package/dist/types/ee/AiAgent/schemas/tools/toolImproveContextArgs.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { AiResultType } from '../../types';
+import { baseOutputMetadataSchema } from '../outputMetadata';
+import { createToolSchema } from '../toolSchemaBuilder';
+export const TOOL_IMPROVE_CONTEXT_DESCRIPTION = `
+Captures learnings from user corrections, clarifications, and guidance to improve future responses.
+
+**Supported Learning Categories:**
+- explore_selection: Which tables/explores to use for specific types of queries
+- field_selection: Which fields to use for specific metrics or dimensions
+- filter_logic: How to apply filters for calculations
+- calculation: How to perform specific calculations or aggregations
+- other: General preferences, formatting, or methodologies
+
+**Technical Requirements:**
+- Must provide original query context that led to the learning
+- Must capture what was incorrect and what the correct approach is
+- Must categorize the learning into one of the supported categories
+- Must provide a confidence score (0-1) indicating if this is a learnable pattern
+- Must generate a clear, actionable instruction to append to agent settings
+- Instructions should be specific and context-aware (not overly generic)
+`;
+export const toolImproveContextArgsSchema = createToolSchema({
+    type: AiResultType.IMPROVE_CONTEXT,
+    description: TOOL_IMPROVE_CONTEXT_DESCRIPTION,
+})
+    .extend({
+    originalQuery: z
+        .string()
+        .describe('The original user query that led to incorrect results'),
+    incorrectResponse: z
+        .string()
+        .describe('What the AI incorrectly suggested or returned'),
+    correctResponse: z
+        .string()
+        .describe('What the user corrected or clarified'),
+    category: z
+        .enum([
+        'explore_selection',
+        'field_selection',
+        'filter_logic',
+        'calculation',
+        'other',
+    ])
+        .describe('Category of the learning'),
+    confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .describe('Confidence score that this is a learnable learning or more context is needed'),
+    suggestedInstruction: z
+        .string()
+        .describe('The instruction to append to agent settings'),
+})
+    .build();
+export const toolImproveContextOutputSchema = z.object({
+    result: z.string(),
+    metadata: baseOutputMetadataSchema,
+});
+//# sourceMappingURL=toolImproveContextArgs.js.map

package/dist/types/ee/AiAgent/schemas/tools/toolImproveContextArgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolImproveContextArgs.js","sourceRoot":"","sources":["../../../../../../src/ee/AiAgent/schemas/tools/toolImproveContextArgs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,CAAC,MAAM,gCAAgC,GAAG;;;;;;;;;;;;;;;;;CAiB/C,CAAC;AAEF,MAAM,CAAC,MAAM,4BAA4B,GAAG,gBAAgB,CAAC;IACzD,IAAI,EAAE,YAAY,CAAC,eAAe;IAClC,WAAW,EAAE,gCAAgC;CAChD,CAAC;KACG,MAAM,CAAC;IACJ,aAAa,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,CAAC,uDAAuD,CAAC;IACtE,iBAAiB,EAAE,CAAC;SACf,MAAM,EAAE;SACR,QAAQ,CAAC,+CAA+C,CAAC;IAC9D,eAAe,EAAE,CAAC;SACb,MAAM,EAAE;SACR,QAAQ,CAAC,sCAAsC,CAAC;IACrD,QAAQ,EAAE,CAAC;SACN,IAAI,CAAC;QACF,mBAAmB;QACnB,iBAAiB;QACjB,cAAc;QACd,aAAa;QACb,OAAO;KACV,CAAC;SACD,QAAQ,CAAC,0BAA0B,CAAC;IACzC,UAAU,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACL,8EAA8E,CACjF;IACL,oBAAoB,EAAE,CAAC;SAClB,MAAM,EAAE;SACR,QAAQ,CAAC,6CAA6C,CAAC;CAC/D,CAAC;KACD,KAAK,EAAE,CAAC;AAMb,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,wBAAwB;CACrC,CAAC,CAAC"}

package/dist/types/ee/AiAgent/schemas/tools/toolProposeChangeArgs.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { AiResultType } from '../../types';
+import { customMetricBaseSchema } from '../customMetrics';
+import { getFieldIdSchema } from '../fieldId';
+import { createToolSchema } from '../toolSchemaBuilder';
+// ============================================================================
+// Tool Description
+// ============================================================================
+export const TOOL_PROPOSE_CHANGE_DESCRIPTION = `
+Creates a change proposal for tables, metrics, and dimensions. Changes are applied immediately but can be reviewed and rejected afterward.
+
+**Supported Operations:**
+- Update table descriptions and labels
+- Update metric/dimension descriptions and labels
+- Create new metrics
+
+**Technical Requirements:**
+- When updating descriptions or labels, must preserve as much original content as possible
+- Descriptions should maintain their original format (preserve complete value and formatting)
+- Must provide entity table name, rationale, and change details
+- Changes are tracked with proposer information and timestamp
+- For updates: use "replace" operation with complete updated value (not partial)
+- For adding new properties: use "add" operation (creates property if it does not exist)
+- For new metrics: use "create" operation with full metric definition
+`;
+const getPatchDescription = (type) => `Patch to apply to the ${type}. You can omit/set-to-null any fields you don't want to change.`;
+// ============================================================================
+// Operation Schemas
+// ============================================================================
+/**
+ * Op schema can be configured on per-field basis to have a appropriate type and allow applicable operations
+ */
+const getOpSchema = (type) => z.discriminatedUnion('op', [
+    z
+        .object({ op: z.literal('replace'), value: type })
+        .describe([
+        'Replace (overwrite) the value of the field.',
+        'Updates the **entire** value of the field to reflect the necessary changes, replacing the current value entirely.',
+        'Even if only the part is being changed, make sure to pass the entire value with changes included so that no part is lost.',
+    ].join('\n')),
+    z
+        .object({ op: z.literal('add'), value: type })
+        .describe('Add a new value to the field. (Creates a new property if it does not exist)'),
+    // z.object({
+    //   op: z.literal("push"),
+    //   value: z.any(),
+    //   index: z.number().nullable() // add later to support `"path": "/tags/-"` / "path": "/tags/0" if no index, default to ops on array
+    // }),
+    // z.object({ op: z.literal("remove") }),
+]);
+const stringOpSchema = getOpSchema(z.string());
+// ============================================================================
+// Entity Change Schemas
+// ============================================================================
+const TableChangeSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('update'),
+        patch: z
+            .object({
+            description: stringOpSchema.nullable(),
+            label: stringOpSchema.nullable(),
+        })
+            .describe(getPatchDescription('table')),
+    }),
+]);
+const DimensionChangeSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('update'),
+        patch: z
+            .object({
+            label: stringOpSchema.nullable(),
+            description: stringOpSchema.nullable(),
+        })
+            .describe(getPatchDescription('dimension')),
+    }),
+    // z.object({
+    //   type: z.literal('delete'),
+    // })
+]);
+const MetricChangeSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('create'),
+        value: z.discriminatedUnion('entityType', [
+            z
+                .object({
+                entityType: z.literal('metric'),
+                metric: customMetricBaseSchema,
+            })
+                .describe('Create a new metric'),
+        ]),
+    }),
+    z.object({
+        type: z.literal('update'),
+        patch: z
+            .object({
+            label: stringOpSchema.nullable(),
+            description: stringOpSchema.nullable(),
+            // aiHint: OpSchema,
+        })
+            .describe(getPatchDescription('metric')),
+    }),
+]);
+// ============================================================================
+// Main Change Schema
+// ============================================================================
+const changeSchema = z.discriminatedUnion('entityType', [
+    z.object({
+        entityType: z.literal('table'),
+        value: TableChangeSchema,
+    }),
+    z.object({
+        entityType: z.literal('dimension'),
+        fieldId: getFieldIdSchema({ additionalDescription: '' }),
+        value: DimensionChangeSchema,
+    }),
+    z.object({
+        entityType: z.literal('metric'),
+        fieldId: getFieldIdSchema({
+            additionalDescription: 'if you are creating a new metric, this is the field id of the new metric not the dimension id',
+        }),
+        value: MetricChangeSchema,
+    }),
+]);
+// ============================================================================
+// Tool Schema Export
+// ============================================================================
+export const toolProposeChangeArgsSchema = createToolSchema({
+    type: AiResultType.PROPOSE_CHANGE,
+    description: TOOL_PROPOSE_CHANGE_DESCRIPTION,
+})
+    .extend({
+    entityTableName: z
+        .string()
+        .describe('The name of the table/explore being modified'),
+    rationale: z
+        .string()
+        .describe('Brief explanation of why this change is being proposed and what it improves'),
+    change: changeSchema,
+})
+    .build();
+export const toolProposeChangeOutputSchema = z.object({
+    result: z.string(),
+    metadata: z.discriminatedUnion('status', [
+        z.object({
+            status: z.literal('success'),
+            changeUuid: z.string(),
+            userFeedback: z
+                .enum(['accepted', 'rejected'])
+                .default('accepted')
+                .optional(),
+        }),
+        z.object({
+            status: z.literal('error'),
+        }),
+    ]),
+});
+//# sourceMappingURL=toolProposeChangeArgs.js.map

package/dist/types/ee/AiAgent/schemas/tools/toolProposeChangeArgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolProposeChangeArgs.js","sourceRoot":"","sources":["../../../../../../src/ee/AiAgent/schemas/tools/toolProposeChangeArgs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,MAAM,CAAC,MAAM,+BAA+B,GAAG;;;;;;;;;;;;;;;;CAgB9C,CAAC;AAQF,MAAM,mBAAmB,GAAG,CAAC,IAAsC,EAAE,EAAE,CACnE,yBAAyB,IAAI,iEAAiE,CAAC;AAEnG,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,WAAW,GAAG,CAAyB,IAAO,EAAE,EAAE,CACpD,CAAC,CAAC,kBAAkB,CAAC,IAAI,EAAE;IACvB,CAAC;SACI,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SACjD,QAAQ,CACL;QACI,6CAA6C;QAC7C,mHAAmH;QACnH,2HAA2H;KAC9H,CAAC,IAAI,CAAC,IAAI,CAAC,CACf;IACL,CAAC;SACI,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SAC7C,QAAQ,CACL,6EAA6E,CAChF;IACL,aAAa;IACb,2BAA2B;IAC3B,oBAAoB;IACpB,sIAAsI;IACtI,MAAM;IACN,yCAAyC;CAC5C,CAAC,CAAC;AAEP,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAE/C,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,MAAM,iBAAiB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACnD,CAAC,CAAC,MAAM,CAAC;QACL,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,KAAK,EAAE,CAAC;aACH,MAAM,CAAC;YACJ,WAAW,EAAE,cAAc,CAAC,QAAQ,EAAE;YACtC,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;SACN,CAAC;aAC9B,QAAQ,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;KAC9C,CAAC;CACL,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACvD,CAAC,CAAC,MAAM,CAAC;QACL,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,KAAK,EAAE,CAAC;aACH,MAAM,CAAC;YACJ,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;YAChC,WAAW,EAAE,cAAc,CAAC,QAAQ,EAAE;SACR,CAAC;aAClC,QAAQ,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;KAClD,CAAC;IACF,aAAa;IACb,+BAA+B;IAC/B,KAAK;CACR,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACpD,CAAC,CAAC,MAAM,CAAC;QACL,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,KAAK,EAAE,CAAC,CAAC,kBAAkB,CAAC,YAAY,EAAE;YACtC,CAAC;iBACI,MAAM,CAAC;gBACJ,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC/B,MAAM,EAAE,sBAAsB;aACjC,CAAC;iBACD,QAAQ,CAAC,qBAAqB,CAAC;SACvC,CAAC;KACL,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACL,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,KAAK,EAAE,CAAC;aACH,MAAM,CAAC;YACJ,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;YAChC,WAAW,EAAE,cAAc,CAAC,QAAQ,EAAE;YACtC,oBAAoB;SACO,CAAC;aAC/B,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;KAC/C,CAAC;CACL,CAAC,CAAC;AAEH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,MAAM,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,YAAY,EAAE;IACpD,CAAC,CAAC,MAAM,CAAC;QACL,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAC9B,KAAK,EAAE,iBAAiB;KAC3B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACL,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;QAClC,OAAO,EAAE,gBAAgB,CAAC,EAAE,qBAAqB,EAAE,EAAE,EAAE,CAAC;QACxD,KAAK,EAAE,qBAAqB;KAC/B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACL,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC/B,OAAO,EAAE,gBAAgB,CAAC;YACtB,qBAAqB,EACjB,+FAA+F;SACtG,CAAC;QACF,KAAK,EAAE,kBAAkB;KAC5B,CAAC;CACL,CAAC,CAAC;AAEH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,MAAM,CAAC,MAAM,2BAA2B,GAAG,gBAAgB,CAAC;IACxD,IAAI,EAAE,YAAY,CAAC,cAAc;IACjC,WAAW,EAAE,+BAA+B;CAC/C,CAAC;KACG,MAAM,CAAC;IACJ,eAAe,EAAE,CAAC;SACb,MAAM,EAAE;SACR,QAAQ,CAAC,8CAA8C,CAAC;IAC7D,SAAS,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,CACL,6EAA6E,CAChF;IACL,MAAM,EAAE,YAAY;CACvB,CAAC;KACD,KAAK,EAAE,CAAC;AAQb,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE;QACrC,CAAC,CAAC,MAAM,CAAC;YACL,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;YAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;YACtB,YAAY,EAAE,CAAC;iBACV,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;iBAC9B,OAAO,CAAC,UAAU,CAAC;iBACnB,QAAQ,EAAE;SAClB,CAAC;QACF,CAAC,CAAC,MAAM,CAAC;YACL,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;SAC7B,CAAC;KACL,CAAC;CACL,CAAC,CAAC"}

package/dist/types/ee/AiAgent/schemas/tools/toolRunMetricQueryArgs.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { customMetricsSchema } from '../customMetrics';
+import { filtersSchemaTransformed, filtersSchemaV2 } from '../filters';
+import { baseOutputMetadataSchema } from '../outputMetadata';
+import { tableCalcsSchema } from '../tableCalcs/tableCalcs';
+import { createToolSchema } from '../toolSchemaBuilder';
+import { tableVizConfigSchema } from '../visualizations';
+export const TOOL_RUN_METRIC_QUERY_DESCRIPTION = `Tool: runMetricQuery
+
+Purpose:
+Run a metric query and get the results as CSV data. This is useful for data analysis and export.
+
+Usage Tips:
+- Specify the exploreName, dimensions, metrics, and any filters needed for your query
+- Results are returned as CSV formatted text
+- Use this when you need to analyze data or export query results
+- The query respects the same limits and permissions as other visualization tools
+`;
+export const toolRunMetricQueryArgsSchema = createToolSchema({
+    type: 'run_metric_query',
+    description: TOOL_RUN_METRIC_QUERY_DESCRIPTION,
+})
+    .extend({
+    vizConfig: tableVizConfigSchema,
+    customMetrics: customMetricsSchema,
+    tableCalculations: tableCalcsSchema,
+    filters: filtersSchemaV2
+        .nullable()
+        .describe('Filters to apply to the query. Filtered fields must exist in the selected explore or should be referenced from the custom metrics.'),
+})
+    .build();
+export const toolRunMetricQueryArgsSchemaTransformed = toolRunMetricQueryArgsSchema.transform((data) => ({
+    ...data,
+    customMetrics: customMetricsSchema.parse(data.customMetrics ?? []),
+    filters: filtersSchemaTransformed.parse(data.filters ?? null),
+}));
+export const toolRunMetricQueryOutputSchema = z.object({
+    result: z.string(),
+    metadata: baseOutputMetadataSchema,
+});
+//# sourceMappingURL=toolRunMetricQueryArgs.js.map

package/dist/types/ee/AiAgent/schemas/tools/toolRunMetricQueryArgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRunMetricQueryArgs.js","sourceRoot":"","sources":["../../../../../../src/ee/AiAgent/schemas/tools/toolRunMetricQueryArgs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,MAAM,CAAC,MAAM,iCAAiC,GAAG;;;;;;;;;;CAUhD,CAAC;AAEF,MAAM,CAAC,MAAM,4BAA4B,GAAG,gBAAgB,CAAC;IACzD,IAAI,EAAE,kBAAkB;IACxB,WAAW,EAAE,iCAAiC;CACjD,CAAC;KACG,MAAM,CAAC;IACJ,SAAS,EAAE,oBAAoB;IAC/B,aAAa,EAAE,mBAAmB;IAClC,iBAAiB,EAAE,gBAAgB;IACnC,OAAO,EAAE,eAAe;SACnB,QAAQ,EAAE;SACV,QAAQ,CACL,oIAAoI,CACvI;CACR,CAAC;KACD,KAAK,EAAE,CAAC;AAMb,MAAM,CAAC,MAAM,uCAAuC,GAChD,4BAA4B,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC9C,GAAG,IAAI;IACP,aAAa,EAAE,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC;IAClE,OAAO,EAAE,wBAAwB,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;CAChE,CAAC,CAAC,CAAC;AAMR,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,wBAAwB;CACrC,CAAC,CAAC"}

package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts

@@ -1665,14 +1665,6 @@ export declare const toolRunQueryArgsSchema: z.ZodObject<{
         })[] | null;
         type: "and" | "or";
     } | null;
-    customMetrics: {
-        name: string;
-        label: string;
-        table: string;
-        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
-        description: string;
-        baseDimensionName: string;
-    }[] | null;
     chartConfig: {
         groupBy: string[] | null;
         stackBars: boolean | null;
@@ -1687,6 +1679,14 @@ export declare const toolRunQueryArgsSchema: z.ZodObject<{
         secondaryYAxisMetric: string | null;
         secondaryYAxisLabel: string | null;
     } | null;
+    customMetrics: {
+        name: string;
+        label: string;
+        table: string;
+        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
+        description: string;
+        baseDimensionName: string;
+    }[] | null;
     title: string;
     queryConfig: {
         dimensions: string[];
@@ -1964,14 +1964,6 @@ export declare const toolRunQueryArgsSchema: z.ZodObject<{
         })[] | null;
         type: "and" | "or";
     } | null;
-    customMetrics: {
-        name: string;
-        label: string;
-        table: string;
-        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
-        description: string;
-        baseDimensionName: string;
-    }[] | null;
     chartConfig: {
         groupBy: string[] | null;
         stackBars: boolean | null;
@@ -1986,6 +1978,14 @@ export declare const toolRunQueryArgsSchema: z.ZodObject<{
         secondaryYAxisMetric: string | null;
         secondaryYAxisLabel: string | null;
     } | null;
+    customMetrics: {
+        name: string;
+        label: string;
+        table: string;
+        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
+        description: string;
+        baseDimensionName: string;
+    }[] | null;
     title: string;
     queryConfig: {
         dimensions: string[];
@@ -3664,14 +3664,6 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
         })[] | null;
         type: "and" | "or";
     } | null;
-    customMetrics: {
-        name: string;
-        label: string;
-        table: string;
-        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
-        description: string;
-        baseDimensionName: string;
-    }[] | null;
     chartConfig: {
         groupBy: string[] | null;
         stackBars: boolean | null;
@@ -3686,6 +3678,14 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
         secondaryYAxisMetric: string | null;
         secondaryYAxisLabel: string | null;
     } | null;
+    customMetrics: {
+        name: string;
+        label: string;
+        table: string;
+        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
+        description: string;
+        baseDimensionName: string;
+    }[] | null;
     title: string;
     queryConfig: {
         dimensions: string[];
@@ -3975,14 +3975,6 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
             frameType: "rows" | "range";
         } | null;
     })[] | null | undefined;
-    customMetrics?: {
-        name: string;
-        label: string;
-        table: string;
-        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
-        description: string;
-        baseDimensionName: string;
-    }[] | null | undefined;
     chartConfig?: {
         groupBy: string[] | null;
         stackBars: boolean | null;
@@ -3997,6 +3989,14 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
         secondaryYAxisMetric: string | null;
         secondaryYAxisLabel: string | null;
     } | null | undefined;
+    customMetrics?: {
+        name: string;
+        label: string;
+        table: string;
+        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
+        description: string;
+        baseDimensionName: string;
+    }[] | null | undefined;
 }>, {
     filters: import("../../../..").Filters;
     tableCalculations: ({
@@ -4058,14 +4058,6 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
     })[] | null;
     type: AiResultType.QUERY_RESULT;
     description: string;
-    customMetrics: {
-        name: string;
-        label: string;
-        table: string;
-        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
-        description: string;
-        baseDimensionName: string;
-    }[] | null;
     chartConfig: {
         groupBy: string[] | null;
         stackBars: boolean | null;
@@ -4080,6 +4072,14 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
         secondaryYAxisMetric: string | null;
         secondaryYAxisLabel: string | null;
     } | null;
+    customMetrics: {
+        name: string;
+        label: string;
+        table: string;
+        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
+        description: string;
+        baseDimensionName: string;
+    }[] | null;
     title: string;
     queryConfig: {
         dimensions: string[];
@@ -4369,14 +4369,6 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
             frameType: "rows" | "range";
         } | null;
     })[] | null | undefined;
-    customMetrics?: {
-        name: string;
-        label: string;
-        table: string;
-        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
-        description: string;
-        baseDimensionName: string;
-    }[] | null | undefined;
     chartConfig?: {
         groupBy: string[] | null;
         stackBars: boolean | null;
@@ -4391,6 +4383,14 @@ export declare const toolRunQueryArgsSchemaTransformed: z.ZodEffects<z.ZodObject
         secondaryYAxisMetric: string | null;
         secondaryYAxisLabel: string | null;
     } | null | undefined;
+    customMetrics?: {
+        name: string;
+        label: string;
+        table: string;
+        type: import("../../../..").MetricType.PERCENTILE | import("../../../..").MetricType.AVERAGE | import("../../../..").MetricType.COUNT | import("../../../..").MetricType.COUNT_DISTINCT | import("../../../..").MetricType.SUM | import("../../../..").MetricType.MIN | import("../../../..").MetricType.MAX | import("../../../..").MetricType.MEDIAN;
+        description: string;
+        baseDimensionName: string;
+    }[] | null | undefined;
 }>;
 export type ToolRunQueryArgsTransformed = z.infer<typeof toolRunQueryArgsSchemaTransformed>;
 export declare const toolRunQueryOutputSchema: z.ZodObject<{

package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import { AiResultType } from '../../types';
+import { customMetricsSchema } from '../customMetrics';
+import { getFieldIdSchema } from '../fieldId';
+import { filtersSchemaTransformed, filtersSchemaV2 } from '../filters';
+import { baseOutputMetadataSchema } from '../outputMetadata';
+import sortFieldSchema from '../sortField';
+import { tableCalcsSchema } from '../tableCalcs/tableCalcs';
+import { createToolSchema } from '../toolSchemaBuilder';
+import visualizationMetadataSchema from '../visualizationMetadata';
+// Query configuration schema - what data to fetch
+const queryConfigSchema = z.object({
+    exploreName: z
+        .string()
+        .describe('The name of the explore containing the metrics and dimensions used for the chart.'),
+    dimensions: z
+        .array(getFieldIdSchema({ additionalDescription: null }))
+        .describe('The field ids for the dimensions to group the metrics by. dimensions[0] is the primary grouping (x-axis for charts). dimensions[1+] create additional grouping levels.'),
+    metrics: z
+        .array(getFieldIdSchema({ additionalDescription: null }))
+        .describe('The field ids of the metrics to be calculated. They will be grouped by the dimensions.'),
+    sorts: z
+        .array(sortFieldSchema)
+        .describe('Sort configuration for the query, it can use a combination of metrics and dimensions.'),
+    limit: z
+        .number()
+        .nullable()
+        .describe('The total number of data points / rows allowed on the chart.'),
+});
+// Chart-specific configuration for rendering hints
+const chartConfigSchema = z
+    .object({
+    defaultVizType: z
+        .enum([
+        'table',
+        'bar',
+        'horizontal',
+        'line',
+        'scatter',
+        'pie',
+        'funnel',
+    ])
+        .describe('The default visualization type to render'),
+    // Axis field selection
+    xAxisDimension: z
+        .string()
+        .nullable()
+        .describe('The dimension field ID to use for the x-axis. Must be included in queryConfig.dimensions'),
+    yAxisMetrics: z
+        .array(getFieldIdSchema({ additionalDescription: null }))
+        .nullable()
+        .describe('The metric field IDs to display on the y-axis. Must be included in queryConfig.metrics or come from tableCalculations'),
+    // Series creation control
+    groupBy: z
+        .array(getFieldIdSchema({ additionalDescription: null }))
+        .nullable()
+        .describe('Dimensions to split metrics into separate series (e.g., one line per region, one bar per status). IMPORTANT: Do NOT include the x-axis dimension in groupBy - only include dimensions you want to use for breaking down the data into multiple series. Example: dimensions=["order_date", "status"], groupBy=["status"] creates separate series for each status value. Leave null for simple single-series charts.'),
+    // Bar and horizontal bar chart specific
+    xAxisType: z
+        .enum(['category', 'time'])
+        .nullable()
+        .describe('The x-axis type can be categorical for string value or time if the dimension is a date or timestamp. Applies to bar, horizontal, and scatter charts.'),
+    stackBars: z
+        .boolean()
+        .nullable()
+        .describe('If groupBy is provided then this will stack the bars on top of each other instead of side by side. Applies to bar and horizontal charts.'),
+    // Line chart specific
+    lineType: z
+        .enum(['line', 'area'])
+        .nullable()
+        .describe('default line. The type of line to display. If area then the area under the line will be filled in.'),
+    // Funnel chart specific
+    funnelDataInput: z
+        .enum(['row', 'column'])
+        .nullable()
+        .describe('How to interpret funnel data. Use "row" when each row represents a funnel stage (most common). Use "column" when comparing multiple funnels side-by-side.'),
+    // Common display properties
+    xAxisLabel: z
+        .string()
+        .describe('A helpful label to explain the x-axis'),
+    yAxisLabel: z
+        .string()
+        .describe('A helpful label to explain the y-axis'),
+    secondaryYAxisMetric: z
+        .string()
+        .nullable()
+        .describe('(Optional) A single metric field ID to display on a secondary (right) y-axis. Must NOT be included in yAxisMetrics. Use when one metric has a very different scale than others (e.g., percentage vs count).'),
+    secondaryYAxisLabel: z
+        .string()
+        .nullable()
+        .describe('A helpful label for the secondary y-axis'),
+})
+    .nullable();
+export const TOOL_RUN_QUERY_DESCRIPTION = `Tool: runQuery
+
+Purpose:
+Execute a metric query and create a chart artifact. The results can be viewed as a table, bar, horizontal bar, line, scatter, pie, or funnel chart.
+You define the default visualization type to render but users can switch between visualization types after creation.
+
+Chart Type Selection Guide:
+- 'bar': Vertical bars for categorical comparisons (e.g., sales by product)
+- 'horizontal': Horizontal bars for long category names or ranking (e.g., top 10 customers)
+- 'line': Time series trends (e.g., revenue over months)
+- 'scatter': Correlation between two metrics (e.g., ad spend vs revenue)
+- 'pie': Part-to-whole proportions (e.g., market share by segment)
+- 'funnel': Sequential conversion flows (e.g., sales funnel stages)
+- 'table': Raw data display with all fields
+
+Configuration Tips:
+- Specify exploreName, dimensions (for grouping/x-axis), and metrics (for y-axis values)
+- First dimension is the x-axis; additional dimensions can be used for series breakdown via groupBy
+- At least one metric is required for all chart types except table
+- chartConfig.xAxisDimension: Select the primary dimension from queryConfig.dimensions (typically dimensions[0])
+- chartConfig.yAxisMetrics: Select the metrics to display from queryConfig.metrics or tableCalculations
+- chartConfig.groupBy: Use to split data into multiple series (e.g., one line per region). Do NOT include the x-axis dimension. Only include dimensions for series breakdown. Leave null for simple single-series charts.
+- For bar/horizontal charts: use xAxisType 'category' for strings or 'time' for dates/timestamps
+- For bar/horizontal charts: stackBars (when groupBy is provided) stacks bars instead of placing them side by side
+- For line charts: use lineType 'area' to fill the area under the line
+- For scatter charts: each point represents one row of data
+- For funnel charts: set funnelDataInput to 'row' (each row = stage) or 'column' (multiple funnels)
+- Users can switch between visualization types in the UI after creation
+- xAxisLabel and yAxisLabel provide helpful context for chart axes
+`;
+export const toolRunQueryArgsSchema = createToolSchema({
+    type: AiResultType.QUERY_RESULT,
+    description: TOOL_RUN_QUERY_DESCRIPTION,
+})
+    .extend({
+    ...visualizationMetadataSchema.shape,
+    queryConfig: queryConfigSchema,
+    chartConfig: chartConfigSchema,
+    customMetrics: customMetricsSchema,
+    tableCalculations: tableCalcsSchema,
+    filters: filtersSchemaV2.nullable(),
+})
+    .build();
+export const toolRunQueryArgsSchemaTransformed = toolRunQueryArgsSchema
+    .extend({
+    customMetrics: customMetricsSchema.default(null),
+    tableCalculations: tableCalcsSchema.default(null),
+    chartConfig: chartConfigSchema.default(null),
+})
+    .transform((data) => ({
+    ...data,
+    filters: filtersSchemaTransformed.parse(data.filters),
+}));
+export const toolRunQueryOutputSchema = z.object({
+    result: z.string(),
+    metadata: baseOutputMetadataSchema,
+});
+//# sourceMappingURL=toolRunQueryArgs.js.map

package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRunQueryArgs.js","sourceRoot":"","sources":["../../../../../../src/ee/AiAgent/schemas/tools/toolRunQueryArgs.ts"],"names":[],"mappings":"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"}