@sisense/sdk-ai-core 0.17.0 → 0.60.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/dist/__vite-browser-external-l0sNRNKZ.js +1 -0
  2. package/dist/constants.d.ts +35 -0
  3. package/dist/engines/atomic-handle-args.d.ts +45 -0
  4. package/dist/engines/atomic-tool-requirements.d.ts +38 -0
  5. package/dist/engines/author-pulse/actions/create.d.ts +9 -0
  6. package/dist/engines/author-pulse/actions/define.d.ts +9 -0
  7. package/dist/engines/author-pulse/actions/load-existing.d.ts +9 -0
  8. package/dist/engines/author-pulse/actions/redefine.d.ts +9 -0
  9. package/dist/engines/author-pulse/actions/set-receive-notifications.d.ts +8 -0
  10. package/dist/engines/author-pulse/actions/update-spec.d.ts +11 -0
  11. package/dist/engines/author-pulse/actions/update-workflow.d.ts +9 -0
  12. package/dist/engines/author-pulse/atomic-adapter.d.ts +10 -0
  13. package/dist/engines/author-pulse/atomic-tools.d.ts +362 -0
  14. package/dist/engines/author-pulse/author-pulse-engine.d.ts +21 -0
  15. package/dist/engines/author-pulse/index.d.ts +9 -0
  16. package/dist/engines/author-pulse/shared/adjustment-error.d.ts +15 -0
  17. package/dist/engines/author-pulse/shared/assemble-create-workflow-payload.d.ts +36 -0
  18. package/dist/engines/author-pulse/shared/assert-agentic-workflow.d.ts +12 -0
  19. package/dist/engines/author-pulse/shared/compile-query-from-prompt.d.ts +95 -0
  20. package/dist/engines/author-pulse/shared/decision-spec-validation.d.ts +84 -0
  21. package/dist/engines/author-pulse/shared/notification-urls.d.ts +52 -0
  22. package/dist/engines/author-pulse/shared/pulse-knowledge.d.ts +36 -0
  23. package/dist/engines/author-pulse/shared/pulse-signature.d.ts +39 -0
  24. package/dist/engines/author-pulse/shared/resolve-frequency.d.ts +18 -0
  25. package/dist/engines/author-pulse/shared/staging.d.ts +65 -0
  26. package/dist/engines/author-pulse/shared/workflow-ownership.d.ts +14 -0
  27. package/dist/engines/author-pulse/types.d.ts +1385 -0
  28. package/dist/engines/build-chart/atomic-adapter.d.ts +20 -0
  29. package/dist/engines/build-chart/atomic-tools.d.ts +214 -0
  30. package/dist/engines/build-chart/build-chart-engine.d.ts +1 -1
  31. package/dist/engines/build-chart/chart-tool-name.d.ts +3 -0
  32. package/dist/engines/build-chart/create-chart/assemble-chart-widget.d.ts +1 -1
  33. package/dist/engines/build-chart/create-chart/chart-json-axes-mapping.d.ts +1 -1
  34. package/dist/engines/build-chart/create-chart/create-chart.d.ts +1 -1
  35. package/dist/engines/build-chart/create-chart/derive-chart-title.d.ts +7 -0
  36. package/dist/engines/build-chart/create-chart/generate-chart-recommendations.d.ts +2 -2
  37. package/dist/engines/build-chart/create-chart/resolve-chart-query.d.ts +4 -0
  38. package/dist/engines/build-chart/shared/normalize-cartesian-axes-mapping.d.ts +1 -1
  39. package/dist/engines/build-chart/shared/sync-chart-state-measure-flags.d.ts +3 -0
  40. package/dist/engines/build-chart/types.d.ts +38 -19
  41. package/dist/engines/build-chart/update-chart/apply-prior-chart-style.d.ts +8 -5
  42. package/dist/engines/build-chart/update-chart/chart-options-schemas.d.ts +18 -18
  43. package/dist/engines/build-chart/update-chart/schemas.d.ts +2 -2
  44. package/dist/engines/build-chart/update-chart/update-chart-data-options.d.ts +7 -2
  45. package/dist/engines/build-chart/update-chart/update-chart-query.d.ts +1 -1
  46. package/dist/engines/build-chart/update-chart/update-chart-style-options.d.ts +7 -2
  47. package/dist/engines/build-chart/update-chart/update-chart-title.d.ts +1 -1
  48. package/dist/engines/build-chart/update-chart/update-chart-type.d.ts +7 -2
  49. package/dist/engines/build-csv-model/build-csv-model-engine.d.ts +1 -1
  50. package/dist/engines/build-csv-model/types.d.ts +1 -1
  51. package/dist/engines/build-dashboard/add-dashboard-narration.d.ts +50 -0
  52. package/dist/engines/build-dashboard/add-dashboard-widgets.d.ts +1 -1
  53. package/dist/engines/build-dashboard/atomic-adapter.d.ts +21 -0
  54. package/dist/engines/build-dashboard/atomic-tools.d.ts +231 -0
  55. package/dist/engines/build-dashboard/build-dashboard-engine.d.ts +1 -1
  56. package/dist/engines/build-dashboard/build-dashboard-service.d.ts +2 -1
  57. package/dist/engines/build-dashboard/create-dashboard.d.ts +3 -4
  58. package/dist/engines/build-dashboard/dashboard-filters/manipulate-dashboard-filters.d.ts +2 -1
  59. package/dist/engines/build-dashboard/dashboard-filters/translate-filters.d.ts +17 -1
  60. package/dist/engines/build-dashboard/index.d.ts +2 -0
  61. package/dist/engines/build-dashboard/layout/place-widget.d.ts +53 -0
  62. package/dist/engines/build-dashboard/load-existing-fusion-dashboard.d.ts +1 -1
  63. package/dist/engines/build-dashboard/remove-dashboard-widgets.d.ts +4 -0
  64. package/dist/engines/build-dashboard/resolve-chart-widgets.d.ts +16 -0
  65. package/dist/engines/build-dashboard/types.d.ts +180 -18
  66. package/dist/engines/build-data-model/build-data-model-engine.d.ts +1 -1
  67. package/dist/engines/build-data-model/types.d.ts +1 -1
  68. package/dist/engines/build-query/build-query-engine.d.ts +33 -5
  69. package/dist/engines/build-query/index.d.ts +1 -1
  70. package/dist/engines/build-query/types.d.ts +216 -3
  71. package/dist/engines/build-status/build-status-engine.d.ts +8 -0
  72. package/dist/engines/build-status/builds-client.d.ts +44 -0
  73. package/dist/engines/build-status/index.d.ts +2 -0
  74. package/dist/engines/build-status/types.d.ts +177 -0
  75. package/dist/engines/datamodel-graph/data-model-map-text.d.ts +28 -0
  76. package/dist/engines/datamodel-graph/datamodel-graph-engine.d.ts +31 -0
  77. package/dist/engines/datamodel-graph/index.d.ts +4 -0
  78. package/dist/engines/datamodel-graph/summaries.d.ts +97 -0
  79. package/dist/engines/datamodel-graph/test-fixtures.d.ts +42 -0
  80. package/dist/engines/datamodel-graph/types.d.ts +190 -0
  81. package/dist/engines/evaluate-pulse/evaluate-pulse-engine.d.ts +10 -0
  82. package/dist/engines/evaluate-pulse/index.d.ts +2 -0
  83. package/dist/engines/evaluate-pulse/types.d.ts +85 -0
  84. package/dist/engines/get-dashboard-narration/get-dashboard-narration-engine.d.ts +23 -0
  85. package/dist/engines/get-dashboard-narration/index.d.ts +2 -0
  86. package/dist/engines/get-dashboard-narration/types.d.ts +64 -0
  87. package/dist/engines/get-dashboards/get-dashboards-engine.d.ts +1 -1
  88. package/dist/engines/get-dashboards/types.d.ts +16 -4
  89. package/dist/engines/get-data-preview/get-data-preview-engine.d.ts +18 -0
  90. package/dist/engines/get-data-preview/index.d.ts +2 -0
  91. package/dist/engines/get-data-preview/types.d.ts +35 -0
  92. package/dist/engines/get-data-source-fields/get-data-source-fields-engine.d.ts +12 -6
  93. package/dist/engines/get-data-source-fields/index.d.ts +1 -0
  94. package/dist/engines/get-data-source-fields/model-relations.d.ts +38 -0
  95. package/dist/engines/get-data-source-fields/types.d.ts +49 -3
  96. package/dist/engines/get-data-sources/get-data-sources-engine.d.ts +1 -1
  97. package/dist/engines/get-data-sources/types.d.ts +2 -2
  98. package/dist/engines/index.d.ts +17 -0
  99. package/dist/engines/inspect-pulse/atomic-adapter.d.ts +8 -0
  100. package/dist/engines/inspect-pulse/atomic-tools.d.ts +60 -0
  101. package/dist/engines/inspect-pulse/index.d.ts +4 -0
  102. package/dist/engines/inspect-pulse/inspect-pulse-engine.d.ts +7 -0
  103. package/dist/engines/inspect-pulse/types.d.ts +209 -0
  104. package/dist/engines/manage-perspectives/manage-perspectives-engine.d.ts +5 -1
  105. package/dist/engines/manage-perspectives/types.d.ts +13 -8
  106. package/dist/engines/pulse-tool-words.d.ts +62 -0
  107. package/dist/engines/recommend-queries/recommend-queries-engine.d.ts +1 -1
  108. package/dist/engines/recommend-queries/types.d.ts +1 -1
  109. package/dist/engines/shared/existing-answer-cascade.d.ts +52 -0
  110. package/dist/engines/shared/get-filters-json-for-llm-summary.d.ts +2 -2
  111. package/dist/engines/shared/nlq-query-helpers.d.ts +2 -2
  112. package/dist/engines/shared/project-dashboard-json.d.ts +151 -0
  113. package/dist/engines/shared/project-widget-json.d.ts +67 -0
  114. package/dist/engines/shared/projection-helpers.d.ts +19 -0
  115. package/dist/engines/shared/redact-data-models-closed-to-ai.d.ts +55 -0
  116. package/dist/engines/shared/redact-hidden-columns-from-ai.d.ts +55 -0
  117. package/dist/index.d.ts +20 -0
  118. package/dist/index.js +57916 -30543
  119. package/dist/services/ai-access/ai-access-service.d.ts +68 -0
  120. package/dist/services/dashboards/dashboards-service.d.ts +9 -3
  121. package/dist/services/dashboards/fusion-dashboards-service.d.ts +34 -4
  122. package/dist/services/data-sources/data-sources-service.d.ts +131 -2
  123. package/dist/services/data-sources/find-data-source-by-title.d.ts +8 -0
  124. package/dist/services/datamodel-graph/datamodel-graph-service.d.ts +457 -0
  125. package/dist/services/existing-answer/existing-answer-query-service.d.ts +31 -0
  126. package/dist/services/formulas/formulas-service.d.ts +19 -0
  127. package/dist/services/hide-from-ai/hide-from-ai.d.ts +31 -0
  128. package/dist/services/knowledge-graph/knowledge-graph-service.d.ts +96 -0
  129. package/dist/services/llm/llm-consumption-service.d.ts +7 -2
  130. package/dist/services/llm/llm-settings-service.d.ts +49 -5
  131. package/dist/services/nlq/nlq-preview-dataset.d.ts +34 -0
  132. package/dist/services/nlq/nlq-service.d.ts +138 -3
  133. package/dist/services/pulse/evaluate-pulse-client.d.ts +78 -0
  134. package/dist/services/pulse/pulse-alerts-service.d.ts +264 -0
  135. package/dist/services/pulse/pulse-events-service.d.ts +217 -0
  136. package/dist/services/semantic-search/semantic-search-service.d.ts +43 -0
  137. package/dist/services/tool-store/tool-store-service.d.ts +32 -0
  138. package/dist/services/users-groups-service.d.ts +37 -0
  139. package/dist/skills/index.d.ts +127 -0
  140. package/dist/tool-availability/controlled-tools.d.ts +56 -0
  141. package/dist/tool-availability/index.d.ts +4 -0
  142. package/dist/tool-availability/offer-tools.d.ts +44 -0
  143. package/dist/tool-availability/resolve-tool-availability.d.ts +68 -0
  144. package/dist/tool-availability/withdrawn-text.d.ts +33 -0
  145. package/dist/tool-catalog/catalog.d.ts +387 -0
  146. package/dist/tool-catalog/index.d.ts +3 -0
  147. package/dist/tool-catalog/manifest.d.ts +5 -0
  148. package/dist/tool-catalog/prototype-lookup.d.ts +10 -0
  149. package/dist/tool-catalog/types.d.ts +67 -0
  150. package/dist/tools.manifest.json +826 -0
  151. package/dist/utils/chat-stream-errors.d.ts +42 -0
  152. package/dist/utils/create-custom-fetch.d.ts +19 -1
  153. package/dist/utils/create-stream-completion.d.ts +84 -6
  154. package/dist/utils/create-structured-completion.d.ts +29 -2
  155. package/dist/utils/create-tools-completion.d.ts +9 -0
  156. package/dist/utils/deferred-tools.d.ts +45 -0
  157. package/dist/utils/dev-debug.d.ts +5 -0
  158. package/dist/utils/generate-suggestions.d.ts +32 -0
  159. package/dist/utils/http-client.d.ts +3 -1
  160. package/dist/utils/llm-call-observer.d.ts +83 -0
  161. package/dist/utils/llm-client.d.ts +11 -1
  162. package/dist/utils/quoted-text.d.ts +6 -0
  163. package/dist/utils/server-error-body.d.ts +23 -0
  164. package/dist/utils/text-tokens.d.ts +35 -0
  165. package/dist/utils/user-action-tracking.d.ts +48 -5
  166. package/dist/utils/zod-utils.d.ts +9 -1
  167. package/package.json +28 -19
