@larkup/workspace-server 0.0.0-stage → 0.2.0

package/src/lib/chat/tabular-dataset-routing.ts

@@ -0,0 +1,93 @@
+import type { TabularDatasetMeta } from '@larkup/core/tabular-store';
+
+function normalized(value: string) {
+  return value
+    .toLocaleLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim();
+}
+
+function hasColumnMention(text: string, column: string) {
+  const query = normalized(text);
+  const name = normalized(column);
+  if (!query || !name) return false;
+  if (query.includes(name)) return true;
+
+  const words = name.split(' ').filter(Boolean);
+  return (
+    words.length === 1 && words[0].length >= 4 && new RegExp(`\\b${words[0]}\\b`, 'iu').test(query)
+  );
+}
+
+function isTemporalRequest(text: string) {
+  return /\b(?:month(?:ly)?|quarter(?:ly)?|year(?:ly)?|trend|time\s+series|over\s+time)\b/iu.test(
+    text,
+  );
+}
+
+function namesRequestedInText(text: string, dataset: TabularDatasetMeta) {
+  return dataset.columns.filter((column) => hasColumnMention(text, column.name));
+}
+
+function distinctiveFileNameScore(text: string, fileName: string) {
+  const query = normalized(text);
+  const fileTerms = normalized(fileName)
+    .split(' ')
+    .filter(
+      (term) => term.length >= 7 && !['sample', 'returns', 'orders', 'people'].includes(term),
+    );
+  return fileTerms.some((term) => new RegExp(`\\b${term}\\b`, 'iu').test(query)) ? 8 : 0;
+}
+
+function scoreDataset(text: string, dataset: TabularDatasetMeta) {
+  let score = distinctiveFileNameScore(text, dataset.fileName);
+  const temporal = isTemporalRequest(text);
+  for (const column of namesRequestedInText(text, dataset)) {
+    if (column.type === 'number') score += 6;
+    else if (column.type === 'date' && temporal) score += 2;
+    else if (/\bby\b/iu.test(text)) score += 3;
+  }
+  return score;
+}
+
+/**
+ * Find one unambiguous dataset for code analysis when a model omitted the
+ * optional datasetId. This is intentionally schema-led: a matching filename
+ * alone is not enough to stage a potentially large source in the sandbox.
+ */
+export function selectTabularDatasetForQuestion(
+  text: string | undefined,
+  datasets: TabularDatasetMeta[],
+) {
+  if (datasets.length === 1) return datasets[0]?.id;
+  if (!text) return undefined;
+
+  const candidates = datasets
+    .map((dataset) => ({ dataset, score: scoreDataset(text, dataset) }))
+    .sort((left, right) => right.score - left.score);
+  const best = candidates[0];
+  const next = candidates[1];
+  if (!best || best.score < 6 || best.score === next?.score) return undefined;
+  return best.dataset.id;
+}
+
+/**
+ * Correct a model-selected sheet only when the question's schema makes a
+ * different dataset objectively better. This keeps workbook selection
+ * generic while avoiding a filename such as "sales.xlsx" winning over a
+ * sheet that actually contains both Sales and Profit.
+ */
+export function resolveTabularDatasetForQuestion(
+  text: string | undefined,
+  datasets: TabularDatasetMeta[],
+  selectedDatasetId: string,
+) {
+  const selected = datasets.find((dataset) => dataset.id === selectedDatasetId);
+  if (!text || !selected || datasets.length < 2) return selectedDatasetId;
+
+  const selectedScore = scoreDataset(text, selected);
+  const resolved = selectTabularDatasetForQuestion(text, datasets);
+  if (!resolved || resolved === selectedDatasetId) return selectedDatasetId;
+  const best = datasets.find((dataset) => dataset.id === resolved);
+  return best && scoreDataset(text, best) > selectedScore ? best.id : selectedDatasetId;
+}

package/src/lib/chat/tabular-query-plan.ts

