@sqlrooms/mosaic 0.29.0-rc.4 → 0.29.0-rc.6

package/dist/VgPlotChartError.d.ts

@@ -0,0 +1,7 @@
+import { FC } from 'react';
+type VgPlotChartErrorProps = {
+    error: Error;
+};
+export declare const VgPlotChartError: FC<VgPlotChartErrorProps>;
+export {};
+//# sourceMappingURL=VgPlotChartError.d.ts.map

package/dist/VgPlotChartError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VgPlotChartError.d.ts","sourceRoot":"","sources":["../src/VgPlotChartError.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAC,EAAE,EAAC,MAAM,OAAO,CAAC;AAGzB,KAAK,qBAAqB,GAAG;IAC3B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,qBAAqB,CActD,CAAC"}

package/dist/VgPlotChartError.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DataPointLimitError } from './DataPointLimitError';
+export const VgPlotChartError = ({ error }) => {
+    const title = error instanceof DataPointLimitError
+        ? 'Too much data'
+        : 'Unable to display chart';
+    return (_jsxs("div", { className: "flex h-full min-h-[200px] flex-col items-center justify-center p-4", children: [_jsx("div", { className: "mb-2 text-center font-semibold", children: title }), _jsx("div", { className: "text-center text-sm whitespace-pre-wrap", children: error.message })] }));
+};
+//# sourceMappingURL=VgPlotChartError.js.map

package/dist/VgPlotChartError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VgPlotChartError.js","sourceRoot":"","sources":["../src/VgPlotChartError.tsx"],"names":[],"mappings":";AACA,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAM1D,MAAM,CAAC,MAAM,gBAAgB,GAA8B,CAAC,EAAC,KAAK,EAAC,EAAE,EAAE;IACrE,MAAM,KAAK,GACT,KAAK,YAAY,mBAAmB;QAClC,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,yBAAyB,CAAC;IAEhC,OAAO,CACL,eAAK,SAAS,EAAC,oEAAoE,aACjF,cAAK,SAAS,EAAC,gCAAgC,YAAE,KAAK,GAAO,EAC7D,cAAK,SAAS,EAAC,yCAAyC,YACrD,KAAK,CAAC,OAAO,GACV,IACF,CACP,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import {FC} from 'react';\nimport {DataPointLimitError} from './DataPointLimitError';\n\ntype VgPlotChartErrorProps = {\n  error: Error;\n};\n\nexport const VgPlotChartError: FC<VgPlotChartErrorProps> = ({error}) => {\n  const title =\n    error instanceof DataPointLimitError\n      ? 'Too much data'\n      : 'Unable to display chart';\n\n  return (\n    <div className=\"flex h-full min-h-[200px] flex-col items-center justify-center p-4\">\n      <div className=\"mb-2 text-center font-semibold\">{title}</div>\n      <div className=\"text-center text-sm whitespace-pre-wrap\">\n        {error.message}\n      </div>\n    </div>\n  );\n};\n"]}