@@ -1,6 +1,7 @@
1
- import { BaseDashboardSummary, ExtendedDashboardProps } from './types';
1
+ import { BaseDashboardSummary, DashboardSummary, ExtendedDashboardProps } from './types';
2
2
  /**
3
3
  * Returns the CSDK dashboard configuration ({@link BaseDashboardSummary}) for LLM consumption.
4
4
  * Returns `undefined` when `dashboardState` has not yet been computed.
5
5
  */
6
6
  export declare const getBaseDashboardSummary: (dashboardProps: ExtendedDashboardProps) => BaseDashboardSummary | undefined;
7
+ export declare const getDashboardLayoutGrid: (dashboardProps: ExtendedDashboardProps) => DashboardSummary["layoutGrid"];
@@ -1,4 +1,3 @@
1
- import { CreateDashboardParams, BuildDashboardContext } from './types';
2
- export declare const createDashboard: ({ dashboardTitle, widgetIdsToAdd }: CreateDashboardParams, context: BuildDashboardContext) => Promise<{
3
- message: string;
4
- }>;
1
+ import { ExtendedDashboardProps, BuildDashboardContext } from './types';
2
+ export declare function createdDashboardMessage(widgetCount: number): string;
3
+ export declare function saveCreatedDashboard(saveDashboard: BuildDashboardContext['saveDashboard'], dashboardProps: ExtendedDashboardProps): void;
@@ -1,6 +1,7 @@
1
1
  import { DashboardProps } from '@sisense/sdk-ui';