@@ -0,0 +1,195 @@
+import type { TabularDataset, TabularQueryRequest } from '@larkup/core/tabular-store';
+
+export type InferredTabularPlan = {
+  request: TabularQueryRequest;
+  chartTitle?: string;
+};
+
+function numericColumns(dataset: TabularDataset): string[] {
+  return dataset.columns.filter((column) => column.type === 'number').map((column) => column.name);
+}
+
+function normalized(value: string) {
+  return value
+    .toLocaleLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim();
+}
+
+function columnMentioned(text: string, column: string) {
+  const query = normalized(text);
+  const name = normalized(column);
+  if (!query || !name) return false;
+  if (query.includes(name)) return true;
+  const words = name.split(' ').filter(Boolean);
+  return (
+    words.length === 1 && words[0].length >= 4 && new RegExp(`\\b${words[0]}\\b`, 'iu').test(query)
+  );
+}
+
+function explicitNumericMeasures(
+  text: string,
+  dataset: TabularDataset,
+  request: TabularQueryRequest,
+) {
+  const numeric = numericColumns(dataset);
+  const requested = (request.aggregations ?? [])
+    .map((aggregation) => aggregation.column)
+    .filter((column) => numeric.includes(column));
+  const mentioned = numeric.filter((column) => columnMentioned(text, column));
+  return [...new Set([...requested, ...mentioned])];
+}
+
+function columnPattern(column: string) {
+  return normalized(column)
+    .split(' ')
+    .map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('[-_\\s]+');
+}
+
+function groupingColumn(text: string, dataset: TabularDataset) {
+  return dataset.columns.find(
+    (column) =>
+      column.type !== 'number' &&
+      new RegExp(`\\bby\\s+(?:the\\s+)?${columnPattern(column.name)}\\b`, 'iu').test(text),
+  )?.name;
+}
+
+function requestedOperation(
+  measure: string,
+  request: TabularQueryRequest,
+  text: string,
+): NonNullable<TabularQueryRequest['aggregations']>[number]['op'] {
+  const supplied = request.aggregations?.find((aggregation) => aggregation.column === measure)?.op;
+  if (supplied) return supplied;
+  if (/\b(?:average|avg|mean)\b/iu.test(text)) return 'avg';
+  if (/\bmedian\b/iu.test(text)) return 'median';
+  // “Lowest to highest” and “highest month” usually describe ordering or a
+  // later comparison of grouped totals, not a request for the minimum raw
+  // order-level value. Reserve min/max for an explicit aggregate operation.
+  if (/\b(?:minimum|min)\b/iu.test(text)) return 'min';
+  if (/\b(?:maximum|max)\b/iu.test(text)) return 'max';
+  return 'sum';
+}
+
+function requestedSortOrder(text: string) {
+  if (/\b(?:lowest\s+to\s+highest|ascending|asc)\b/iu.test(text)) return 'asc' as const;
+  if (/\b(?:highest\s+to\s+lowest|descending|desc)\b/iu.test(text)) return 'desc' as const;
+  return undefined;
+}
+
+function normalizeAggregations(
+  dataset: TabularDataset,
+  request: TabularQueryRequest,
+): TabularQueryRequest {
+  if (!request.aggregations?.length) return request;
+  const numeric = numericColumns(dataset);
+  const isCount = (aggregation: NonNullable<TabularQueryRequest['aggregations']>[number]) =>
+    aggregation.op === 'count' || aggregation.op === 'countDistinct';
+  const valid = request.aggregations.filter(
+    (aggregation) => isCount(aggregation) || numeric.includes(aggregation.column),
+  );
+  if (valid.length === request.aggregations.length || numeric.length !== 1) return request;
+
+  // The model may select a text label such as a representative/name as a
+  // measure. A dataset with exactly one numeric field has an unambiguous,
+  // schema-derived correction; otherwise leave the request unchanged.
+  return {
+    ...request,
+    aggregations: request.aggregations.map((aggregation) =>
+      isCount(aggregation) ? aggregation : { ...aggregation, column: numeric[0] },
+    ),
+  };
+}
+
+function normalizeDistinctCountIntent(
+  text: string,
+  request: TabularQueryRequest,
+): TabularQueryRequest {
+  if (!/\b(?:unique|distinct)\b/i.test(text) || !request.aggregations?.length) return request;
+
+  return {
+    ...request,
+    aggregations: request.aggregations.map((aggregation) =>
+      aggregation.op === 'count' ? { ...aggregation, op: 'countDistinct' } : aggregation,
+    ),
+  };
+}
+
+/**
+ * Normalize a clear calendar request from the dataset schema. It never
+ * assumes business columns or domain names: a time series is derived only
+ * when there is one date column and one numeric measure.
+ */
+export function inferTabularPlan(
+  requestText: string | undefined,
+  dataset: TabularDataset,
+  request: TabularQueryRequest,
+): InferredTabularPlan {
+  const text = requestText?.toLocaleLowerCase() ?? '';
+  const dateColumn = dataset.columns.find((column) => column.type === 'date')?.name;
+  const numeric = numericColumns(dataset);
+  const requestedMeasures = explicitNumericMeasures(text, dataset, request);
+  const measureColumns =
+    requestedMeasures.length > 0 ? requestedMeasures : numeric.length === 1 ? [numeric[0]] : [];
+  const year = text.match(/\b(20\d{2})\b/)?.[1];
+
+  if (
+    dateColumn &&
+    measureColumns.length > 0 &&
+    /\b(?:monthly|per month|month(?:ly)? trend)\b/i.test(text)
+  ) {
+    const bucketColumn = `${dateColumn}_month`;
+    const filters = (request.filters ?? []).filter((filter) => filter.column !== dateColumn);
+    if (year) {
+      filters.push({ column: dateColumn, op: 'gte', value: `${year}-01-01` });
+      filters.push({ column: dateColumn, op: 'lt', value: `${Number(year) + 1}-01-01` });
+    }
+    return {
+      request: {
+        ...request,
+        // A model may also send the source column names. Once rows are
+        // grouped those names no longer exist (for example, Revenue becomes
+        // sum_Revenue), so retaining the projection would turn every result
+        // row into an empty object.
+        columns: undefined,
+        filters,
+        timeBucket: { column: dateColumn, grain: 'month' },
+        groupBy: [bucketColumn],
+        aggregations: measureColumns.map((column) => ({
+          column,
+          op: requestedOperation(column, request, text),
+        })),
+        sortBy: bucketColumn,
+        sortOrder: 'asc',
+        limit: 120,
+      },
+      chartTitle: `Monthly ${measureColumns.join(' and ')} trend${year ? ` for ${year}` : ''}`,
+    };
+  }
+
+  const groupBy = groupingColumn(text, dataset);
+  if (groupBy && requestedMeasures.length > 0) {
+    const aggregations = requestedMeasures.map((column) => ({
+      column,
+      op: requestedOperation(column, request, text),
+    }));
+    const sortOrder = requestedSortOrder(text);
+    return {
+      request: {
+        ...request,
+        columns: undefined,
+        groupBy: [groupBy],
+        aggregations,
+        ...(sortOrder
+          ? { sortBy: `${aggregations[0].op}_${aggregations[0].column}`, sortOrder }
+          : {}),
+        limit: Math.min(request.limit ?? 120, 120),
+      },
+    };
+  }
+
+  return {
+    request: normalizeDistinctCountIntent(text, normalizeAggregations(dataset, request)),
+  };
+}

