@sisense/sdk-ai-core 0.9.0 → 0.13.0

package/dist/engines/build-chart/types.d.ts

@@ -1,37 +1,26 @@
-import { CalculatedMeasureColumn, MeasureColumn } from '@sisense/sdk-data';
-import { ChartType, ChartWidgetProps, StyledColumn, StyledMeasureColumn, WithCommonWidgetProps } from '@sisense/sdk-ui';
+import { ChartType, ChartWidgetProps, WithCommonWidgetProps } from '@sisense/sdk-ui';
 import { HttpClient } from '@sisense/sdk-rest-client';
-import { default as OpenAI } from 'openai';
-import { z } from 'zod';
-import { QueryResult, QuerySummary } from '../build-query/types';
-import { Dataset } from '../../services/nlq/nlq-service';
+import { z } from 'zod/v4';
+import { QueryResult } from '../build-query/types';
+import { ChartState, Dataset, QueryState } from '../../services/nlq/nlq-service';
+import { LanguageModel } from 'ai';
 export type ArtifactReference = {
     artifactId?: string;
 };
 export type ExtendedChartWidgetProps = WithCommonWidgetProps<ChartWidgetProps, 'chart'> & ArtifactReference & {
-    /**
-     * data columns used to generate chart recommendations
-     */
-    dataColumns?: ColumnType[];
+    /** Query state used to generate this chart — needed to revise query structure incrementally */
+    queryState?: QueryState;
+    /** Sample / tabular payload from the query execution. */
+    dataset?: Dataset;
+    /** Optional CSDK chart JSON when a caller persists it alongside NLQ state (distinct from REST `chartState` / {@link QueryState}). */
+    chartState?: ChartState;
 };
 export type NullableChartType = ChartType | null | undefined;
 /**
- * Base chart summary for LLM consumption and asset extraction
+ * Compact CSDK chart configuration for LLM consumption.
+ * Alias for {@link ChartState} — the serialized form produced by `translateChartToJSON`.
  */
-export type BaseChartSummary = {
-    /** Human-readable title of the chart */
-    title?: string;
-    /** Name of the data source used for the chart */
-    dataSourceTitle: string;
-    /** Type of chart (line, bar, pie, etc.) */
-    chartType?: ChartType;
-    /** Summary of applied filters */
-    filters: string;
-    /** Summary of data configuration options */
-    dataOptions: string;
-    /** Summary of styling and visual options */
-    styleOptions: string;
-};
+export type BaseChartSummary = ChartState;
 /**
  * Summary of a chart for LLM consumption and asset extraction
  */
@@ -42,564 +31,322 @@ export interface ChartSummary {
     createdAt: string;
     /** Unique identifier for the chart (typically the tool call ID) */
     chartId: string;
-    /** Chart details, undefined if chart creation failed */
-    chart?: BaseChartSummary;
+    /** Data source the chart was built from */
+    dataSourceTitle: string;
+    /** Compact CSDK chart configuration (chartType, dataOptions, filters, styleOptions) */
+    chartState?: BaseChartSummary;
     /** Whether this chart creation resulted in an error */
     isError?: boolean;
-    /** Dataset from smart query API when chart was built without prior buildQuery; only included when naturalResponseEnabled */
+    /** Dataset rows/sample from NLQ when present on the saved chart widget; surfaced on {@link ChartSummary} when `naturalResponseEnabled` */
     dataset?: Dataset;
 }
