@outsidedata/dolex 0.1.0

package/src/mcp/tools/visualize.ts

@@ -0,0 +1,229 @@
+/**
+ * MCP Tool: visualize
+ * Takes inline data + intent and returns visualization recommendations
+ * from the handcrafted pattern library.
+ *
+ * For source-based data (sourceId + table + query), use visualize_from_source.
+ *
+ * Returns compact text content (specId + metadata, no data) while
+ * structuredContent still gets the full pre-rendered chart HTML.
+ */
+
+import { z } from 'zod';
+import type { VisualizeInput, VisualizeOutput, DataColumn, VisualizationSpec } from '../../types.js';
+import { isCompoundSpec } from '../../types.js';
+import { buildChartHtml, isHtmlPatternSupported } from '../../renderers/html/index.js';
+import { shouldCompound, buildCompoundSpec } from '../../renderers/html/compound.js';
+import { buildCompoundHtml } from '../../renderers/html/builders/compound.js';
+import { specStore } from '../spec-store.js';
+import { getResult } from './result-cache.js';
+import { errorResponse, inferColumns, applyColorPreferences } from './shared.js';
+import { logOperation } from './operation-log.js';
+import type { OperationMeta } from './operation-log.js';
+
+const ALL_PALETTE_NAMES = [
+  'categorical', 'blue', 'green', 'purple', 'warm',
+  'blueRed', 'greenPurple', 'tealOrange', 'redGreen',
+  'traffic-light', 'profit-loss', 'temperature',
+] as const;
+
+export const colorPreferencesSchema = z.object({
+  palette: z.enum(ALL_PALETTE_NAMES).optional().describe('Named palette: categorical, blue, green, purple, warm, blueRed, greenPurple, tealOrange, redGreen, traffic-light, profit-loss, temperature'),
+  highlight: z.object({
+    values: z.array(z.any()).describe('Values to emphasize — all others become muted gray'),
+    color: z.union([z.string(), z.array(z.string())]).optional().describe('Color(s) for highlighted values. Single CSS color or array matching values length.'),
+    mutedColor: z.string().optional().describe('Color for non-highlighted items (default: #6b7280)'),
+    mutedOpacity: z.number().optional().describe('Opacity for muted items (default: 1.0, lower for stronger de-emphasis)'),
+  }).optional(),
+  colorField: z.string().optional().describe('Which data field to base colors on'),
+}).optional().describe('Color preferences applied to the visualization');
+
+export const columnsSchema = z.array(z.object({
+  name: z.string(),
+  type: z.enum(['numeric', 'categorical', 'date', 'id', 'text']),
+  sampleValues: z.array(z.string()).optional(),
+  uniqueCount: z.number().optional(),
+  nullCount: z.number().optional(),
+  totalCount: z.number().optional(),
+})).optional().describe('Column metadata — if not provided, will be inferred from data');
+
+export const dataShapeHintsSchema = z.object({
+  rowCount: z.number().optional(),
+  categoryCount: z.number().optional(),
+  seriesCount: z.number().optional(),
+  numericColumnCount: z.number().optional(),
+  categoricalColumnCount: z.number().optional(),
+  dateColumnCount: z.number().optional(),
+  hasTimeSeries: z.boolean().optional(),
+  hasHierarchy: z.boolean().optional(),
+  hasNegativeValues: z.boolean().optional(),
+}).optional().describe('Hints about the data shape to help pattern selection');
+
+export const visualizeInputSchema = z.object({
+  data: z.array(z.record(z.any())).optional().describe('Array of data rows to visualize. Optional if resultId is provided.'),
+  resultId: z.string().optional().describe('Result ID from a previous query_source call — reuses cached data without re-sending it'),
+  intent: z.string().describe('What the user wants to see — e.g., "compare sales by region", "show distribution of ages", "how do rankings change over time"'),
+  columns: columnsSchema,
+  dataShapeHints: dataShapeHintsSchema,
+  pattern: z.string().optional().describe('Force a specific chart pattern by ID (e.g. "bar", "beeswarm", "stream-graph"). Use list_patterns to discover IDs. Bypasses scoring; alternatives still returned.'),
+  title: z.string().optional().describe('Chart title — set upfront to avoid a refine round-trip'),
+  subtitle: z.string().optional().describe('Chart subtitle — set upfront to avoid a refine round-trip'),
+  includeDataTable: z.boolean().optional().describe('Whether to add a companion sortable data table with linked highlighting below the chart. Default: true'),
+  colorPreferences: colorPreferencesSchema,
+  maxAlternativeChartTypes: z.number().optional().describe('Max alternative chart type recommendations to return (default: 2, set 0 for none)'),
+  geoLevel: z.enum(['country', 'subdivision']).optional()
+    .describe('Geographic level: "country" (each row = a nation) or "subdivision" (each row = a state/province). Auto-detected if omitted.'),
+  geoRegion: z.string().optional()
+    .describe('Geographic region code: "world", ISO country code (US, CN, AU, etc.), or continent (EU, AF, AS, SA, NA, OC). Auto-detected if omitted.'),
+});
+
+/**
+ * Shared core logic for both visualize and visualize_from_source.
+ * Takes resolved data + args and returns the MCP response.
+ */
+export function handleVisualizeCore(
+  selectPatterns: (input: VisualizeInput) => VisualizeOutput,
+  toolName: string = 'visualize',
+) {
+  return (data: Record<string, any>[], args: {
+    intent: string;
+    columns?: z.infer<typeof columnsSchema>;
+    dataShapeHints?: z.infer<typeof dataShapeHintsSchema>;
+    pattern?: string;
+    title?: string;
+    subtitle?: string;
+    includeDataTable?: boolean;
+    colorPreferences?: z.infer<typeof colorPreferencesSchema>;
+    maxAlternativeChartTypes?: number;
+    geoLevel?: 'country' | 'subdivision';
+    geoRegion?: string;
+  }, queryMeta?: { truncated?: boolean; totalSourceRows?: number }, extraMeta?: Partial<OperationMeta>) => {
+    const start = Date.now();
+    const columns = (args.columns as DataColumn[]) || inferColumns(data);
+    const maxAlternativeChartTypes = args.maxAlternativeChartTypes ?? 2;
+
+    const input: VisualizeInput = {
+      data,
+      intent: args.intent,
+      columns,
+      dataShapeHints: args.dataShapeHints,
+      forcePattern: args.pattern,
+      geoLevel: args.geoLevel,
+      geoRegion: args.geoRegion,
+    };
+
+    const result = selectPatterns(input);
+
+    const alternatives = result.alternatives.slice(0, maxAlternativeChartTypes);
+
+    if (args.colorPreferences) {
+      applyColorPreferences(result.recommended.spec, args.colorPreferences);
+    }
+
+    const spec = result.recommended.spec;
+    if (args.title) spec.title = args.title;
+    if (args.subtitle) spec.config = { ...spec.config, subtitle: args.subtitle };
+    const hasHtmlBuilder = spec && isHtmlPatternSupported(spec.pattern);
+
+    let outputHtml: string | undefined;
+    let finalSpec: VisualizationSpec | import('../../types.js').CompoundVisualizationSpec = spec;
+    if (hasHtmlBuilder && shouldCompound(spec, { compound: args.includeDataTable })) {
+      const compoundSpec = buildCompoundSpec(spec, columns);
+      outputHtml = buildCompoundHtml(compoundSpec);
+      finalSpec = compoundSpec;
+    } else if (hasHtmlBuilder) {
+      outputHtml = buildChartHtml(spec);
+    }
+
+    const alternativesMap = new Map<string, VisualizationSpec>();
+    for (const alt of alternatives) {
+      alternativesMap.set(alt.pattern, alt.spec);
+    }
+    const specId = specStore.save(finalSpec, columns, alternativesMap);
+
+    const compactResponse: Record<string, any> = {
+      specId,
+      recommended: {
+        pattern: result.recommended.pattern,
+        title: spec.title,
+        reasoning: result.recommended.reasoning,
+      },
+      alternatives: alternatives.map(a => ({
+        pattern: a.pattern,
+        reasoning: a.reasoning,
+      })),
+      dataShape: {
+        rowCount: data.length,
+        columnCount: columns.length,
+        columns: columns.map(c => ({ name: c.name, type: c.type })),
+        ...(queryMeta?.truncated ? { truncated: true, totalSourceRows: queryMeta.totalSourceRows } : {}),
+      },
+    };
+
+    if (isCompoundSpec(finalSpec)) {
+      compactResponse.compound = true;
+    }
+
+    if (['choropleth', 'proportional-symbol'].includes(spec.pattern) && spec.config) {
+      compactResponse.geo = {
+        ...(spec.config.mapType ? { region: spec.config.mapType } : {}),
+        ...(spec.config.projection ? { projection: spec.config.projection } : {}),
+        ...(spec.config.objectName ? { mapFile: spec.config.objectName } : {}),
+      };
+    }
+
+    logOperation({
+      toolName,
+      timestamp: start,
+      durationMs: Date.now() - start,
+      success: true,
+      meta: {
+        pattern: result.recommended.pattern,
+        specId,
+        alternativesCount: alternatives.length,
+        dataShape: {
+          rowCount: data.length,
+          columnCount: columns.length,
+          columns: columns.map(c => ({ name: c.name, type: c.type })),
+        },
+        ...extraMeta,
+      },
+    });
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(compactResponse, null, 2),
+      }],
+      ...(outputHtml ? {
+        structuredContent: {
+          html: outputHtml,
+        },
+      } : {}),
+    };
+  };
+}
+
+export function handleVisualize(
+  selectPatterns: (input: VisualizeInput) => VisualizeOutput,
+) {
+  const core = handleVisualizeCore(selectPatterns);
+
+  return async (args: z.infer<typeof visualizeInputSchema>) => {
+    let data = args.data;
+
+    if (args.resultId) {
+      const cached = getResult(args.resultId);
+      if (!cached) {
+        return errorResponse(`Result "${args.resultId}" not found or expired. Re-run query_source to get a new resultId.`);
+      }
+      data = cached.rows;
+    }
+
+    if (!data || data.length === 0) {
+      return errorResponse('No data provided. Pass either `data` array or `resultId` from query_source.');
+    }
+
+    return core(data, args);
+  };
+}