package/src/lib/chat/tabular-routing.ts

@@ -0,0 +1,122 @@
+/**
+ * Route ordinary sheet questions through the structured query engine, while
+ * sending explicit joins and advanced analytics to the sandbox. This keeps
+ * common Excel/CSV questions independent from local Python availability.
+ */
+export function tabularToolsForStep(input: {
+  stepNumber: number;
+  toolNames: string[];
+  requiresSandbox?: boolean;
+}) {
+  if (input.stepNumber === 0) {
+    if (input.requiresSandbox && input.toolNames.includes('executeAnalysis')) {
+      return {
+        toolChoice: { type: 'tool' as const, toolName: 'executeAnalysis' },
+        activeTools: ['executeAnalysis'],
+      };
+    }
+    return {
+      toolChoice: { type: 'tool' as const, toolName: 'queryTabularData' },
+      activeTools: ['queryTabularData'],
+    };
+  }
+  if (input.stepNumber === 1) {
+    // The first evidence tool has already returned authoritative rows (and,
+    // for chart requests, queryTabularData has attached a normalized chart).
+    // Re-exposing presentation and analysis tools here lets some models emit
+    // a second, empty chart call or repeat the analysis instead of answering.
+    return { toolChoice: 'none' as const, activeTools: [] };
+  }
+  return { toolChoice: 'none' as const, activeTools: [] };
+}
+
+/** Stop once the host has attached a renderable chart to authoritative rows. */
+export function hasCompletedTabularVisualizationStep(
+  steps: Array<{
+    toolResults?: readonly unknown[];
+  }>,
+) {
+  const lastStep = steps.at(-1);
+  return Boolean(
+    lastStep?.toolResults?.some((result) => {
+      if (!result || typeof result !== 'object' || !('toolName' in result)) return false;
+      if ((result as { toolName?: unknown }).toolName !== 'queryTabularData') return false;
+      const output = (result as { output?: unknown }).output;
+      return Boolean(
+        output &&
+        typeof output === 'object' &&
+        'visualization' in output &&
+        (output as { visualization?: unknown }).visualization,
+      );
+    }),
+  );
+}
+
+/**
+ * Identify requests whose answer requires an out-of-core calculation rather
+ * than a single structured table query. This is phrased around analytical
+ * operations, so it works for any workbook and does not depend on sheet or
+ * column names.
+ */
+export function requiresTabularSandbox(text: string): boolean {
+  return /\b(?:join|correlat(?:e|ion)|regression|cluster(?:ing)?|forecast(?:ing)?|statistical|sandbox|python|matplotlib|seaborn|scikit(?:-learn)?|custom\s+(?:analysis|chart|visuali[sz]ation)|across\s+(?:sheets?|tables?|datasets?|files?)|between\s+(?:sheets?|tables?|datasets?|files?))\b/i.test(
+    text,
+  );
+}
+
+/**
+ * A workspace can contain spreadsheets alongside PDFs, media, and notes.
+ * Only force the table path when the wording actually asks for tabular facts;
+ * otherwise normal source retrieval remains free to select the right modality.
+ */
+export function isLikelyTabularQuestion(input: {
+  text: string;
+  columnNames: string[];
+  datasetNames: string[];
+}) {
+  const text = input.text.trim().toLocaleLowerCase();
+  if (!text) return false;
+  if (
+    /\b(?:spreadsheet|excel|csv|worksheet|sheet|dataset|row|column|filter|sort|group(?:ed|ing)?|aggregate|average|median|total|sum|count|highest|lowest|largest|smallest|maximum|minimum|trend|distribution)\b/.test(
+      text,
+    ) ||
+    /\b(?:arithmetic|geometric|weighted)\s+mean\b|\bmean\s+(?:of|for|by)\b/.test(text)
+  ) {
+    return true;
+  }
+
+  // “Put it in a table” describes the requested answer format, not the
+  // source modality. Treat table as tabular only when the surrounding words
+  // make a data table explicit, so a media or document question can still
+  // retrieve its own source in a mixed workspace.
+  if (
+    /\b(?:data|database|pivot|lookup)\s+table\b|\btable\s+(?:data|rows?|columns?|schema|lookup)\b/.test(
+      text,
+    )
+  ) {
+    return true;
+  }
+
+  const mentionsDataset = input.datasetNames.some((name) => {
+    const stem = name
+      .replace(/\.(?:csv|xlsx|xls|json)$/i, '')
+      .trim()
+      .toLocaleLowerCase();
+    return stem.length >= 3 && text.includes(stem);
+  });
+  if (mentionsDataset) return true;
+
+  return input.columnNames.some((column) => {
+    const normalized = column.trim().toLocaleLowerCase();
+    if (normalized.length >= 4 && text.includes(normalized)) return true;
+    const terms = normalized.match(/[\p{L}\p{N}_]+/gu) ?? [];
+    const matchedTerms = terms.filter((term) => term.length >= 4 && text.includes(term));
+    if (matchedTerms.length >= 2) return true;
+
+    // Metrics in real workbooks often have long headers while the user asks
+    // with one distinctive word. A sufficiently specific header token is
+    // enough to choose the exact table tool without relying on dataset- or
+    // domain-specific routing rules.
+    return matchedTerms.some((term) => term.length >= 6);
+  });
+}