2
2
  import { LanguageModel } from 'ai';
3
- export declare const manipulateDashboardFilters: (userPrompt: string, dataSourceTitle: string, dashboardProps: DashboardProps, llmClient?: LanguageModel) => Promise<{
3
+ import { HttpClient } from '@sisense/sdk-rest-client';
4
+ export declare const manipulateDashboardFilters: (userPrompt: string, dataSourceTitle: string, dashboardProps: DashboardProps, llmClient?: LanguageModel, toolName?: string, httpClient?: HttpClient) => Promise<{
4
5
  dashboardProps: DashboardProps;
5
6
  explanation: string;
6
7
  }>;
@@ -1,5 +1,21 @@
1
1
  import { Filter, FilterRelations, JaqlDataSourceForDto } from '@sisense/sdk-data';
2
2
  import { NormalizedDataSourceField } from '../../../services/data-sources/data-sources-service';
3
+ /**
4
+ * Factory paths whose first argument is not an Attribute (nested filters,
5
+ * measures, or a formula string). Every other filterFactory / measureFactory
6
+ * function treats args[0] as a column reference.
7
+ */
8
+ export declare const FACTORIES_WITHOUT_LEADING_ATTRIBUTE: Set<string>;
9
+ /**
10
+ * Normalize an LLM column ref to `Table.Column` (date levels stay on the column,
11
+ * e.g. `Commerce.Date.Years`).
12
+ */
13
+ export declare function normalizeAttributeRef(ref: string): string;
14
+ /**
15
+ * Look up a data field for an LLM column ref. Accepts `DM.Table.Column`,
16
+ * `Table.Column`, and `[Table.Column]`. Exact match after normalize only.
17
+ */
18
+ export declare function resolveDataField(ref: string, dataFields: NormalizedDataSourceField[]): NormalizedDataSourceField | undefined;
3
19
  export declare function getFactoryFunctionsMap(factoryName: string, factoryObject: Record<string, any>): Record<string, (...args: any[]) => any>;
4
20
  export declare const measureFactoryFunctionsMap: Record<string, (...args: any[]) => any>;
5
21
  export declare const filterFactoryFunctionsMap: Record<string, (...args: any[]) => any>;
@@ -40,4 +56,4 @@ export declare const filterFactoryFunctionsMap: Record<string, (...args: any[])
40
56
  * @param filtersJson - A JSON string representing the filters
41
57
  * @returns A Filter[] or FilterRelations object
42
58
  */
43
- export declare const translateFiltersFromJsonFunctionCall: (filtersJson: string, dataSource: JaqlDataSourceForDto, dataFields: NormalizedDataSourceField[]) => Filter[] | FilterRelations;
59
+ export declare const translateFiltersFromJSONFunctionCall: (filtersJson: string, dataSource: JaqlDataSourceForDto, dataFields: NormalizedDataSourceField[]) => Filter[] | FilterRelations;
@@ -1,3 +1,5 @@
1
1
  export { buildDashboardEngine } from './build-dashboard-engine';
2
2
  export * from './types';
3
3
  export * from './build-dashboard-service';
4
+ export { resolveChartWidgets, formatUnresolvedChartIdsWarning, type ChartWidgetLookupResult, type ChartWidgetResolution, } from './resolve-chart-widgets';
5
+ export { addNarrationToDashboard, removeNarrationFromDashboard, createNarrativeWidgetProps, DEFAULT_NARRATION_WIDGET_TITLE, DEFAULT_NARRATION_ROW_HEIGHT, type AddNarrationToDashboardResult, } from './add-dashboard-narration';
@@ -0,0 +1,53 @@
1
+ import { WidgetsPanelColumnLayout } from '@sisense/sdk-ui';
2
+ export declare const DEFAULT_ROW_HEIGHT = 384;
3
+ export type RowHeightTier = 'small' | 'medium' | 'large';
4
+ export declare const ROW_HEIGHT: Record<RowHeightTier, number>;
5
+ export type WidgetPlacement = {
6
+ /** 1-based row number */
7
+ row: number;
8
+ /** 1-based cell position within row; omit to append at end of row */
9
+ cell?: number;
10
+ relativeTo?: {
11
+ widgetId: string;
12
+ position: 'before' | 'after';
13
+ };
14
+ /** Height tier when placement creates a new row */
15
+ height?: RowHeightTier;
16
+ };
17
+ export type LayoutGridSummary = {
18
+ rows: Array<{
19
+ row: number;
20
+ height: number;
21
+ cells: Array<{
22
+ cell: number;
23
+ widgetId: string;
24
+ widthPercentage: number;
25
+ }>;
26
+ }>;
27
+ };
28
+ export type WidgetCellLocation = {
29
+ columnIndex: number;
30
+ rowIndex: number;
31
+ cellIndex: number;
32
+ };
33
+ type LayoutCell = WidgetsPanelColumnLayout['columns'][number]['rows'][number]['cells'][number];
34
+ export declare function normalizeCellHeight(height: number | string | undefined): number;
35
+ export declare function findWidgetCell(layout: WidgetsPanelColumnLayout, widgetId: string): WidgetCellLocation | undefined;
36
+ export declare function rebalanceRowWidths(cells: LayoutCell[]): LayoutCell[];
37
+ export declare function computeCellGeometry(layout: WidgetsPanelColumnLayout, columnIndex: number, targetRowIndex: number, isNewRow: boolean, cellCountAfterInsert: number, explicitHeight?: number): {
38
+ height: number;
39
+ widthPercentage: number;
40
+ };
41
+ export type ResolvedPlacement = {
42
+ columnIndex: number;
43
+ rowIndex: number;
44
+ cellIndex: number;
45
+ isNewRow: boolean;
46
+ };
47
+ export declare function resolvePlacement(layout: WidgetsPanelColumnLayout, placement: WidgetPlacement): ResolvedPlacement;
48
+ export declare function placeWidgetInLayout(layout: WidgetsPanelColumnLayout, widgetId: string, placement: WidgetPlacement): WidgetsPanelColumnLayout;
49
+ export declare function appendWidgetToLayout(layout: WidgetsPanelColumnLayout, widgetId: string): WidgetsPanelColumnLayout;
50
+ export declare function buildLayoutGridSummary(layout: WidgetsPanelColumnLayout | undefined): LayoutGridSummary | undefined;
51
+ export declare function replaceWidgetIdInLayout(layout: WidgetsPanelColumnLayout, oldWidgetId: string, newWidgetId: string): WidgetsPanelColumnLayout;
52
+ export declare function updateRowHeight(layout: WidgetsPanelColumnLayout, rowIndex: number, height: number): WidgetsPanelColumnLayout;
53
+ export {};
@@ -1,4 +1,4 @@
1
1
  import { LoadExistingFusionDashboardParams, BuildDashboardContext } from './types';
2
- export declare const loadExistingFusionDashboard: ({ dashboardTitle }: LoadExistingFusionDashboardParams, context: BuildDashboardContext) => Promise<{
2
+ export declare const loadExistingFusionDashboard: ({ dashboardTitle, dashboardId }: LoadExistingFusionDashboardParams, context: BuildDashboardContext) => Promise<{
3
3
  message: string;
4
4
  }>;
@@ -0,0 +1,4 @@
1
+ import { RemoveDashboardWidgetsParams, BuildDashboardContext } from './types';
2
+ export declare const removeDashboardWidgets: ({ dashboardId, widgetIds }: RemoveDashboardWidgetsParams, context: BuildDashboardContext) => Promise<{
3
+ message: string;
4
+ }>;
@@ -0,0 +1,16 @@
1
+ import { WidgetProps } from '@sisense/sdk-ui';
2
+ export type ChartWidgetLookupResult = WidgetProps | WidgetProps[] | null | undefined;
3
+ export type ChartWidgetResolution = {
4
+ /** Flat list of widgets in chartIds order (chart-list ids may expand to multiple). */
5
+ widgets: WidgetProps[];
6
+ /** chartIds that could not be resolved from the session context. */
7
+ unresolvedChartIds: string[];
8
+ /** Resolved widgets grouped by requested chartId. */
9
+ byChartId: Map<string, WidgetProps[]>;
10
+ };
11
+ /**
12
+ * Resolves chart tool-call IDs to widget props one at a time.
13
+ * Missing or invalid IDs are skipped rather than failing the whole batch.
14
+ */
15
+ export declare function resolveChartWidgets(chartIds: string[], lookup: (chartId: string) => ChartWidgetLookupResult): ChartWidgetResolution;
16
+ export declare function formatUnresolvedChartIdsWarning(unresolvedChartIds: string[], includedWidgetCount: number): string;
@@ -1,9 +1,33 @@
1
1
  import { DashboardProps, WidgetProps } from '@sisense/sdk-ui';
2
2
  import { DashboardJSON } from '@sisense/sdk-ui/analytics-composer';
3
3
  import { HttpClient } from '@sisense/sdk-rest-client';
4
- import { z } from 'zod/v4';
4
+ import { z } from 'zod';
5
5
  import { ArtifactReference, ChartSummary } from '../build-chart/types';
6
+ import { LayoutGridSummary } from './layout/place-widget';
7
+ import { ChartWidgetResolution } from './resolve-chart-widgets';
6
8
  import { LanguageModel } from 'ai';
9
+ export type { LayoutGridSummary, RowHeightTier, WidgetPlacement, } from './layout/place-widget';
10
+ export declare const rowHeightTierSchema: z.ZodEnum<{
11
+ small: "small";
12
+ large: "large";
13
+ medium: "medium";
14
+ }>;
15
+ export declare const widgetPlacementSchema: z.ZodObject<{
16
+ row: z.ZodNumber;
17
+ cell: z.ZodOptional<z.ZodNumber>;
18
+ relativeTo: z.ZodOptional<z.ZodObject<{
19
+ widgetId: z.ZodString;
20
+ position: z.ZodEnum<{
21
+ before: "before";
22
+ after: "after";
23
+ }>;
24
+ }, z.core.$strip>>;
25
+ height: z.ZodOptional<z.ZodEnum<{
26
+ small: "small";
27
+ large: "large";
28
+ medium: "medium";
29
+ }>>;
30
+ }, z.core.$strip>;
7
31
  export type DashboardState = DashboardJSON;
8
32
  export type ExtendedDashboardProps = DashboardProps & ArtifactReference & {
9
33
  /**
@@ -39,6 +63,10 @@ export interface DashboardSummary {
39
63
  dataSourceTitle: string;
40
64
  /** Compact CSDK dashboard configuration, undefined if dashboard creation failed */
41
65
  dashboardState?: BaseDashboardSummary;
66
+ /** 1-based row/cell grid for placement and delete operations */
67
+ layoutGrid?: LayoutGridSummary;
68
+ /** chartIds from the action that could not be resolved in the session context */
69
+ unresolvedChartIds?: string[];
42
70
  }
43
71
  /**
44
72
  * Row in the `dashboards` array of the build-dashboard system prompt: either a
@@ -47,74 +75,172 @@ export interface DashboardSummary {
47
75
  export type DashboardContextPromptEntry = DashboardSummary | {
48
76
  dashboardId: string;
49
77
  dashboardState: BaseDashboardSummary;
78
+ layoutGrid?: LayoutGridSummary;
50
79
  };
51
80
  /**
52
81
  * Canonical tool description for buildDashboard — reusable by any host (sdk-assistant, MCP server, custom integrations).
53
82
  * Hosts may append host-specific notes but should not duplicate or contradict this text.
54
83
  */
55
- export declare const buildDashboardToolDescription = "Creates or updates a dashboard via a required structured `action` param. Build charts with buildChart first, then pass chartIds where needed. Load the buildDashboard skill via loadSkill before calling this tool.";
84
+ export declare const buildDashboardToolDescription = "Creates or updates a dashboard via a required structured `action` object (not a JSON string). Build charts with buildChart first, then pass chartIds where needed. Load the buildDashboard skill via loadSkill before calling this tool.\n\nSupports structured actions via the `action` object (no inner LLM loop):\n- `load-existing` \u2014 open a Fusion dashboard by title.\n- `create` \u2014 new dashboard with explicit rows and height tiers (small/medium/large); `rows: []` for an empty dashboard.\n- `add-charts` \u2014 add charts to an existing dashboard; optional `placements` per chart (row, cell, before/after a widget, or height tier for a new row). Omit placements to append at the bottom.\n- `remove-charts` \u2014 remove widgets by dashboard widgetId from layoutGrid (not chartId).\n- `replace-charts` \u2014 swap a layout slot to a different chartId (not for in-place edits via buildChart priorChartId).\n- `update-title` \u2014 rename an existing dashboard.\n- `update-row-height` \u2014 change the height tier of an existing row (row number from layoutGrid).\n- `add-filters` \u2014 add filters from natural language (`filterDescription`; uses LLM).\n- `add-narration` \u2014 add a Dashboard Narrative widget (an AI-written summary of the dashboard's data, generated when the user opens it) in a new top row. Use it whenever the user asks for a narrative or narration on the dashboard \u2014 for a new dashboard, right after `create` succeeds, with its dashboardId. A dashboard holds at most one; remove it with `remove-charts` and its widgetId from layoutGrid. To show a narrative in the conversation instead, use getDashboardNarration.";
56
85
  /** JSON-Schema-safe union; run {@link parseActionWithGuards} at execution time. */
57
86
  export declare const buildDashboardActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
58
87
  type: z.ZodLiteral<"load-existing">;
59
- dashboardTitle: z.ZodString;
88
+ dashboardTitle: z.ZodOptional<z.ZodString>;
89
+ dashboardId: z.ZodOptional<z.ZodString>;
60
90
  }, z.core.$strip>, z.ZodObject<{
61
91
  type: z.ZodLiteral<"create">;
62
92
  title: z.ZodString;
63
- chartIds: z.ZodArray<z.ZodString>;
93
+ rows: z.ZodArray<z.ZodObject<{
94
+ height: z.ZodEnum<{
95
+ small: "small";
96
+ large: "large";
97
+ medium: "medium";
98
+ }>;
99
+ chartIds: z.ZodArray<z.ZodString>;
100
+ }, z.core.$strip>>;
64
101
  }, z.core.$strip>, z.ZodObject<{
65
102
  type: z.ZodLiteral<"add-charts">;
66
103
  priorDashboardId: z.ZodString;
67
104
  chartIds: z.ZodArray<z.ZodString>;
105
+ placements: z.ZodOptional<z.ZodArray<z.ZodOptional<z.ZodObject<{
106
+ row: z.ZodNumber;
107
+ cell: z.ZodOptional<z.ZodNumber>;
108
+ relativeTo: z.ZodOptional<z.ZodObject<{
109
+ widgetId: z.ZodString;
110
+ position: z.ZodEnum<{
111
+ before: "before";
112
+ after: "after";
113
+ }>;
114
+ }, z.core.$strip>>;
115
+ height: z.ZodOptional<z.ZodEnum<{
116
+ small: "small";
117
+ large: "large";
118
+ medium: "medium";
119
+ }>>;
120
+ }, z.core.$strip>>>>;
121
+ }, z.core.$strip>, z.ZodObject<{
122
+ type: z.ZodLiteral<"remove-charts">;
123
+ priorDashboardId: z.ZodString;
124
+ widgetIds: z.ZodArray<z.ZodString>;
125
+ }, z.core.$strip>, z.ZodObject<{
126
+ type: z.ZodLiteral<"replace-charts">;
127
+ priorDashboardId: z.ZodString;
128
+ replacements: z.ZodArray<z.ZodObject<{
129
+ widgetId: z.ZodString;
130
+ chartId: z.ZodString;
131
+ }, z.core.$strip>>;
68
132
  }, z.core.$strip>, z.ZodObject<{
69
133
  type: z.ZodLiteral<"update-title">;
70
134
  priorDashboardId: z.ZodString;
71
135
  title: z.ZodString;
136
+ }, z.core.$strip>, z.ZodObject<{
137
+ type: z.ZodLiteral<"update-row-height">;
138
+ priorDashboardId: z.ZodString;
139
+ row: z.ZodNumber;
140
+ height: z.ZodEnum<{
141
+ small: "small";
142
+ large: "large";
143
+ medium: "medium";
144
+ }>;
145
+ }, z.core.$strip>, z.ZodObject<{
146
+ type: z.ZodLiteral<"add-narration">;
147
+ priorDashboardId: z.ZodString;
148
+ height: z.ZodOptional<z.ZodEnum<{
149
+ small: "small";
150
+ large: "large";
151
+ medium: "medium";
152
+ }>>;
72
153
  }, z.core.$strip>, z.ZodObject<{
73
154
  type: z.ZodLiteral<"add-filters">;
74
155
  priorDashboardId: z.ZodString;
75
156
  filterDescription: z.ZodString;
76
- }, z.core.$strip>]>;
157
+ }, z.core.$strip>], "type">;
77
158
  export type BuildDashboardAction = z.infer<typeof buildDashboardActionSchema>;