package/src/patterns/definitions/comparison/bar.ts

@@ -0,0 +1,110 @@
+/**
+ * Standard Bar Chart — the baseline comparison pattern.
+ *
+ * This is the "default" that every other comparison pattern
+ * must beat. It works well for most categorical comparisons
+ * but is rarely the BEST choice.
+ */
+
+import type { VisualizationPattern, VisualizationSpec, DataColumn } from '../../../types.js';
+
+export const barPattern: VisualizationPattern = {
+  id: 'bar',
+  name: 'Bar Chart',
+  category: 'comparison',
+  description:
+    'Standard vertical bar chart for comparing values across categories. The reliable default for categorical comparison.',
+  bestFor: 'Simple categorical comparison with 3-15 categories and one value metric.',
+  notFor:
+    'Time series (use line), part-to-whole (use waffle/stacked), distribution (use histogram/beeswarm), rank changes (use bump chart).',
+
+  dataRequirements: {
+    minRows: 2,
+    maxRows: 50,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category axis' },
+      { type: 'numeric', count: 1, description: 'Value to compare' },
+    ],
+    minCategories: 2,
+    maxCategories: 25,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Default comparison: categories with one numeric value',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          !ctx.dataShape.hasTimeSeries
+        );
+      },
+    },
+    {
+      condition: 'Moderate category count (3-15)',
+      weight: 15,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount >= 3 && ctx.dataShape.categoryCount <= 15;
+      },
+    },
+    {
+      condition: 'Intent includes comparison keywords',
+      weight: 10,
+      matches: (ctx) => {
+        return /\b(compar|rank|top|bottom|highest|lowest|most|least|largest|smallest)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Penalize when better alternatives exist: two-point comparison',
+      weight: -20,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount === 2 && ctx.dataShape.categoryCount >= 3;
+      },
+    },
+    {
+      condition: 'Penalize for time series data',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const xCol = columns[0];
+    const yCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'bar',
+      title: options?.title ?? `${yCol} by ${xCol}`,
+      data,
+      encoding: {
+        x: {
+          field: xCol,
+          type: 'nominal',
+          title: xCol,
+          sort: 'descending',
+        },
+        y: {
+          field: yCol,
+          type: 'quantitative',
+          title: yCol,
+        },
+        color: {
+          field: xCol,
+          type: 'nominal',
+          scale: {},
+        },
+      },
+      config: {
+        orientation: options?.horizontal ? 'horizontal' : 'vertical',
+        sortBy: options?.sortBy ?? 'value',
+        sortOrder: options?.sortOrder ?? 'descending',
+        showLabels: options?.showLabels ?? (data.length <= 12),
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/bullet.ts

@@ -0,0 +1,136 @@
+/**
+ * Bullet Chart — compact horizontal bar with target marker and qualitative range bands.
+ *
+ * The bullet chart replaces dashboard gauges and meters with a compact,
+ * information-dense display. Shows a primary measure (actual) against a
+ * comparative measure (target) with qualitative ranges providing context
+ * (poor / satisfactory / good).
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const bulletPattern: VisualizationPattern = {
+  id: 'bullet',
+  name: 'Bullet Chart',
+  category: 'comparison',
+  description:
+    'Compact horizontal bar showing a primary measure against a target with qualitative range bands (poor/satisfactory/good). Stephen Few\'s replacement for gauges and meters.',
+  bestFor:
+    'Dashboard KPI tracking with context: actual vs target vs qualitative assessment. Revenue vs quota, CPU usage vs threshold, NPS score vs benchmark.',
+  notFor:
+    'Many categories without targets (use bar chart), composition or part-to-whole (use stacked bar or donut), time series (use line or sparkline).',
+
+  dataRequirements: {
+    minRows: 1,
+    maxRows: 12,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Metric name (label for each bullet)' },
+      { type: 'numeric', count: 2, description: 'Actual value and target value (plus optional range thresholds)' },
+    ],
+    minCategories: 1,
+    maxCategories: 12,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions bullet chart',
+      weight: 90,
+      matches: (ctx) => {
+        return /\b(bullet\s*chart|bullet)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Intent mentions actual vs target, KPI tracking, or performance against benchmark',
+      weight: 70,
+      matches: (ctx) => {
+        return /\b(vs\.?\s*target|versus\s*target|actual\s*vs|against\s*(target|benchmark|quota|threshold|goal)|kpi\s*(track|dashboard|monitor)|performance\s*(vs|against|to)\s*(target|benchmark|quota))\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Data has target-like columns — suggests actual vs target comparison',
+      weight: 55,
+      matches: (ctx) => {
+        const colNames = ctx.columns.map((c) => c.name.toLowerCase());
+        const hasActual = colNames.some((n) => /\b(actual|current|value|score|result)\b/.test(n));
+        const hasTarget = colNames.some((n) => /\b(target|goal|benchmark|quota|threshold|budget)\b/.test(n));
+        return hasActual && hasTarget;
+      },
+    },
+    {
+      condition: 'Few metrics with multiple numeric columns — good bullet chart candidate',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.rowCount >= 1 &&
+          ctx.dataShape.rowCount <= 8 &&
+          ctx.dataShape.numericColumnCount >= 2 &&
+          ctx.dataShape.categoricalColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Penalize for time series data — use line or sparkline instead',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize for too many rows — bullet charts are for few KPIs',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount > 12;
+      },
+    },
+    {
+      condition: 'Penalize when only one numeric column — need at least actual and target',
+      weight: -50,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount < 2;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const numericCols = columns.filter((col) => {
+      const sample = data[0]?.[col];
+      return sample !== undefined && !isNaN(Number(sample));
+    });
+
+    const actualCol = options?.actualField ?? numericCols[0] ?? columns[1];
+    const targetCol = options?.targetField ?? numericCols[1] ?? columns[2];
+    const rangeFields = options?.rangeFields ?? numericCols.slice(2);
+
+    const spec: VisualizationSpec = {
+      pattern: 'bullet',
+      title: options?.title ?? 'Performance vs Target',
+      data,
+      encoding: {
+        x: {
+          field: actualCol,
+          type: 'quantitative',
+          title: actualCol,
+        },
+        color: {
+          field: categoryCol,
+          type: 'nominal',
+        },
+      },
+      config: {
+        metricField: categoryCol,
+        actualField: actualCol,
+        targetField: targetCol,
+        rangeFields: rangeFields.length > 0 ? rangeFields : undefined,
+        sortBy: options?.sortBy ?? 'value',
+        sortOrder: options?.sortOrder ?? 'descending',
+        rangeLabels: options?.rangeLabels,
+        showLabels: options?.showLabels ?? true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/bump-chart.ts

@@ -0,0 +1,143 @@
+/**
+ * Bump Chart — rank changes over time.
+ *
+ * Shows how the relative positions of entities change across
+ * ordered categories (usually time). Unlike line charts that show
+ * absolute values, bump charts show relative ranking, making it
+ * easy to spot who rose and who fell.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const bumpChartPattern: VisualizationPattern = {
+  id: 'bump-chart',
+  name: 'Bump Chart',
+  category: 'comparison',
+  description:
+    'Tracks rank positions of entities over time or ordered categories. Lines connect rankings, and crossings show when one entity overtakes another.',
+  bestFor:
+    'Ranking changes: team standings over seasons, product market share rank, country GDP ranking over decades, leaderboard progression.',
+  notFor:
+    'Absolute values (use line chart), single time point (use bar), too many entities (>12 gets unreadable), non-ordinal x-axis.',
+
+  dataRequirements: {
+    minRows: 6,
+    maxRows: 200,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Entity being ranked (team, country, etc.)' },
+      { type: 'numeric', count: 1, description: 'Value used to compute rankings' },
+    ],
+    minCategories: 3,
+    maxCategories: 12,
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions rank, ranking, position, or standings',
+      weight: 90,
+      matches: (ctx) => {
+        return /\b(rank|ranking|position|standing|leaderboard|leader|place|moved up|moved down|overtake|overtook)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Time series data with multiple categories (series) — potential for bump chart',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.seriesCount >= 3 &&
+          ctx.dataShape.seriesCount <= 12 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Moderate number of entities and time points — sweet spot for bump charts',
+      weight: 20,
+      matches: (ctx) => {
+        const dateCols = ctx.columns.filter((c) => c.type === 'date');
+        const timePoints = dateCols.length > 0 ? dateCols[0].uniqueCount : 0;
+        return (
+          ctx.dataShape.seriesCount >= 3 &&
+          ctx.dataShape.seriesCount <= 12 &&
+          timePoints >= 3 &&
+          timePoints <= 20
+        );
+      },
+    },
+    {
+      condition: 'Penalize when no time dimension exists',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries && ctx.dataShape.dateColumnCount === 0;
+      },
+    },
+    {
+      condition: 'Penalize for too many entities — becomes unreadable',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount > 12;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const entityCol = columns[0];
+    const timeCol = columns.length > 1 ? columns[1] : columns[0];
+    const valueCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+
+    // Compute rankings from raw values
+    const timeValues = [...new Set(data.map((d) => d[timeCol]))];
+    const rankedData: Record<string, any>[] = [];
+
+    for (const time of timeValues) {
+      const rowsAtTime = data
+        .filter((d) => d[timeCol] === time)
+        .sort((a, b) => Number(b[valueCol]) - Number(a[valueCol]));
+
+      rowsAtTime.forEach((row, idx) => {
+        rankedData.push({
+          ...row,
+          _rank: idx + 1,
+          _timePeriod: time,
+        });
+      });
+    }
+
+    const spec: VisualizationSpec = {
+      pattern: 'bump-chart',
+      title: options?.title ?? `Ranking of ${entityCol} over ${timeCol}`,
+      data: rankedData,
+      encoding: {
+        x: {
+          field: timeCol,
+          type: 'ordinal',
+          title: timeCol,
+        },
+        y: {
+          field: '_rank',
+          type: 'quantitative',
+          title: 'Rank',
+          sort: 'ascending',
+        },
+        color: {
+          field: entityCol,
+          type: 'nominal',
+        },
+      },
+      config: {
+        categoryField: entityCol,
+        timeField: timeCol,
+        valueField: valueCol,
+        showLabels: true,
+        strokeWidth: options?.strokeWidth ?? 3,
+        dotRadius: options?.dotRadius ?? 5,
+      },
+    };
+
+    return spec;
+  },
+};