package/src/lib/chat/tabular-sandbox-files.ts

@@ -0,0 +1,78 @@
+import type { TabularDataset } from '@larkup/core/tabular-store';
+
+export type TabularSandboxFile = { name: string; content: string };
+
+export type TabularSandboxManifest = {
+  datasets: Array<{
+    id: string;
+    fileName: string;
+    file: string;
+    rowCount: number;
+    columns: string[];
+  }>;
+};
+
+function csvCell(value: unknown) {
+  const text = String(value ?? '');
+  return text.includes(',') || text.includes('"') || text.includes('\n')
+    ? `"${text.replace(/"/g, '""')}"`
+    : text;
+}
+
+/** Serialize a stored dataset with RFC 4180-compatible quoting for sandbox analysis. */
+export function tabularDatasetToCsv(dataset: TabularDataset) {
+  const columns = dataset.columns.map((column) => column.name);
+  return [
+    columns.join(','),
+    ...dataset.rows.map((row) => columns.map((column) => csvCell(row[column])).join(',')),
+  ].join('\n');
+}
+
+/**
+ * Stage one or more selected datasets for a sandbox without exposing row data
+ * to the chat model. A single dataset keeps the long-standing `data.csv`
+ * contract; multiple datasets receive stable generic filenames plus a manifest
+ * that maps each source ID and sheet name to its CSV file.
+ */
+export function createTabularSandboxFiles(datasets: TabularDataset[]): {
+  files: TabularSandboxFile[];
+  manifest?: TabularSandboxManifest;
+} {
+  if (datasets.length === 0) return { files: [] };
+
+  const multiple = datasets.length > 1;
+  const manifest: TabularSandboxManifest = { datasets: [] };
+  const files = datasets.map((dataset, index) => {
+    const name = multiple ? `dataset-${index + 1}.csv` : 'data.csv';
+    manifest.datasets.push({
+      id: dataset.id,
+      fileName: dataset.fileName,
+      file: name,
+      rowCount: dataset.rowCount,
+      columns: dataset.columns.map((column) => column.name),
+    });
+    return { name, content: tabularDatasetToCsv(dataset) };
+  });
+
+  if (multiple) {
+    files.push({ name: 'datasets.json', content: JSON.stringify(manifest, null, 2) });
+    return { files, manifest };
+  }
+
+  return { files };
+}
+
+/**
+ * Recover a common single-sheet code pattern when every selected dataset was
+ * requested but the generated code still reads `data.csv`. Rewriting is safe
+ * only when the number of reads exactly matches the selected datasets.
+ */
+export function remapLegacyMultiDatasetReads(code: string, datasetCount: number): string {
+  if (datasetCount < 2) return code;
+
+  const legacyRead = /pd\s*\.\s*read_(?:csv|excel)\(\s*(['"])data\.csv\1(?:\s*,[^)]*)?\s*\)/g;
+  if ([...code.matchAll(legacyRead)].length !== datasetCount) return code;
+
+  let datasetIndex = 0;
+  return code.replace(legacyRead, () => `pd.read_csv('dataset-${++datasetIndex}.csv')`);
+}

package/src/lib/chat/tabular-visualization.ts

@@ -0,0 +1,165 @@
+import { formatChartLabel, normalizeChartConfig, numericValue } from '@larkup/core/chart-config';
+
+export type TabularChartConfig = {
+  chartType: 'bar' | 'line';
+  title: string;
+  data: Record<string, unknown>[];
+  xAxisKey: string;
+  series: { dataKey: string; label: string }[];
+  showLegend: boolean;
+  xAxisLabel?: string;
+  yAxisLabel?: string;
+};
+
+type TabularVisualizationResult = {
+  visualization?: TabularChartConfig;
+  error?: unknown;
+};
+
+function formatChartCategory(value: string) {
+  const calendarMonth = value.match(/^(\d{4})-(\d{2})$/);
+  if (calendarMonth) {
+    return new Intl.DateTimeFormat('en-US', {
+      month: 'short',
+      year: 'numeric',
+      timeZone: 'UTC',
+    }).format(new Date(Date.UTC(Number(calendarMonth[1]), Number(calendarMonth[2]) - 1, 1)));
+  }
+  return formatChartLabel(value);
+}
+
+function formatSeriesLabel(value: string) {
+  return formatChartLabel(
+    value.replace(/^(?:sum|avg|countDistinct|count|min|max|median)[_\s-]+/i, ''),
+  );
+}
+
+export function requestsVisualization(text: string): boolean {
+  return /\b(chart|graph|plot|visuali[sz]e|distribution|breakdown|trends?|compare|show\s+me)\b/i.test(
+    text,
+  );
+}
+
+function normalizedTerms(value: string) {
+  return value.toLocaleLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+
+function columnIsMentioned(text: string, column: string) {
+  const requestTerms = new Set(normalizedTerms(text));
+  const columnTerms = normalizedTerms(column).filter((term) => term.length >= 3);
+  return columnTerms.some((term) => requestTerms.has(term));
+}
+
+function hasNumericValues(rows: Record<string, unknown>[], column: string) {
+  return rows.some((row) => numericValue(row[column]) !== undefined);
+}
+
+function hasVaryingValues(rows: Record<string, unknown>[], column: string) {
+  const values = new Set(
+    rows
+      .map((row) => row[column])
+      .filter((value) => value !== null && value !== undefined && String(value).trim())
+      .map((value) => String(value)),
+  );
+  return values.size > 1;
+}
+
+function isTemporalColumn(column: string, rows: Record<string, unknown>[]) {
+  if (/\b(?:year|date|month|quarter|week|day|time)\b/i.test(formatChartLabel(column))) return true;
+  return rows.some((row) => /^(?:19|20)\d{2}$/.test(String(row[column] ?? '').trim()));
+}
+
+/** Build a chart only from an already-queried, bounded tabular result. */
+export function createTabularVisualization(
+  requestText: string | undefined,
+  result: { columns: string[]; rows: Record<string, unknown>[] },
+): TabularChartConfig | undefined {
+  if (!requestText || !requestsVisualization(requestText) || result.rows.length === 0) {
+    return undefined;
+  }
+
+  const wantsTimeSeries =
+    /\b(?:line(?:\s+\w+){0,2}\s+chart|trends?|over time|time series|year[ -]to[ -]year|available years?|monthly|quarterly|annually)\b/i.test(
+      requestText,
+    );
+  const numericColumns = result.columns.filter((column) => hasNumericValues(result.rows, column));
+  const temporalColumn = wantsTimeSeries
+    ? result.columns.find(
+        (column) => isTemporalColumn(column, result.rows) && hasVaryingValues(result.rows, column),
+      )
+    : undefined;
+  const categoryColumn = result.columns.find(
+    (column) =>
+      !numericColumns.includes(column) &&
+      hasVaryingValues(result.rows, column) &&
+      !/^_*empty(?:[_-]?\d+)?$/i.test(column.trim()),
+  );
+  const xAxisKey = temporalColumn ?? categoryColumn ?? result.columns[0] ?? '';
+  const seriesCandidates = numericColumns.filter((column) => column !== xAxisKey);
+  const mentionedSeries = seriesCandidates.filter((column) =>
+    columnIsMentioned(requestText, column),
+  );
+  const seriesColumns = (mentionedSeries.length > 0 ? mentionedSeries : seriesCandidates).slice(
+    0,
+    3,
+  );
+  const chartType = wantsTimeSeries ? 'line' : 'bar';
+
+  const candidate = normalizeChartConfig({
+    chartType,
+    title: 'Data chart',
+    data: result.rows.slice(0, 50),
+    xAxisKey,
+    series: seriesColumns.map((column) => ({ dataKey: column, label: column })),
+  });
+  if (candidate.error) return undefined;
+
+  return {
+    ...candidate,
+    chartType: candidate.chartType as 'bar' | 'line',
+    title: `${chartType === 'line' ? 'Trend' : 'Distribution'} by ${formatChartLabel(candidate.xAxisKey)}`,
+    series: candidate.series.map((series) => ({
+      ...series,
+      label:
+        !series.label || series.label === series.dataKey
+          ? formatSeriesLabel(series.dataKey)
+          : series.label,
+    })),
+    showLegend: candidate.showLegend ?? candidate.series.length > 1,
+  };
+}
+
+/**
+ * Keep the prose beside a rendered chart compact and deterministic. The chart
+ * already exposes every plotted row, so echoing those rows as assistant text
+ * is both noisy and a common source of provider-specific output failures.
+ */
+export function formatTabularVisualizationAnswer(result: TabularVisualizationResult): string {
+  const chart = result.visualization;
+  if (!chart) {
+    return typeof result.error === 'string' && result.error.trim()
+      ? `I couldn’t create the requested chart: ${result.error.trim()}`
+      : 'I couldn’t create a chart from the available tabular result.';
+  }
+
+  const insights = chart.series.flatMap((series) => {
+    const points = chart.data.flatMap((row) => {
+      const value = numericValue(row[series.dataKey]);
+      const category = row[chart.xAxisKey];
+      return value === undefined || category === undefined || category === null
+        ? []
+        : [{ value, category: String(category) }];
+    });
+    if (points.length < 2) return [];
+    const peak = points.reduce((best, point) => (point.value > best.value ? point : best));
+    return `${series.label || formatSeriesLabel(series.dataKey)} peaks at ${new Intl.NumberFormat(
+      'en-US',
+      { maximumFractionDigits: 2 },
+    ).format(peak.value)} in ${formatChartCategory(peak.category)}`;
+  });
+
+  const introduction = chart.title?.trim()
+    ? `Here’s the requested chart: ${chart.title.trim()}.`
+    : 'Here’s the requested chart.';
+  return insights.length > 0 ? `${introduction} ${insights.join('; ')}.` : introduction;
+}