-export type ColumnType = StyledColumn | StyledMeasureColumn | Column | MeasureColumn | CalculatedMeasureColumn;
-export interface Column {
+/**
+ * Row in the `charts` array of the build-chart system prompt: either a full
+ * {@link ChartSummary} from the host or a single targeted entry when revising by id.
+ */
+export type ChartContextPromptEntry = ChartSummary | {
+    chartId: string;
+    chartState: BaseChartSummary;
+};
+/**
+ * Normalized styled-column shape used throughout the chart pipeline.
+ * `queryState` elements are normalized to this form before use (see `getColumnsJSON`).
+ * `dataOptions` items are already in this form after `translateChartFromJSON`.
+ * The `column` value is opaque — never inspected by chart manipulation code.
+ */
+export type ColumnJSON = {
+    column: unknown;
+    [key: string]: unknown;
+};
+export interface ColumnSummary {
     id?: number;
     name: string;
     type?: string;
 }
-export declare const chartType: z.ZodEnum<["bar", "column", "area", "line", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "scattermap", "arearange"]>;
-export declare const axesMapping: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodEnum<["bar", "column", "area", "line", "polar"]>;
-    category: z.ZodArray<z.ZodNumber, "many">;
-    value: z.ZodArray<z.ZodNumber, "many">;
-    breakBy: z.ZodArray<z.ZodNumber, "many">;
-}, "strict", z.ZodTypeAny, {
-    value: number[];
-    type: "area" | "column" | "line" | "bar" | "polar";
-    category: number[];
-    breakBy: number[];
-}, {
-    value: number[];
-    type: "area" | "column" | "line" | "bar" | "polar";
-    category: number[];
-    breakBy: number[];
-}>, z.ZodObject<{
-    type: z.ZodEnum<["pie", "funnel", "treemap", "sunburst"]>;
-    category: z.ZodArray<z.ZodNumber, "many">;
-    value: z.ZodArray<z.ZodNumber, "many">;
-}, "strict", z.ZodTypeAny, {
-    value: number[];
-    type: "pie" | "funnel" | "treemap" | "sunburst";
-    category: number[];
-}, {
-    value: number[];
-    type: "pie" | "funnel" | "treemap" | "sunburst";
-    category: number[];
-}>, z.ZodObject<{
+export declare const chartType: z.ZodEnum<{
+    area: "area";
+    table: "table";
+    indicator: "indicator";
+    column: "column";
+    line: "line";
+    pie: "pie";
+    bar: "bar";
+    polar: "polar";
+    funnel: "funnel";
+    treemap: "treemap";
+    sunburst: "sunburst";
+    scatter: "scatter";
+    areamap: "areamap";
+    boxplot: "boxplot";
+    scattermap: "scattermap";
+    arearange: "arearange";
+}>;
+export declare const axesMappingSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodEnum<{
+        area: "area";
+        column: "column";
+        line: "line";
+        bar: "bar";
+        polar: "polar";
+    }>;
+    category: z.ZodArray<z.ZodNumber>;
+    value: z.ZodArray<z.ZodNumber>;
+    breakBy: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodEnum<{
+        pie: "pie";
+        funnel: "funnel";
+        treemap: "treemap";
+        sunburst: "sunburst";
+    }>;
+    category: z.ZodArray<z.ZodNumber>;
+    value: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"scatter">;
-    x: z.ZodArray<z.ZodNumber, "many">;
-    y: z.ZodArray<z.ZodNumber, "many">;
-    breakByPoint: z.ZodArray<z.ZodNumber, "many">;
-    breakByColor: z.ZodArray<z.ZodNumber, "many">;
-    size: z.ZodArray<z.ZodNumber, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "scatter";
-    x: number[];
-    y: number[];
-    breakByPoint: number[];
-    breakByColor: number[];
-    size: number[];
-}, {
-    type: "scatter";
-    x: number[];
-    y: number[];
-    breakByPoint: number[];
-    breakByColor: number[];
-    size: number[];
-}>, z.ZodObject<{
+    x: z.ZodArray<z.ZodNumber>;
+    y: z.ZodArray<z.ZodNumber>;
+    breakByPoint: z.ZodArray<z.ZodNumber>;
+    breakByColor: z.ZodArray<z.ZodNumber>;
+    size: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"table">;
-    columns: z.ZodArray<z.ZodNumber, "many">;
-    pagination: z.ZodBoolean;
-    rowsPerPage: z.ZodNumber;
-}, "strict", z.ZodTypeAny, {
-    type: "table";
-    columns: number[];
-    pagination: boolean;
-    rowsPerPage: number;
-}, {
-    type: "table";
-    columns: number[];
-    pagination: boolean;
-    rowsPerPage: number;
-}>, z.ZodObject<{
+    columns: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"range">;
-    category: z.ZodArray<z.ZodNumber, "many">;
-    value: z.ZodArray<z.ZodNumber, "many">;
-    breakBy: z.ZodArray<z.ZodNumber, "many">;
-}, "strict", z.ZodTypeAny, {
-    value: number[];
-    type: "range";
-    category: number[];
-    breakBy: number[];
-}, {
-    value: number[];
-    type: "range";
-    category: number[];
-    breakBy: number[];
-}>, z.ZodObject<{
+    category: z.ZodArray<z.ZodNumber>;
+    value: z.ZodArray<z.ZodNumber>;
+    breakBy: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"indicator">;
-    value: z.ZodArray<z.ZodNumber, "many">;
-    secondary: z.ZodArray<z.ZodNumber, "many">;
-    min: z.ZodArray<z.ZodNumber, "many">;
-    max: z.ZodArray<z.ZodNumber, "many">;
-}, "strict", z.ZodTypeAny, {
-    value: number[];
-    type: "indicator";
-    secondary: number[];
-    min: number[];
-    max: number[];
-}, {
-    value: number[];
-    type: "indicator";
-    secondary: number[];
-    min: number[];
-    max: number[];
-}>, z.ZodObject<{
+    value: z.ZodArray<z.ZodNumber>;
+    secondary: z.ZodArray<z.ZodNumber>;
+    min: z.ZodArray<z.ZodNumber>;
+    max: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"boxplot">;
-    category: z.ZodArray<z.ZodNumber, "many">;
-    value: z.ZodArray<z.ZodNumber, "many">;
-    boxType: z.ZodEnum<["iqr", "extremums", "standardDeviation"]>;
+    category: z.ZodArray<z.ZodNumber>;
+    value: z.ZodArray<z.ZodNumber>;
+    boxType: z.ZodEnum<{
+        iqr: "iqr";
+        extremums: "extremums";
+        standardDeviation: "standardDeviation";
+    }>;
     outliersEnabled: z.ZodBoolean;
-}, "strict", z.ZodTypeAny, {
-    value: number[];
-    type: "boxplot";
-    category: number[];
-    boxType: "iqr" | "extremums" | "standardDeviation";
-    outliersEnabled: boolean;
-}, {
-    value: number[];
-    type: "boxplot";
-    category: number[];
-    boxType: "iqr" | "extremums" | "standardDeviation";
-    outliersEnabled: boolean;
-}>, z.ZodObject<{
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"areamap">;
-    geo: z.ZodArray<z.ZodNumber, "many">;
-    color: z.ZodArray<z.ZodNumber, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "areamap";
-    geo: number[];
-    color: number[];
-}, {
-    type: "areamap";
-    geo: number[];
-    color: number[];
-}>, z.ZodObject<{
+    geo: z.ZodArray<z.ZodNumber>;
+    color: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"scattermap">;
-    geo: z.ZodArray<z.ZodNumber, "many">;
-    size: z.ZodArray<z.ZodNumber, "many">;
-    colorBy: z.ZodArray<z.ZodNumber, "many">;
-    details: z.ZodArray<z.ZodNumber, "many">;
-    locationLevel: z.ZodEnum<["auto", "country", "state", "city"]>;
-}, "strict", z.ZodTypeAny, {
-    type: "scattermap";
-    details: number[];
-    size: number[];
-    geo: number[];
-    colorBy: number[];
-    locationLevel: "auto" | "country" | "state" | "city";
-}, {
-    type: "scattermap";
-    details: number[];
-    size: number[];
-    geo: number[];
-    colorBy: number[];
-    locationLevel: "auto" | "country" | "state" | "city";
-}>]>;
-export declare const nullableChartType: z.ZodNullable<z.ZodEnum<["bar", "column", "area", "line", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "scattermap", "arearange"]>>;
+    geo: z.ZodArray<z.ZodNumber>;
+    size: z.ZodArray<z.ZodNumber>;
+    colorBy: z.ZodArray<z.ZodNumber>;
+    details: z.ZodArray<z.ZodNumber>;
+    locationLevel: z.ZodEnum<{
+        auto: "auto";
+        country: "country";
+        state: "state";
+        city: "city";
+    }>;
+}, z.core.$strict>]>;
+export declare const nullableChartType: z.ZodNullable<z.ZodEnum<{
+    area: "area";
+    table: "table";
+    indicator: "indicator";
+    column: "column";
+    line: "line";
+    pie: "pie";
+    bar: "bar";
+    polar: "polar";
+    funnel: "funnel";
+    treemap: "treemap";
+    sunburst: "sunburst";
+    scatter: "scatter";
+    areamap: "areamap";
+    boxplot: "boxplot";
+    scattermap: "scattermap";
+    arearange: "arearange";
+}>>;
 export declare const chartIdSchema: z.ZodDefault<z.ZodString>;
 export declare const queryIdSchema: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 export declare const chartRecommendationsSchema: z.ZodObject<{
-    chartType: z.ZodEnum<["bar", "column", "area", "line", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "scattermap", "arearange"]>;
-    axesMapping: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-        type: z.ZodEnum<["bar", "column", "area", "line", "polar"]>;
-        category: z.ZodArray<z.ZodNumber, "many">;
-        value: z.ZodArray<z.ZodNumber, "many">;
-        breakBy: z.ZodArray<z.ZodNumber, "many">;
-    }, "strict", z.ZodTypeAny, {
-        value: number[];
-        type: "area" | "column" | "line" | "bar" | "polar";
-        category: number[];
-        breakBy: number[];
-    }, {
-        value: number[];
-        type: "area" | "column" | "line" | "bar" | "polar";
-        category: number[];
-        breakBy: number[];
-    }>, z.ZodObject<{
-        type: z.ZodEnum<["pie", "funnel", "treemap", "sunburst"]>;
-        category: z.ZodArray<z.ZodNumber, "many">;
-        value: z.ZodArray<z.ZodNumber, "many">;
-    }, "strict", z.ZodTypeAny, {
-        value: number[];
-        type: "pie" | "funnel" | "treemap" | "sunburst";
-        category: number[];
-    }, {
-        value: number[];
-        type: "pie" | "funnel" | "treemap" | "sunburst";
-        category: number[];
-    }>, z.ZodObject<{
+    chartType: z.ZodEnum<{
+        area: "area";
+        table: "table";
+        indicator: "indicator";
+        column: "column";
+        line: "line";
+        pie: "pie";
+        bar: "bar";
+        polar: "polar";
+        funnel: "funnel";
+        treemap: "treemap";
+        sunburst: "sunburst";
+        scatter: "scatter";
+        areamap: "areamap";
+        boxplot: "boxplot";
+        scattermap: "scattermap";
+        arearange: "arearange";
+    }>;
+    axesMapping: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodEnum<{
+            area: "area";
+            column: "column";
+            line: "line";
+            bar: "bar";
+            polar: "polar";
+        }>;
+        category: z.ZodArray<z.ZodNumber>;
+        value: z.ZodArray<z.ZodNumber>;
+        breakBy: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodEnum<{
+            pie: "pie";
+            funnel: "funnel";
+            treemap: "treemap";
+            sunburst: "sunburst";
+        }>;
+        category: z.ZodArray<z.ZodNumber>;
+        value: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"scatter">;
-        x: z.ZodArray<z.ZodNumber, "many">;
-        y: z.ZodArray<z.ZodNumber, "many">;
-        breakByPoint: z.ZodArray<z.ZodNumber, "many">;
-        breakByColor: z.ZodArray<z.ZodNumber, "many">;
-        size: z.ZodArray<z.ZodNumber, "many">;
-    }, "strict", z.ZodTypeAny, {
-        type: "scatter";
-        x: number[];
-        y: number[];
-        breakByPoint: number[];
-        breakByColor: number[];
-        size: number[];
-    }, {
-        type: "scatter";
-        x: number[];
-        y: number[];
-        breakByPoint: number[];
-        breakByColor: number[];
-        size: number[];
-    }>, z.ZodObject<{
+        x: z.ZodArray<z.ZodNumber>;
+        y: z.ZodArray<z.ZodNumber>;
+        breakByPoint: z.ZodArray<z.ZodNumber>;
+        breakByColor: z.ZodArray<z.ZodNumber>;
+        size: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"table">;
-        columns: z.ZodArray<z.ZodNumber, "many">;
-        pagination: z.ZodBoolean;
-        rowsPerPage: z.ZodNumber;
-    }, "strict", z.ZodTypeAny, {
-        type: "table";
-        columns: number[];
-        pagination: boolean;
-        rowsPerPage: number;
-    }, {
-        type: "table";
-        columns: number[];
-        pagination: boolean;
-        rowsPerPage: number;
-    }>, z.ZodObject<{
+        columns: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"range">;
-        category: z.ZodArray<z.ZodNumber, "many">;
-        value: z.ZodArray<z.ZodNumber, "many">;
-        breakBy: z.ZodArray<z.ZodNumber, "many">;
-    }, "strict", z.ZodTypeAny, {
-        value: number[];
-        type: "range";
-        category: number[];
-        breakBy: number[];
-    }, {
-        value: number[];
-        type: "range";
-        category: number[];
-        breakBy: number[];
-    }>, z.ZodObject<{
+        category: z.ZodArray<z.ZodNumber>;
+        value: z.ZodArray<z.ZodNumber>;
+        breakBy: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"indicator">;
-        value: z.ZodArray<z.ZodNumber, "many">;
-        secondary: z.ZodArray<z.ZodNumber, "many">;
-        min: z.ZodArray<z.ZodNumber, "many">;
-        max: z.ZodArray<z.ZodNumber, "many">;
-    }, "strict", z.ZodTypeAny, {
-        value: number[];
-        type: "indicator";
-        secondary: number[];
-        min: number[];
-        max: number[];
-    }, {
-        value: number[];
-        type: "indicator";
-        secondary: number[];
-        min: number[];
-        max: number[];
-    }>, z.ZodObject<{
+        value: z.ZodArray<z.ZodNumber>;
+        secondary: z.ZodArray<z.ZodNumber>;
+        min: z.ZodArray<z.ZodNumber>;
+        max: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"boxplot">;
-        category: z.ZodArray<z.ZodNumber, "many">;
-        value: z.ZodArray<z.ZodNumber, "many">;
-        boxType: z.ZodEnum<["iqr", "extremums", "standardDeviation"]>;
+        category: z.ZodArray<z.ZodNumber>;
+        value: z.ZodArray<z.ZodNumber>;
+        boxType: z.ZodEnum<{
+            iqr: "iqr";
+            extremums: "extremums";
+            standardDeviation: "standardDeviation";
+        }>;
         outliersEnabled: z.ZodBoolean;
-    }, "strict", z.ZodTypeAny, {
-        value: number[];
-        type: "boxplot";
-        category: number[];
-        boxType: "iqr" | "extremums" | "standardDeviation";
-        outliersEnabled: boolean;
-    }, {
-        value: number[];
-        type: "boxplot";
-        category: number[];
-        boxType: "iqr" | "extremums" | "standardDeviation";
-        outliersEnabled: boolean;
-    }>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"areamap">;
-        geo: z.ZodArray<z.ZodNumber, "many">;
-        color: z.ZodArray<z.ZodNumber, "many">;
-    }, "strict", z.ZodTypeAny, {
-        type: "areamap";
-        geo: number[];
-        color: number[];
-    }, {
-        type: "areamap";
-        geo: number[];
-        color: number[];
-    }>, z.ZodObject<{
+        geo: z.ZodArray<z.ZodNumber>;
+        color: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"scattermap">;
-        geo: z.ZodArray<z.ZodNumber, "many">;
-        size: z.ZodArray<z.ZodNumber, "many">;
-        colorBy: z.ZodArray<z.ZodNumber, "many">;
-        details: z.ZodArray<z.ZodNumber, "many">;
-        locationLevel: z.ZodEnum<["auto", "country", "state", "city"]>;
-    }, "strict", z.ZodTypeAny, {
-        type: "scattermap";
-        details: number[];
-        size: number[];
-        geo: number[];
-        colorBy: number[];
-        locationLevel: "auto" | "country" | "state" | "city";
-    }, {
-        type: "scattermap";
-        details: number[];
-        size: number[];
-        geo: number[];
-        colorBy: number[];
-        locationLevel: "auto" | "country" | "state" | "city";
-    }>]>;
-}, "strip", z.ZodTypeAny, {
-    chartType: "area" | "table" | "indicator" | "column" | "line" | "pie" | "bar" | "polar" | "funnel" | "treemap" | "sunburst" | "scatter" | "areamap" | "boxplot" | "scattermap" | "arearange";
-    axesMapping: {
-        value: number[];
-        type: "area" | "column" | "line" | "bar" | "polar";
-        category: number[];
-        breakBy: number[];
-    } | {
-        value: number[];
-        type: "pie" | "funnel" | "treemap" | "sunburst";
-        category: number[];
-    } | {
-        type: "scatter";
-        x: number[];
-        y: number[];
-        breakByPoint: number[];
-        breakByColor: number[];
-        size: number[];
-    } | {
-        type: "table";
-        columns: number[];
-        pagination: boolean;
-        rowsPerPage: number;
-    } | {
-        value: number[];
-        type: "range";
-        category: number[];
-        breakBy: number[];
-    } | {
-        value: number[];
-        type: "indicator";
-        secondary: number[];
-        min: number[];
-        max: number[];
-    } | {
-        value: number[];
-        type: "boxplot";
-        category: number[];
-        boxType: "iqr" | "extremums" | "standardDeviation";
-        outliersEnabled: boolean;
-    } | {
-        type: "areamap";
-        geo: number[];
-        color: number[];
-    } | {
-        type: "scattermap";
-        details: number[];
-        size: number[];
-        geo: number[];
-        colorBy: number[];
-        locationLevel: "auto" | "country" | "state" | "city";
-    };
-}, {
-    chartType: "area" | "table" | "indicator" | "column" | "line" | "pie" | "bar" | "polar" | "funnel" | "treemap" | "sunburst" | "scatter" | "areamap" | "boxplot" | "scattermap" | "arearange";
-    axesMapping: {
-        value: number[];
-        type: "area" | "column" | "line" | "bar" | "polar";
-        category: number[];
-        breakBy: number[];
-    } | {
-        value: number[];
-        type: "pie" | "funnel" | "treemap" | "sunburst";
-        category: number[];
-    } | {
-        type: "scatter";
-        x: number[];
-        y: number[];
-        breakByPoint: number[];
-        breakByColor: number[];
-        size: number[];
-    } | {
-        type: "table";
-        columns: number[];
-        pagination: boolean;
-        rowsPerPage: number;
-    } | {
-        value: number[];
-        type: "range";
-        category: number[];
-        breakBy: number[];
-    } | {
-        value: number[];
-        type: "indicator";
-        secondary: number[];
-        min: number[];
-        max: number[];
-    } | {
-        value: number[];
-        type: "boxplot";
-        category: number[];
-        boxType: "iqr" | "extremums" | "standardDeviation";
-        outliersEnabled: boolean;
-    } | {
-        type: "areamap";
-        geo: number[];
-        color: number[];
-    } | {
-        type: "scattermap";
-        details: number[];
-        size: number[];
-        geo: number[];
-        colorBy: number[];
-        locationLevel: "auto" | "country" | "state" | "city";
-    };
-}>;
+        geo: z.ZodArray<z.ZodNumber>;
+        size: z.ZodArray<z.ZodNumber>;
+        colorBy: z.ZodArray<z.ZodNumber>;
+        details: z.ZodArray<z.ZodNumber>;
+        locationLevel: z.ZodEnum<{
+            auto: "auto";
+            country: "country";
+            state: "state";
+            city: "city";
+        }>;
+    }, z.core.$strict>]>;
+}, z.core.$strip>;
+/**
+ * Canonical tool description for buildChart — reusable by any host (sdk-assistant, MCP server, custom integrations).
+ * Hosts may append host-specific notes but should not duplicate or contradict this text.
+ */
+export declare const buildChartToolDescription = "Creates or revises a chart from a natural language prompt.\n\nRevising a chart includes updating the chart's data structure (data options), sorting, trend and forecast, style options, and filters. \n\nThree ways to scope the run:\n\n1. **New chart from scratch:** omit both `priorChartId` and `queryId` and describe the desired chart in `userPrompt`.\n2. **Revise an existing chart:** pass `priorChartId` (the chartId from a prior buildChart result, or the widget id when inside a dashboard). The chart's existing data context and style are preserved across revisions.\n3. **Verbatim prior query:** pass `queryId` (an id from a prior data query result) to chart to reuse that query result if needed to not waste the prior query work.\n\nWhen revising an existing chart, do not run other tools (e.g. query tool) and do not pass `queryId`.\n\nPass the user prompt exactly as received \u2014 do not transform or modify it.";
 export declare const buildChartSchema: z.ZodObject<{
     dataSourceTitle: z.ZodString;
     userPrompt: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    dataSourceTitle: string;
-    userPrompt: string;
-}, {
-    dataSourceTitle: string;
-    userPrompt: string;
-}>;
-export declare const buildChartSchemaNaturalConversation: z.ZodObject<{
-    dataSourceTitle: z.ZodString;
-    userPrompt: z.ZodString;
+    priorChartId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     queryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    dataSourceTitle: string;
-    userPrompt: string;
-    queryId?: string | null | undefined;
-}, {
-    dataSourceTitle: string;
-    userPrompt: string;
-    queryId?: string | null | undefined;
-}>;
+}, z.core.$strip>;
 export declare const createChartSchema: z.ZodObject<{
     queryPrompt: z.ZodString;
     chartPrompt: z.ZodString;
-    chartType: z.ZodNullable<z.ZodEnum<["bar", "column", "area", "line", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "scattermap", "arearange"]>>;
+    chartType: z.ZodNullable<z.ZodEnum<{
+        area: "area";
+        table: "table";
+        indicator: "indicator";
+        column: "column";
+        line: "line";
+        pie: "pie";
+        bar: "bar";
+        polar: "polar";
+        funnel: "funnel";
+        treemap: "treemap";
+        sunburst: "sunburst";
+        scatter: "scatter";
+        areamap: "areamap";
+        boxplot: "boxplot";
+        scattermap: "scattermap";
+        arearange: "arearange";
+    }>>;
     chartTitle: z.ZodString;
     queryId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    queryPrompt: string;
-    chartType: "area" | "table" | "indicator" | "column" | "line" | "pie" | "bar" | "polar" | "funnel" | "treemap" | "sunburst" | "scatter" | "areamap" | "boxplot" | "scattermap" | "arearange" | null;
-    queryId: string | null;
-    chartPrompt: string;
-    chartTitle: string;
-}, {
-    queryPrompt: string;
-    chartType: "area" | "table" | "indicator" | "column" | "line" | "pie" | "bar" | "polar" | "funnel" | "treemap" | "sunburst" | "scatter" | "areamap" | "boxplot" | "scattermap" | "arearange" | null;
-    chartPrompt: string;
-    chartTitle: string;
-    queryId?: string | null | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateChartSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateChartTitleSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-} & {
     chartTitle: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartTitle: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartTitle: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateChartTypeSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-} & {
-    chartType: z.ZodEnum<["bar", "column", "area", "line", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "scattermap", "arearange"]>;
-}, "strip", z.ZodTypeAny, {
-    chartType: "area" | "table" | "indicator" | "column" | "line" | "pie" | "bar" | "polar" | "funnel" | "treemap" | "sunburst" | "scatter" | "areamap" | "boxplot" | "scattermap" | "arearange";
-    userPrompt: string;
-    chartId: string;
-}, {
-    chartType: "area" | "table" | "indicator" | "column" | "line" | "pie" | "bar" | "polar" | "funnel" | "treemap" | "sunburst" | "scatter" | "areamap" | "boxplot" | "scattermap" | "arearange";
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+    chartType: z.ZodEnum<{
+        area: "area";
+        table: "table";
+        indicator: "indicator";
+        column: "column";
+        line: "line";
+        pie: "pie";
+        bar: "bar";
+        polar: "polar";
+        funnel: "funnel";
+        treemap: "treemap";
+        sunburst: "sunburst";
+        scatter: "scatter";
+        areamap: "areamap";
+        boxplot: "boxplot";
+        scattermap: "scattermap";
+        arearange: "arearange";
+    }>;
+}, z.core.$strip>;
 export declare const updateChartTypeOfMeasuresSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateChartSortingSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateTrendAndForecastSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateOtherChartDataOptionsSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const updateChartStyleOptionsSchema: z.ZodObject<{
     userPrompt: z.ZodString;
-} & {
     chartId: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    userPrompt: string;
-    chartId: string;
-}, {
-    userPrompt: string;
-    chartId?: string | undefined;
-}>;
+}, z.core.$strip>;
+export declare const updateChartQuerySchema: z.ZodObject<{
+    revisionPrompt: z.ZodString;
+    chartId: z.ZodString;
+}, z.core.$strip>;
 /**
  * Build chart context interface
  */