package/dist/ai.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Reusable AI helpers for Mosaic dashboards.
+ *
+ * Host apps provide a narrow adapter for their store/artifact model; Mosaic owns
+ * the dashboard tool behavior and prompts.
+ *
+ * @packageDocumentation
+ */
+import { type LanguageModel, type Tool, ToolLoopAgent } from 'ai';
+import { type ChartBuilderColumn, type ChartToolExecutionContext, type DashboardToolDeps, type PanelPatch, type ChartTypeDefinition } from './chart-types';
+import type { MosaicDashboardEntry, MosaicDashboardPanelConfig } from './dashboard/dashboard-types';
+import type { MosaicDashboardLayoutType } from './dashboard/core-types';
+import { type ChartRuntimeIssue } from './chart-runtime';
+export type { ChartToolExecutionContext } from './chart-types';
+export type DashboardAiStore<TState> = {
+    getState: () => TState;
+};
+export type DashboardAiTable = {
+    tableName: string;
+    columns?: ChartBuilderColumn[];
+    rowCount?: number;
+};
+export type DashboardAiAdapter<TState> = {
+    getTables: (state: TState) => DashboardAiTable[];
+    hasRunContext?: (state: TState, context?: ChartToolExecutionContext) => boolean;
+    resolveContextDashboardArtifactId?: (state: TState, context?: ChartToolExecutionContext) => string | undefined;
+    makeDashboardPrimaryForRun?: (state: TState, dashboardId: string, context?: ChartToolExecutionContext) => void;
+    getCurrentDashboardArtifactId: (state: TState) => string | undefined;
+    createDashboardArtifact: (state: TState, title?: string, layoutType?: MosaicDashboardLayoutType) => string;
+    isDashboardArtifact: (state: TState, artifactId: string) => boolean;
+    setCurrentArtifact: (state: TState, artifactId: string) => void;
+    ensureDashboard: (state: TState, dashboardId: string, title?: string, layoutType?: MosaicDashboardLayoutType) => void;
+    getDashboard: (state: TState, dashboardId: string) => MosaicDashboardEntry | undefined;
+    getPanelIssue?: (state: TState, dashboardId: string, panelId: string) => ChartRuntimeIssue | undefined;
+    setSelectedTable: (state: TState, dashboardId: string, tableName: string) => void;
+    addPanel: (state: TState, dashboardId: string, panel: MosaicDashboardPanelConfig) => string;
+    updatePanel: (state: TState, dashboardId: string, panelId: string, patch: Partial<PanelPatch>) => void;
+    removePanel: (state: TState, dashboardId: string, panelId: string) => void;
+};
+export type CreateDashboardToolDepsOptions<TState> = {
+    store: DashboardAiStore<TState>;
+    adapter: DashboardAiAdapter<TState>;
+};
+export type CreateDashboardAiToolsOptions<TState> = CreateDashboardToolDepsOptions<TState> & {
+    chartTypes?: ChartTypeDefinition<any>[];
+    /**
+     * Host-provided dashboard tools keyed by their registered tool name.
+     * Register geospatial map tools under MAP_TOOL_KEY so prompts and tools
+     * stay in sync.
+     */
+    extraTools?: (deps: DashboardToolDeps) => Record<string, Tool>;
+};
+export type DashboardAgentToolCall = {
+    toolName: string;
+};
+export type DashboardAgentRunResult = {
+    finalOutput?: string;
+    agentToolCalls?: DashboardAgentToolCall[];
+};
+export type DashboardAgentResult = {
+    success: boolean;
+    finalOutput: string;
+    dashboardId: string;
+    error?: string;
+    metadata?: {
+        tableName: string;
+        panelsCreated: number;
+        stepsExecuted: number;
+        queriesRun: number;
+    };
+};
+export type CreateDashboardAgentToolOptions<TState> = CreateDashboardToolDepsOptions<TState> & {
+    getModel: (args: {
+        state: TState;
+    }) => LanguageModel;
+    createQueryTools?: (args: {
+        store: DashboardAiStore<TState>;
+    }) => {
+        query: Tool;
+    };
+    runSubAgent: (args: {
+        agent: ToolLoopAgent<any, any, any>;
+        prompt: string;
+        store: DashboardAiStore<TState>;
+        parentToolCallId: string;
+        abortSignal?: AbortSignal;
+    }) => Promise<DashboardAgentRunResult>;
+    instructions?: string;
+    chartTypes?: ChartTypeDefinition<any>[];
+    /**
+     * Host-provided dashboard tools keyed by their registered tool name.
+     * Register geospatial map tools under MAP_TOOL_KEY so prompts and tools
+     * stay in sync.
+     */
+    extraTools?: (deps: DashboardToolDeps) => Record<string, Tool>;
+};
+export declare const MAP_TOOL_KEY = "create_dashboard_map";
+export declare const DASHBOARD_AI_INSTRUCTIONS = "\nDashboard authoring:\n\n**When to use dashboard_agent vs individual tools:**\n- Use `dashboard_agent` for exploratory requests that require data analysis and discovery:\n  - \"analyze the earthquakes dataset\"\n  - \"create insights dashboard for sales data\"\n  - \"find interesting patterns in customer behavior\"\n  - Any request asking to \"discover\", \"explore\", \"find insights\", or \"analyze\"\n- Use individual chart tools for direct, specific requests:\n  - \"create histogram of magnitude with 20 bins\"\n  - \"add a line chart showing sales over time\"\n  - \"update the histogram to use 30 bins\"\n\n**Individual dashboard chart tools:**\n- create_dashboard_histogram, create_dashboard_line_chart, create_dashboard_box_plot, create_dashboard_bubble_chart, create_dashboard_count_plot, create_dashboard_heatmap\n- Each chart type has its own tool with specific parameters.\n- For line charts with aggregation, use yFields array with {field: string, aggregate: \"sum\"|\"avg\"|\"min\"|\"max\"}.\n- Set xInterval for temporal binning (year, month, day, hour, etc.).\n- If the host app provides `create_dashboard_map`, use it for map/geospatial/location requests and tables with longitude/latitude or geometry columns. Author its config as native Deck JSON with layer classes in `spec.layers[].@@type`, dataset bindings in `_sqlroomsBinding.dataset`, and table/query sources in `config.datasets`. For data-driven map colors, use color accessors such as `getFillColor`, `getLineColor`, `getColor`, `getSourceColor`, or `getTargetColor` with `{\"@@function\":\"colorScale\", \"field\":\"...\", \"type\":\"sequential\"|\"diverging\"|\"quantize\"|\"quantile\"|\"categorical\", \"scheme\":\"Viridis\", \"domain\":\"auto\"}`.\n- Use `set_dashboard_vgplot` with complete JSON only when no chart tool fits your needs.\n- When calling `create_dashboard_artifact`, `layoutType` may be `grid` or `dock`; omitted values default to `grid`.\n- Ensure specs are valid JSON objects compatible with https://idl.uw.edu/mosaic/schema/latest.json.\n- `list_dashboard_panels` includes runtime issues when a chart failed. Use those issues to repair panels in place: convert too-large bubble charts to heatmaps, add `xInterval` to too-large line charts, and inspect columns/settings for SQL errors.\n";
+export declare const DASHBOARD_AGENT_INSTRUCTIONS = "You are a dashboard builder agent that creates and modifies interactive data dashboards.\n\n## Your Role\n\nYou analyze data and create insightful dashboards with multiple visualizations (charts, profilers, text annotations). You can handle both direct requests (\"create histogram of magnitude\") and exploratory requests (\"find interesting insights in earthquakes dataset\").\n\n## Available Tools\n\n**Chart Tools:**\n- create_dashboard_histogram - distribution of numeric values (always safe, aggregates automatically)\n- create_dashboard_line_chart - trends over time or ordered variable (use with aggregations for >10k rows)\n- create_dashboard_box_plot - compare distributions across categories\n- create_dashboard_bubble_chart - relationship between two numeric columns (avoid for >10k rows, use heatmap instead)\n- create_dashboard_count_plot - frequency of categorical values (always safe, aggregates automatically)\n- create_dashboard_heatmap - density/patterns across two dimensions (preferred for large datasets)\n\n**Panel Tools:**\n- create_dashboard_profiler - table statistics and column summaries\n- create_dashboard_text_panel - markdown annotations and insights\n- create_dashboard_map - native Deck JSON geospatial map panel (if provided by the host app)\n\n**Data Tools:**\n- query - execute SQL queries for data exploration\n\n**Management Tools:**\n- list_dashboard_panels - discover panel IDs and what's on the dashboard\n- remove_dashboard_panel - delete a panel by ID\n\n## Workflows\n\n### Direct Requests\nWhen user provides specific instructions:\n1. Parse intent -> identify chart type\n2. Call appropriate tool with settings\n3. Done\n\nExample: \"create histogram of magnitude with 20 bins\"\n-> create_dashboard_histogram(settings: {field: \"magnitude\", bins: 20})\n\n### Exploratory Requests\nWhen user asks to discover insights:\n1. Use query tool to explore data:\n   - Start with simple stats: COUNT, MIN, MAX, AVG, DISTINCT (check total row count!)\n   - Check distributions: GROUP BY with COUNT\n   - Find correlations: CORR(col1, col2)\n   - Identify outliers and patterns\n2. Create targeted charts based on discoveries:\n   - If dataset has >10k rows: avoid bubble charts and unaggregated line charts\n   - Use histogram, count plot, heatmap, or aggregated visualizations instead\n3. **ALWAYS create ONE text panel** with a concise summary of ALL key findings\n4. Stop when dashboard tells coherent story\n\n**CRITICAL:**\n- Create exactly ONE text panel with insights summary (can be first, last, or in between)\n- Insights should be concise but USEFUL - each bullet should provide actionable or interesting information\n- Include specific numbers, percentages, and comparisons that tell the story\n- Use query tool to discover actual patterns, don't make vague statements\n- Focus on 3-5 most important findings that answer \"what's interesting about this data?\"\n- Do NOT create additional text panels unless absolutely necessary\n\n**Good insight examples:**\n- \"Peak activity between 4-5 magnitude (62% of events)\" - specific, actionable\n- \"Strong correlation (0.73) between depth and magnitude suggests tectonic pattern\" - specific with interpretation\n- \"California accounts for 3,234/5,234 events (62%), followed by Japan (18%)\" - specific comparison\n\n**Bad insight examples:**\n- \"Dataset has data\" - useless\n- \"Various magnitudes observed\" - vague\n- \"Interesting patterns found\" - not specific\n\n### Update Requests\nTo update existing panels:\n1. Call list_dashboard_panels() to discover panel IDs\n2. Call appropriate create tool with panelId parameter\n3. Panel is updated in-place\n\n## Query Guidelines\n\n**Keep queries simple:**\n- Start with aggregations: COUNT, MIN, MAX, AVG, SUM\n- Use GROUP BY for breakdowns and distributions\n- Use LIMIT to control result size (especially with GROUP BY)\n- Avoid expensive operations: large JOINs, full table scans\n\n**Exploration strategy:**\n- Limit exploration to 5-10 queries per request\n- Start broad (overall stats), then narrow (specific patterns)\n- Stop when you have enough insights for a coherent dashboard\n\n## Best Practices\n\n- **ONE text panel for exploratory requests:** Always create exactly ONE text panel with insights summary when exploring data. It can be created at any point in the workflow.\n- **Make insights useful, not just concise:** Each bullet should include specific numbers, percentages, or patterns discovered through queries. Avoid vague statements.\n- **Use queries to find real insights:** Run queries to discover actual patterns (correlations, distributions, outliers, top values). Don't make assumptions.\n- **No additional text panels:** Do NOT create multiple text panels. All insights go in the single summary panel.\n- **Avoid unaggregated charts for large datasets:** For datasets >10k rows, DO NOT use bubble charts or line charts without aggregations. Use aggregated alternatives instead:\n  - For scatter/bubble plots: use heatmap or binned aggregations\n  - For line charts: use GROUP BY with time buckets or aggregations\n  - Histograms and count plots are always safe (they aggregate automatically)\n- **Check before update:** Always call list_dashboard_panels before updating/removing panels\n- **Repair broken charts:** list_dashboard_panels may return an `issue` per panel. For `too-much-data`, switch to an aggregated chart or add aggregation. For `sql-error`, inspect available columns/types and update the broken panel in place.\n- **Validate columns:** Query tools will validate column existence and types\n- **Handle errors gracefully:** If a query or chart creation fails, try alternative approach\n- **Use markdown formatting:** Use headings (##), bullet lists (-), and **bold** in text panels for readability";
+export declare function createDashboardToolDeps<TState>({ store, adapter, }: CreateDashboardToolDepsOptions<TState>): DashboardToolDeps;
+export declare function createDashboardAiTools<TState>({ store, adapter, chartTypes, extraTools, }: CreateDashboardAiToolsOptions<TState>): Record<string, Tool>;
+export declare function createDashboardAgentTool<TState>(options: CreateDashboardAgentToolOptions<TState>): Tool;
+//# sourceMappingURL=ai.d.ts.map