78
159
  /**
79
160
  * Schema for the main buildDashboard smart tool
80
161
  */
81
162
  export declare const buildDashboardSchema: z.ZodObject<{
82
163
  dataSourceTitle: z.ZodString;
83
- action: z.ZodDiscriminatedUnion<[z.ZodObject<{
164
+ action: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
84
165
  type: z.ZodLiteral<"load-existing">;
85
- dashboardTitle: z.ZodString;
166
+ dashboardTitle: z.ZodOptional<z.ZodString>;
167
+ dashboardId: z.ZodOptional<z.ZodString>;
86
168
  }, z.core.$strip>, z.ZodObject<{
87
169
  type: z.ZodLiteral<"create">;
88
170
  title: z.ZodString;
89
- chartIds: z.ZodArray<z.ZodString>;
171
+ rows: z.ZodArray<z.ZodObject<{
172
+ height: z.ZodEnum<{
173
+ small: "small";
174
+ large: "large";
175
+ medium: "medium";
176
+ }>;
177
+ chartIds: z.ZodArray<z.ZodString>;
178
+ }, z.core.$strip>>;
90
179
  }, z.core.$strip>, z.ZodObject<{
91
180
  type: z.ZodLiteral<"add-charts">;
92
181
  priorDashboardId: z.ZodString;
93
182
  chartIds: z.ZodArray<z.ZodString>;
183
+ placements: z.ZodOptional<z.ZodArray<z.ZodOptional<z.ZodObject<{
184
+ row: z.ZodNumber;
185
+ cell: z.ZodOptional<z.ZodNumber>;
186
+ relativeTo: z.ZodOptional<z.ZodObject<{
187
+ widgetId: z.ZodString;
188
+ position: z.ZodEnum<{
189
+ before: "before";
190
+ after: "after";
191
+ }>;
192
+ }, z.core.$strip>>;
193
+ height: z.ZodOptional<z.ZodEnum<{
194
+ small: "small";
195
+ large: "large";
196
+ medium: "medium";
197
+ }>>;
198
+ }, z.core.$strip>>>>;
199
+ }, z.core.$strip>, z.ZodObject<{
200
+ type: z.ZodLiteral<"remove-charts">;
201
+ priorDashboardId: z.ZodString;
202
+ widgetIds: z.ZodArray<z.ZodString>;
203
+ }, z.core.$strip>, z.ZodObject<{
204
+ type: z.ZodLiteral<"replace-charts">;
205
+ priorDashboardId: z.ZodString;
206
+ replacements: z.ZodArray<z.ZodObject<{
207
+ widgetId: z.ZodString;
208
+ chartId: z.ZodString;
209
+ }, z.core.$strip>>;
94
210
  }, z.core.$strip>, z.ZodObject<{
95
211
  type: z.ZodLiteral<"update-title">;
96
212
  priorDashboardId: z.ZodString;
97
213
  title: z.ZodString;
214
+ }, z.core.$strip>, z.ZodObject<{
215
+ type: z.ZodLiteral<"update-row-height">;
216
+ priorDashboardId: z.ZodString;
217
+ row: z.ZodNumber;
218
+ height: z.ZodEnum<{
219
+ small: "small";
220
+ large: "large";
221
+ medium: "medium";
222
+ }>;
223
+ }, z.core.$strip>, z.ZodObject<{
224
+ type: z.ZodLiteral<"add-narration">;
225
+ priorDashboardId: z.ZodString;
226
+ height: z.ZodOptional<z.ZodEnum<{
227
+ small: "small";
228
+ large: "large";
229
+ medium: "medium";
230
+ }>>;
98
231
  }, z.core.$strip>, z.ZodObject<{
99
232
  type: z.ZodLiteral<"add-filters">;
100
233
  priorDashboardId: z.ZodString;
101
234
  filterDescription: z.ZodString;
102
- }, z.core.$strip>]>;
235
+ }, z.core.$strip>], "type">, unknown>;
103
236
  }, z.core.$strip>;