@@ -608,14 +355,13 @@ export interface BuildChartContext {
      * Tool call ID
      */
     toolCallId: string;
+    abortSignal?: AbortSignal;
     /**
      * Data source title (required)
      */
     dataSourceTitle: string;
     /** Chart summaries to be used as context */
     chartSummaries?: ChartSummary[];
-    /** query results to be used as context */
-    querySummaries?: QuerySummary[];
     /**
      * Retrieve a chart by its ID
      * @param chartId - The ID of the chart to retrieve
@@ -634,17 +380,21 @@ export interface BuildChartContext {
      * @returns The query result, or null if not found
      */
     retrieveQuery?: (queryId: string) => QueryResult | null;
-    /** Whether NLQ V3 is enabled */
-    isNlqV3Enabled?: boolean;
+    /**
+     * When false, incremental NLQ uses Layer-2 text augmentation instead of REST `chartState`.
+     * Typically threaded from host config when available.
+     */
+    isNlqDeltaEnabled?: boolean;
     httpClient?: HttpClient;
-    openAIClient?: OpenAI;
+    llmClient?: LanguageModel;
+    /**
+     * When true, include `dataset` on the returned {@link ChartSummary} when the saved chart
+     * widget carries `dataset`.
+     */
+    naturalResponseEnabled?: boolean;
+    /** Common filters (e.g., from dashboard filters) to be applied to the query of the chart. */
+    commonFilters?: unknown;
     /** ID of a prior query result when this chart uses that query; otherwise null/undefined */
     queryId?: string | null;
-    /** When true, include dataset in ChartSummary when build chart fetches data internally (no queryId) */
-    naturalResponseEnabled?: boolean;
-    /** Callback to capture query result when build chart fetches data internally via buildQueryEngine */
-    onInternalQueryResult?: (result: QueryResult) => void;
-    /** Translated dashboard filters for NLQ smart-query `commonFilters` when build chart calls buildQueryEngine (no queryId) */
-    filters?: unknown;
 }
 //# sourceMappingURL=types.d.ts.map