package/dist/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"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"}

package/dist/ai.js

@@ -0,0 +1,445 @@
+/**
+ * Reusable AI helpers for Mosaic dashboards.
+ *
+ * Host apps provide a narrow adapter for their store/artifact model; Mosaic owns
+ * the dashboard tool behavior and prompts.
+ *
+ * @packageDocumentation
+ */
+import { ToolLoopAgent, stepCountIs, tool, } from 'ai';
+import { z } from 'zod';
+import { createChartTools, createDefaultChartTypes, createListPanelsTool, createProfilerTool, createRemovePanelTool, createTextPanelTool, } from './chart-types';
+import { DEFAULT_CHART_MAX_DATA_POINTS, } from './chart-runtime';
+export const MAP_TOOL_KEY = 'create_dashboard_map';
+export const DASHBOARD_AI_INSTRUCTIONS = `
+Dashboard authoring:
+
+**When to use dashboard_agent vs individual tools:**
+- Use \`dashboard_agent\` for exploratory requests that require data analysis and discovery:
+  - "analyze the earthquakes dataset"
+  - "create insights dashboard for sales data"
+  - "find interesting patterns in customer behavior"
+  - Any request asking to "discover", "explore", "find insights", or "analyze"
+- Use individual chart tools for direct, specific requests:
+  - "create histogram of magnitude with 20 bins"
+  - "add a line chart showing sales over time"
+  - "update the histogram to use 30 bins"
+
+**Individual dashboard chart tools:**
+- create_dashboard_histogram, create_dashboard_line_chart, create_dashboard_box_plot, create_dashboard_bubble_chart, create_dashboard_count_plot, create_dashboard_heatmap
+- Each chart type has its own tool with specific parameters.
+- For line charts with aggregation, use yFields array with {field: string, aggregate: "sum"|"avg"|"min"|"max"}.
+- Set xInterval for temporal binning (year, month, day, hour, etc.).
+- If the host app provides \`${MAP_TOOL_KEY}\`, use it for map/geospatial/location requests and tables with longitude/latitude or geometry columns. Author its config as native Deck JSON with layer classes in \`spec.layers[].@@type\`, dataset bindings in \`_sqlroomsBinding.dataset\`, and table/query sources in \`config.datasets\`. For data-driven map colors, use color accessors such as \`getFillColor\`, \`getLineColor\`, \`getColor\`, \`getSourceColor\`, or \`getTargetColor\` with \`{"@@function":"colorScale", "field":"...", "type":"sequential"|"diverging"|"quantize"|"quantile"|"categorical", "scheme":"Viridis", "domain":"auto"}\`.
+- Use \`set_dashboard_vgplot\` with complete JSON only when no chart tool fits your needs.
+- When calling \`create_dashboard_artifact\`, \`layoutType\` may be \`grid\` or \`dock\`; omitted values default to \`grid\`.
+- Ensure specs are valid JSON objects compatible with https://idl.uw.edu/mosaic/schema/latest.json.
+- \`list_dashboard_panels\` includes runtime issues when a chart failed. Use those issues to repair panels in place: convert too-large bubble charts to heatmaps, add \`xInterval\` to too-large line charts, and inspect columns/settings for SQL errors.
+`;
+export const DASHBOARD_AGENT_INSTRUCTIONS = `You are a dashboard builder agent that creates and modifies interactive data dashboards.
+
+## Your Role
+
+You analyze data and create insightful dashboards with multiple visualizations (charts, profilers, text annotations). You can handle both direct requests ("create histogram of magnitude") and exploratory requests ("find interesting insights in earthquakes dataset").
+
+## Available Tools
+
+**Chart Tools:**
+- create_dashboard_histogram - distribution of numeric values (always safe, aggregates automatically)
+- create_dashboard_line_chart - trends over time or ordered variable (use with aggregations for >10k rows)
+- create_dashboard_box_plot - compare distributions across categories
+- create_dashboard_bubble_chart - relationship between two numeric columns (avoid for >10k rows, use heatmap instead)
+- create_dashboard_count_plot - frequency of categorical values (always safe, aggregates automatically)
+- create_dashboard_heatmap - density/patterns across two dimensions (preferred for large datasets)
+
+**Panel Tools:**
+- create_dashboard_profiler - table statistics and column summaries
+- create_dashboard_text_panel - markdown annotations and insights
+- ${MAP_TOOL_KEY} - native Deck JSON geospatial map panel (if provided by the host app)
+
+**Data Tools:**
+- query - execute SQL queries for data exploration
+
+**Management Tools:**
+- list_dashboard_panels - discover panel IDs and what's on the dashboard
+- remove_dashboard_panel - delete a panel by ID
+
+## Workflows
+
+### Direct Requests
+When user provides specific instructions:
+1. Parse intent -> identify chart type
+2. Call appropriate tool with settings
+3. Done
+
+Example: "create histogram of magnitude with 20 bins"
+-> create_dashboard_histogram(settings: {field: "magnitude", bins: 20})
+
+### Exploratory Requests
+When user asks to discover insights:
+1. Use query tool to explore data:
+   - Start with simple stats: COUNT, MIN, MAX, AVG, DISTINCT (check total row count!)
+   - Check distributions: GROUP BY with COUNT
+   - Find correlations: CORR(col1, col2)
+   - Identify outliers and patterns
+2. Create targeted charts based on discoveries:
+   - If dataset has >10k rows: avoid bubble charts and unaggregated line charts
+   - Use histogram, count plot, heatmap, or aggregated visualizations instead
+3. **ALWAYS create ONE text panel** with a concise summary of ALL key findings
+4. Stop when dashboard tells coherent story
+
+**CRITICAL:**
+- Create exactly ONE text panel with insights summary (can be first, last, or in between)
+- Insights should be concise but USEFUL - each bullet should provide actionable or interesting information
+- Include specific numbers, percentages, and comparisons that tell the story
+- Use query tool to discover actual patterns, don't make vague statements
+- Focus on 3-5 most important findings that answer "what's interesting about this data?"
+- Do NOT create additional text panels unless absolutely necessary
+
+**Good insight examples:**
+- "Peak activity between 4-5 magnitude (62% of events)" - specific, actionable
+- "Strong correlation (0.73) between depth and magnitude suggests tectonic pattern" - specific with interpretation
+- "California accounts for 3,234/5,234 events (62%), followed by Japan (18%)" - specific comparison
+
+**Bad insight examples:**
+- "Dataset has data" - useless
+- "Various magnitudes observed" - vague
+- "Interesting patterns found" - not specific
+
+### Update Requests
+To update existing panels:
+1. Call list_dashboard_panels() to discover panel IDs
+2. Call appropriate create tool with panelId parameter
+3. Panel is updated in-place
+
+## Query Guidelines
+
+**Keep queries simple:**
+- Start with aggregations: COUNT, MIN, MAX, AVG, SUM
+- Use GROUP BY for breakdowns and distributions
+- Use LIMIT to control result size (especially with GROUP BY)
+- Avoid expensive operations: large JOINs, full table scans
+
+**Exploration strategy:**
+- Limit exploration to 5-10 queries per request
+- Start broad (overall stats), then narrow (specific patterns)
+- Stop when you have enough insights for a coherent dashboard
+
+## Best Practices
+
+- **ONE text panel for exploratory requests:** Always create exactly ONE text panel with insights summary when exploring data. It can be created at any point in the workflow.
+- **Make insights useful, not just concise:** Each bullet should include specific numbers, percentages, or patterns discovered through queries. Avoid vague statements.
+- **Use queries to find real insights:** Run queries to discover actual patterns (correlations, distributions, outliers, top values). Don't make assumptions.
+- **No additional text panels:** Do NOT create multiple text panels. All insights go in the single summary panel.
+- **Avoid unaggregated charts for large datasets:** For datasets >10k rows, DO NOT use bubble charts or line charts without aggregations. Use aggregated alternatives instead:
+  - For scatter/bubble plots: use heatmap or binned aggregations
+  - For line charts: use GROUP BY with time buckets or aggregations
+  - Histograms and count plots are always safe (they aggregate automatically)
+- **Check before update:** Always call list_dashboard_panels before updating/removing panels
+- **Repair broken charts:** list_dashboard_panels may return an \`issue\` per panel. For \`too-much-data\`, switch to an aggregated chart or add aggregation. For \`sql-error\`, inspect available columns/types and update the broken panel in place.
+- **Validate columns:** Query tools will validate column existence and types
+- **Handle errors gracefully:** If a query or chart creation fails, try alternative approach
+- **Use markdown formatting:** Use headings (##), bullet lists (-), and **bold** in text panels for readability`;
+const DashboardCreateArtifactToolParameters = z.object({
+    title: z.string().optional(),
+    layoutType: z
+        .enum(['dock', 'grid'])
+        .optional()
+        .default('grid')
+        .describe('Dashboard layout node type to use at creation time.'),
+});
+const DashboardAgentInputSchema = z.object({
+    reasoning: z
+        .string()
+        .describe('Reasoning for why the dashboard agent is being called'),
+    prompt: z
+        .string()
+        .describe('The exploratory data analysis prompt for the agent'),
+    tableName: z
+        .string()
+        .describe('REQUIRED: The name of the table/dataset to analyze.'),
+    dashboardTitle: z
+        .string()
+        .optional()
+        .describe('Optional title for the dashboard artifact'),
+    maxSteps: z
+        .number()
+        .optional()
+        .default(20)
+        .describe('Maximum exploration steps (default: 20, range: 5-50)'),
+    temperature: z
+        .number()
+        .optional()
+        .default(0.7)
+        .describe('Model temperature for creativity vs consistency (default: 0.7, range: 0.0-1.0)'),
+});
+class DashboardAgentException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DashboardAgentException';
+    }
+}
+function getTablesWithColumns(state, adapter) {
+    return adapter
+        .getTables(state)
+        .filter((table) => table.columns && table.columns.length > 0);
+}
+function findTableColumns(state, adapter, tableName) {
+    const table = getTablesWithColumns(state, adapter).find((candidate) => candidate.tableName === tableName);
+    if (!table?.columns)
+        return null;
+    return table.columns.map((column) => ({
+        name: column.name,
+        type: column.type,
+    }));
+}
+function formatAvailableTables(tables) {
+    return tables.map((table) => table.tableName).join(', ') || '(none)';
+}
+export function createDashboardToolDeps({ store, adapter, }) {
+    const resolveArtifact = (artifactId, createIfMissing, context) => {
+        const state = store.getState();
+        const hasRunContext = adapter.hasRunContext?.(state, context) ?? false;
+        const contextDashboardArtifactId = adapter.resolveContextDashboardArtifactId?.(state, context);
+        let targetArtifactId = artifactId ??
+            contextDashboardArtifactId ??
+            (!hasRunContext
+                ? adapter.getCurrentDashboardArtifactId(state)
+                : undefined);
+        if (!targetArtifactId && hasRunContext) {
+            throw new Error('No primary dashboard artifact is available in the current run context. Pass artifactId explicitly or use set_primary_context_artifact first.');
+        }
+        if (!targetArtifactId && createIfMissing) {
+            targetArtifactId = adapter.createDashboardArtifact(state, undefined, 'grid');
+            adapter.setCurrentArtifact(state, targetArtifactId);
+            adapter.makeDashboardPrimaryForRun?.(state, targetArtifactId, context);
+        }
+        if (!targetArtifactId) {
+            throw new Error('No dashboard artifact is available. Set createArtifactIfMissing=true or create one first.');
+        }
+        if (!adapter.isDashboardArtifact(state, targetArtifactId)) {
+            throw new Error(`Artifact "${targetArtifactId}" is not a dashboard artifact.`);
+        }
+        adapter.ensureDashboard(state, targetArtifactId);
+        return targetArtifactId;
+    };
+    const resolveTable = (artifactId, tableName) => {
+        const state = store.getState();
+        const tables = getTablesWithColumns(state, adapter);
+        const dashboard = adapter.getDashboard(state, artifactId);
+        const explicitTableName = tableName?.trim() || undefined;
+        if (explicitTableName) {
+            const columns = findTableColumns(state, adapter, explicitTableName);
+            if (!columns) {
+                throw new Error(`Unknown table "${explicitTableName}". Available tables: ${formatAvailableTables(tables)}.`);
+            }
+            adapter.setSelectedTable(state, artifactId, explicitTableName);
+            return { tableName: explicitTableName, columns };
+        }
+        if (dashboard?.selectedTable) {
+            const columns = findTableColumns(state, adapter, dashboard.selectedTable);
+            if (columns) {
+                return { tableName: dashboard.selectedTable, columns };
+            }
+        }
+        if (tables.length === 1) {
+            const onlyTable = tables[0];
+            if (!onlyTable?.columns) {
+                throw new Error('The only available table has no column metadata.');
+            }
+            adapter.setSelectedTable(state, artifactId, onlyTable.tableName);
+            return {
+                tableName: onlyTable.tableName,
+                columns: onlyTable.columns.map((column) => ({
+                    name: column.name,
+                    type: column.type,
+                })),
+            };
+        }
+        throw new Error(`No dashboard table is selected. Provide tableName using one of: ${formatAvailableTables(tables)}.`);
+    };
+    const deps = {
+        maxDataPoints: DEFAULT_CHART_MAX_DATA_POINTS,
+        resolveArtifact,
+        resolveTable,
+        addPanel: (dashboardId, panel) => {
+            const state = store.getState();
+            return adapter.addPanel(state, dashboardId, panel);
+        },
+        updatePanel: (dashboardId, panelId, patch) => {
+            const state = store.getState();
+            adapter.updatePanel(state, dashboardId, panelId, patch);
+        },
+        getDashboard: (dashboardId) => {
+            const state = store.getState();
+            return adapter.getDashboard(state, dashboardId);
+        },
+        removePanel: (dashboardId, panelId) => {
+            const state = store.getState();
+            adapter.removePanel(state, dashboardId, panelId);
+        },
+        setCurrentArtifact: (artifactId) => {
+            const state = store.getState();
+            adapter.setCurrentArtifact(state, artifactId);
+        },
+    };
+    if (adapter.getPanelIssue) {
+        deps.getPanelIssue = (dashboardId, panelId) => {
+            const state = store.getState();
+            return adapter.getPanelIssue?.(state, dashboardId, panelId);
+        };
+    }
+    return deps;
+}
+export function createDashboardAiTools({ store, adapter, chartTypes, extraTools, }) {
+    const deps = createDashboardToolDeps({ store, adapter });
+    const resolvedChartTypes = chartTypes ?? createDefaultChartTypes({ includeCustomSpec: false });
+    const chartTools = createChartTools(resolvedChartTypes, deps);
+    const hostTools = extraTools?.(deps) ?? {};
+    const builtInTools = {
+        create_dashboard_artifact: tool({
+            description: 'Create a new dashboard artifact with a dock or grid layout and make it the active artifact. Use when no dashboard artifact exists yet.',
+            inputSchema: DashboardCreateArtifactToolParameters,
+            execute: async (params, context) => {
+                const state = store.getState();
+                const artifactId = adapter.createDashboardArtifact(state, params.title, params.layoutType);
+                adapter.setCurrentArtifact(state, artifactId);
+                adapter.makeDashboardPrimaryForRun?.(state, artifactId, context);
+                return {
+                    llmResult: {
+                        success: true,
+                        details: `Created dashboard artifact "${artifactId}".`,
+                        data: { artifactId },
+                    },
+                };
+            },
+        }),
+        ...chartTools,
+        create_dashboard_profiler: createProfilerTool(deps),
+        create_dashboard_text_panel: createTextPanelTool(deps),
+        list_dashboard_panels: createListPanelsTool(deps),
+        remove_dashboard_panel: createRemovePanelTool(deps),
+    };
+    for (const key of Object.keys(hostTools)) {
+        if (key in builtInTools) {
+            throw new Error(`Dashboard extraTools cannot override built-in tool "${key}". Register the host tool under a unique key.`);
+        }
+    }
+    return {
+        ...builtInTools,
+        ...hostTools,
+    };
+}
+function buildAgentPrompt(userPrompt, tableName, state, adapter) {
+    const table = adapter
+        .getTables(state)
+        .find((candidate) => candidate.tableName === tableName);
+    const columnNames = table?.columns?.map((column) => column.name).join(', ') || 'unknown';
+    const rowInfo = table?.rowCount !== undefined ? `Approximate rows: ${table.rowCount}` : '';
+    return `Analyze the "${tableName}" table.
+
+Table info:
+- Columns: ${columnNames}${rowInfo ? `\n- ${rowInfo}` : ''}
+
+User request: ${userPrompt}
+
+Focus on discovering meaningful patterns and creating visualizations that tell a clear story.`;
+}
+function validateTableExists(state, adapter, tableName) {
+    const tables = adapter.getTables(state);
+    const table = tables.find((candidate) => candidate.tableName === tableName);
+    if (!table) {
+        throw new DashboardAgentException(`Table "${tableName}" not found. Available tables: ${formatAvailableTables(tables)}`);
+    }
+}
+function getOrCreateDashboard(state, adapter, tableName, dashboardTitle) {
+    const dashboardId = adapter.getCurrentDashboardArtifactId(state);
+    if (dashboardId) {
+        adapter.ensureDashboard(state, dashboardId);
+        return dashboardId;
+    }
+    const suggestedTitle = dashboardTitle ||
+        `${tableName.charAt(0).toUpperCase() + tableName.slice(1)} Insights`;
+    const newDashboardId = adapter.createDashboardArtifact(state, suggestedTitle, 'grid');
+    adapter.setCurrentArtifact(state, newDashboardId);
+    return newDashboardId;
+}
+function calculateAgentMetadata(state, adapter, dashboardId, tableName, agentToolCalls) {
+    const dashboard = adapter.getDashboard(state, dashboardId);
+    return {
+        tableName,
+        panelsCreated: dashboard?.panels?.length || 0,
+        stepsExecuted: agentToolCalls.length,
+        queriesRun: agentToolCalls.filter((call) => call.toolName === 'query')
+            .length,
+    };
+}
+export function createDashboardAgentTool(options) {
+    const { store, adapter } = options;
+    return tool({
+        description: `An AI agent that explores datasets and creates comprehensive dashboards with multiple visualizations.
+
+Use this for exploratory data analysis tasks like "analyze the earthquakes dataset" or "create insights dashboard for sales data".
+
+The agent will query the data, discover patterns, and create charts, profilers, and text panels with findings.
+
+For simple tasks like "create a histogram of magnitude", use the individual chart tools instead.
+
+IMPORTANT: Always provide tableName parameter when the user mentions a specific dataset.`,
+        inputSchema: DashboardAgentInputSchema,
+        execute: async (params, toolOptions) => {
+            const { prompt, tableName, dashboardTitle, maxSteps, temperature } = params;
+            let dashboardId = '';
+            try {
+                const state = store.getState();
+                validateTableExists(state, adapter, tableName);
+                dashboardId = getOrCreateDashboard(state, adapter, tableName, dashboardTitle);
+                adapter.setSelectedTable(state, dashboardId, tableName);
+                const queryTools = options.createQueryTools?.({ store });
+                const dashboardAgent = new ToolLoopAgent({
+                    model: options.getModel({ state }),
+                    tools: {
+                        ...(queryTools ? { query: queryTools.query } : {}),
+                        ...createDashboardAiTools({
+                            store,
+                            adapter,
+                            chartTypes: options.chartTypes,
+                            extraTools: options.extraTools,
+                        }),
+                    },
+                    temperature: Math.max(0, Math.min(1, temperature ?? 0.7)),
+                    stopWhen: [stepCountIs(Math.max(5, Math.min(50, maxSteps ?? 20)))],
+                    instructions: options.instructions ?? DASHBOARD_AGENT_INSTRUCTIONS,
+                });
+                const result = await options.runSubAgent({
+                    agent: dashboardAgent,
+                    prompt: buildAgentPrompt(prompt, tableName, state, adapter),
+                    store,
+                    parentToolCallId: toolOptions?.toolCallId || '',
+                    abortSignal: toolOptions?.abortSignal,
+                });
+                const finalState = store.getState();
+                const metadata = calculateAgentMetadata(finalState, adapter, dashboardId, tableName, result.agentToolCalls || []);
+                return {
+                    success: true,
+                    finalOutput: result.finalOutput || 'Dashboard created successfully.',
+                    dashboardId,
+                    metadata,
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const friendlyMessage = error instanceof DashboardAgentException
+                    ? errorMessage
+                    : 'Dashboard agent execution failed.';
+                return {
+                    success: false,
+                    finalOutput: friendlyMessage,
+                    dashboardId,
+                    error: errorMessage,
+                };
+            }
+        },
+    });
+}
+//# sourceMappingURL=ai.js.map