104
237
  export type BuildDashboardParams = z.infer<typeof buildDashboardSchema>;
105
- /**
106
- * Schema for createDashboard tool
107
- */
108
- export declare const createDashboardSchema: z.ZodObject<{
109
- dashboardTitle: z.ZodOptional<z.ZodString>;
110
- widgetIdsToAdd: z.ZodArray<z.ZodString>;
111
- }, z.core.$strip>;
112
- export type CreateDashboardParams = z.infer<typeof createDashboardSchema>;
113
238
  /**
114
239
  * Schema for loadExistingDashboard tool
115
240
  */
116
241
  export declare const loadExistingFusionDashboardSchema: z.ZodObject<{
117
- dashboardTitle: z.ZodString;
242
+ dashboardTitle: z.ZodOptional<z.ZodString>;
243
+ dashboardId: z.ZodOptional<z.ZodString>;
118
244
  }, z.core.$strip>;
119
245
  export type LoadExistingFusionDashboardParams = z.infer<typeof loadExistingFusionDashboardSchema>;
120
246
  /**
@@ -131,8 +257,32 @@ export type UpdateDashboardParams = z.infer<typeof updateDashboardSchema>;
131
257
  export declare const addDashboardWidgetsSchema: z.ZodObject<{
132
258
  dashboardId: z.ZodString;
133
259
  widgetIdsToAdd: z.ZodArray<z.ZodString>;
260
+ placements: z.ZodOptional<z.ZodArray<z.ZodOptional<z.ZodObject<{
261
+ row: z.ZodNumber;
262
+ cell: z.ZodOptional<z.ZodNumber>;
263
+ relativeTo: z.ZodOptional<z.ZodObject<{
264
+ widgetId: z.ZodString;
265
+ position: z.ZodEnum<{
266
+ before: "before";
267
+ after: "after";
268
+ }>;
269
+ }, z.core.$strip>>;
270
+ height: z.ZodOptional<z.ZodEnum<{
271
+ small: "small";
272
+ large: "large";
273
+ medium: "medium";
274
+ }>>;
275
+ }, z.core.$strip>>>>;
134
276
  }, z.core.$strip>;
135
277
  export type AddDashboardWidgetsParams = z.infer<typeof addDashboardWidgetsSchema>;
278
+ /**
279
+ * Schema for removeDashboardWidgets tool
280
+ */
281
+ export declare const removeDashboardWidgetsSchema: z.ZodObject<{
282
+ dashboardId: z.ZodString;
283
+ widgetIds: z.ZodArray<z.ZodString>;
284
+ }, z.core.$strip>;
285
+ export type RemoveDashboardWidgetsParams = z.infer<typeof removeDashboardWidgetsSchema>;
136
286
  /**
137
287
  * Schema for addDashboardFilters tool
138
288
  */
@@ -149,6 +299,8 @@ export interface BuildDashboardContext {
149
299
  * Tool call ID - REQUIRED
150
300
  */
151
301
  toolCallId: string;
302
+ /** `x-tool-name` for this run's LLM calls when another tool runs the engine. Default `buildDashboard`. */
303
+ toolName?: string;
152
304
  abortSignal?: AbortSignal;
153
305
  /**
154
306
  * Data source title (required)
@@ -183,6 +335,16 @@ export interface BuildDashboardContext {
183
335
  * @returns Array of widget props
184
336
  */
185
337
  getWidgetList?: (widgetIds: string[]) => WidgetProps[];
338
+ /**
339
+ * Resolves chart tool-call IDs to widgets, skipping IDs that are missing
340
+ * from the session context instead of failing the whole operation.
341
+ */
342
+ resolveChartWidgets?: (chartIds: string[]) => ChartWidgetResolution;
343
+ /**
344
+ * Whether Dashboard Narrative widgets may be added. False when the Narrative feature is off:
345
+ * the add-narration action is refused. Absent means allowed.
346
+ */
347
+ narrativeWidgetEnabled?: boolean;
186
348
  httpClient?: HttpClient;
187
349
  llmClient?: LanguageModel;
188
350
  }
@@ -1,4 +1,4 @@
1
- import { z } from 'zod/v4';
1
+ import { z } from 'zod';
2
2
  import { toolSchema, BuildDataModelContext, BuildDataModelEngineResult } from './types';
3
3
  type ToolParams = z.infer<typeof toolSchema>;
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { z } from 'zod/v4';
1
+ import { z } from 'zod';
2
2
  import { LanguageModel, ModelMessage } from 'ai';
3
3
  export declare const toolSchema: z.ZodObject<{
4
4
  modelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -1,10 +1,38 @@
1
- import { z } from 'zod/v4';
2
- import { buildQuerySchema, BuildQueryContext, QueryResult } from './types';
1
+ import { BuildQueryParams, BuildQueryContext, BuildQueryOutcome, QueryResult } from './types';
3
2
  /**
4
- * Standalone build query engine - completely decoupled from any UI or store
5
- * Converts a natural language query into an NLQ result and dataset
3
+ * Runs NLQ generation directly, with no existing-answer cascade — always produces a fresh (or
4
+ * revised) query result. Used internally by other engines (e.g. buildChart's create-chart flow)
5
+ * that need an actual query to operate on, not a pointer to an existing widget. The cascade-aware
6
+ * `buildQueryEngine` below is a thin wrapper around this for the LLM-facing buildQuery tool.
6
7
  * @param params - The parameters containing data source title and query prompt
7
8
  * @param context - Context with tool call ID and optional httpClient
8
9
  * @returns The query result with queryId, nlqResult, and dataset
9
10
  */
10
- export declare function buildQueryEngine(params: z.infer<typeof buildQuerySchema>, context: BuildQueryContext): Promise<QueryResult>;
11
+ export declare function runNlqQuery(params: BuildQueryParams, context: BuildQueryContext): Promise<QueryResult>;
12
+ /**
13
+ * Cascade-aware entrypoint for the `buildQuery` LLM tool: for a new question (no `priorQueryId`),
14
+ * first tries the existing-answer cascade (KG similar-question match, then widget semantic search)
15
+ * before paying for NLQ generation; revisions (`priorQueryId` set) always skip straight to NLQ.
16
+ * `forceNewQuery` also skips the cascade on a new question — the only escape hatch once a prior
17
+ * call already returned an existing-answer match for this same question (which mints no queryId to
18
+ * revise from, so `priorQueryId` alone can't express "give me a fresh one instead").
19
+ *
20
+ * On a cascade hit, tries to reconstruct the widget's real JAQL into a buildChart-ready query
21
+ * state (`'existing-chart'`) so the session continues exactly as if NLQ had generated it; if that
22
+ * reconstruction fails for this widget (e.g. an unsupported JAQL shape), falls back to the
23
+ * original link/preview-only result (`'existing-answer'`) rather than failing the tool call.
24
+ *
25
+ * Whenever generation falls through to a plain NLQ result — a revision, or a new question the
26
+ * cascade above didn't match — makes one best-effort, post-generation widget-search check against
27
+ * the *resolved* query's own title (already a coherent, widget-title-shaped string; no new
28
+ * synthesis needed) so a revision or a cascade-miss can still pick up the verified badge. Reuses
29
+ * `findWidgetMatch` unmodified (not `findKgMatch`/`findExistingAnswer` — KG's threshold is tuned
30
+ * for real user-typed questions, not a resolved/synthesized title). Never blocks or fails the tool
31
+ * call: skipped entirely under the same guards as the pre-generation cascade (`forceNewQuery`,
32
+ * `cascadeEnabled === false`), and `findWidgetMatch` itself never throws.
33
+ * @param params - The parameters containing data source title and query prompt
34
+ * @param context - Context with tool call ID and optional httpClient
35
+ * @returns An existing widget (reconstructed into a real chart, or as a link/preview fallback),
36
+ * or a freshly generated NLQ result (optionally carrying verified-match metadata, see above).
37
+ */
38
+ export declare function buildQueryEngine(params: BuildQueryParams, context: BuildQueryContext): Promise<BuildQueryOutcome>;
@@ -1,2 +1,2 @@
1
- export { buildQueryEngine } from './build-query-engine';
1
+ export { buildQueryEngine, runNlqQuery } from './build-query-engine';
2
2
  export * from './types';