@dcyfr/ai-notebooks 1.0.0

package/src/visualization/chart.ts

@@ -0,0 +1,149 @@
+/**
+ * Chart Builder - Chart specification creation
+ */
+
+import type { ChartConfig, ChartSpec, ChartType, DataSeries } from '../types/index.js';
+
+/**
+ * Create a chart spec
+ */
+export function createChart(
+  type: ChartType,
+  title: string,
+  options?: Partial<ChartConfig>
+): ChartSpec {
+  return {
+    config: {
+      type,
+      title,
+      xLabel: options?.xLabel ?? '',
+      yLabel: options?.yLabel ?? '',
+      width: options?.width ?? 800,
+      height: options?.height ?? 400,
+      colors: options?.colors,
+      theme: options?.theme ?? 'dcyfr',
+      showLegend: options?.showLegend ?? true,
+      showGrid: options?.showGrid ?? true,
+    },
+    series: [],
+  };
+}
+
+/**
+ * Add a data series to a chart
+ */
+export function addSeries(chart: ChartSpec, series: DataSeries): ChartSpec {
+  return {
+    ...chart,
+    series: [...chart.series, series],
+  };
+}
+
+/**
+ * Create a data series
+ */
+export function createSeries(
+  name: string,
+  data: Array<{ x: number | string; y: number }>,
+  color?: string
+): DataSeries {
+  return { name, data, color };
+}
+
+/**
+ * Shortcut: create a bar chart
+ */
+export function barChart(
+  title: string,
+  labels: string[],
+  values: number[],
+  options?: Partial<ChartConfig>
+): ChartSpec {
+  const chart = createChart('bar', title, options);
+  const data = labels.map((label, i) => ({ x: label, y: values[i] ?? 0 }));
+  return addSeries(chart, createSeries(title, data));
+}
+
+/**
+ * Shortcut: create a line chart
+ */
+export function lineChart(
+  title: string,
+  xValues: number[],
+  yValues: number[],
+  options?: Partial<ChartConfig>
+): ChartSpec {
+  const chart = createChart('line', title, options);
+  const data = xValues.map((x, i) => ({ x, y: yValues[i] ?? 0 }));
+  return addSeries(chart, createSeries(title, data));
+}
+
+/**
+ * Shortcut: create a scatter plot
+ */
+export function scatterPlot(
+  title: string,
+  points: Array<{ x: number; y: number }>,
+  options?: Partial<ChartConfig>
+): ChartSpec {
+  const chart = createChart('scatter', title, options);
+  return addSeries(chart, createSeries(title, points));
+}
+
+/**
+ * Shortcut: create a pie chart
+ */
+export function pieChart(
+  title: string,
+  labels: string[],
+  values: number[],
+  options?: Partial<ChartConfig>
+): ChartSpec {
+  const chart = createChart('pie', title, options);
+  const data = labels.map((label, i) => ({ x: label, y: values[i] ?? 0 }));
+  return addSeries(chart, createSeries(title, data));
+}
+
+/**
+ * Shortcut: create a histogram
+ */
+export function histogram(
+  title: string,
+  values: number[],
+  bins = 10,
+  options?: Partial<ChartConfig>
+): ChartSpec {
+  const chart = createChart('histogram', title, options);
+
+  if (values.length === 0) return chart;
+
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const binWidth = (max - min) / bins;
+
+  const counts = new Array(bins).fill(0) as number[];
+  for (const v of values) {
+    const idx = Math.min(Math.floor((v - min) / binWidth), bins - 1);
+    counts[idx]++;
+  }
+
+  const data = counts.map((count, i) => ({
+    x: Number((min + i * binWidth + binWidth / 2).toFixed(2)),
+    y: count,
+  }));
+
+  return addSeries(chart, createSeries(title, data));
+}
+
+/**
+ * Update chart configuration
+ */
+export function updateChartConfig(
+  chart: ChartSpec,
+  updates: Partial<ChartConfig>
+): ChartSpec {
+  return {
+    ...chart,
+    config: { ...chart.config, ...updates },
+  };
+}

package/src/visualization/formatter.ts

@@ -0,0 +1,140 @@
+/**
+ * Formatter - Text-based rendering of charts and tables
+ */
+
+import type { ChartSpec, Dataset, DescriptiveStats } from '../types/index.js';
+
+/**
+ * Render a text-based horizontal bar chart
+ */
+export function renderBarChart(chart: ChartSpec, maxWidth = 50): string {
+  const lines: string[] = [];
+  lines.push(`  ${chart.config.title}`);
+  lines.push('  ' + '─'.repeat(maxWidth + 15));
+
+  for (const series of chart.series) {
+    for (const point of series.data) {
+      const maxVal = Math.max(...series.data.map((d) => d.y));
+      const barLen = maxVal > 0 ? Math.round((point.y / maxVal) * maxWidth) : 0;
+      const label = String(point.x).padEnd(12);
+      const bar = '█'.repeat(barLen);
+      lines.push(`  ${label} │${bar} ${point.y}`);
+    }
+  }
+
+  lines.push('  ' + '─'.repeat(maxWidth + 15));
+  return lines.join('\n');
+}
+
+/**
+ * Render data as a text table
+ */
+export function renderTable(
+  headers: string[],
+  rows: (string | number | null | undefined)[][],
+  options?: { maxColWidth?: number; align?: 'left' | 'right' | 'center' }
+): string {
+  const maxCol = options?.maxColWidth ?? 20;
+  const align = options?.align ?? 'left';
+
+  // Calculate column widths
+  const widths = headers.map((h) => Math.min(h.length, maxCol));
+  for (const row of rows) {
+    for (let i = 0; i < row.length; i++) {
+      const len = String(row[i] ?? '').length;
+      widths[i] = Math.min(Math.max(widths[i] ?? 0, len), maxCol);
+    }
+  }
+
+  const pad = (val: string, width: number): string => {
+    const s = val.slice(0, width);
+    if (align === 'right') return s.padStart(width);
+    if (align === 'center') {
+      const left = Math.floor((width - s.length) / 2);
+      return ' '.repeat(left) + s + ' '.repeat(width - s.length - left);
+    }
+    return s.padEnd(width);
+  };
+
+  const headerLine = headers.map((h, i) => pad(h, widths[i])).join(' │ ');
+  const separator = widths.map((w) => '─'.repeat(w)).join('─┼─');
+
+  const dataLines = rows.map((row) =>
+    row.map((val, i) => pad(String(val ?? ''), widths[i])).join(' │ ')
+  );
+
+  return [headerLine, separator, ...dataLines].join('\n');
+}
+
+/**
+ * Render a dataset as a text table
+ */
+export function renderDatasetTable(dataset: Dataset, maxRows = 20): string {
+  const headers = dataset.metadata.columns.map((c) => c.name);
+  const displayRows = dataset.rows.slice(0, maxRows);
+  const tableRows = displayRows.map((row) =>
+    headers.map((h) => row[h] as string | number | null | undefined)
+  );
+
+  let result = renderTable(headers, tableRows);
+
+  if (dataset.rows.length > maxRows) {
+    result += `\n... ${dataset.rows.length - maxRows} more rows`;
+  }
+
+  return result;
+}
+
+/**
+ * Render descriptive statistics as a table
+ */
+export function renderStatsTable(stats: DescriptiveStats[]): string {
+  const headers = ['Column', 'Count', 'Mean', 'Median', 'StdDev', 'Min', 'Max', 'Nulls'];
+  const rows = stats.map((s) => [
+    s.column ?? '',
+    s.count,
+    Number(s.mean.toFixed(2)),
+    Number(s.median.toFixed(2)),
+    Number(s.stddev.toFixed(2)),
+    s.min,
+    s.max,
+    s.nullCount,
+  ]);
+  return renderTable(headers, rows, { align: 'right' });
+}
+
+/**
+ * Render a sparkline from values
+ */
+export function sparkline(values: number[]): string {
+  if (values.length === 0) return '';
+  const chars = '▁▂▃▄▅▆▇█';
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min || 1;
+
+  return values
+    .map((v) => {
+      const idx = Math.min(Math.floor(((v - min) / range) * (chars.length - 1)), chars.length - 1);
+      return chars[idx];
+    })
+    .join('');
+}
+
+/**
+ * Format a number with locale-aware formatting
+ */
+export function formatNumber(value: number, decimals = 2): string {
+  return value.toFixed(decimals);
+}
+
+/**
+ * Render a simple text-based summary
+ */
+export function renderSummary(title: string, items: Record<string, unknown>): string {
+  const lines = [`  ${title}`, '  ' + '─'.repeat(40)];
+  for (const [key, value] of Object.entries(items)) {
+    lines.push(`  ${key.padEnd(20)} ${value}`);
+  }
+  return lines.join('\n');
+}

package/src/visualization/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Visualization module barrel exports
+ */
+
+export {
+  createChart,
+  addSeries,
+  createSeries,
+  barChart,
+  lineChart,
+  scatterPlot,
+  pieChart,
+  histogram,
+  updateChartConfig,
+} from './chart.js';
+
+export {
+  renderBarChart,
+  renderTable,
+  renderDatasetTable,
+  renderStatsTable,
+  sparkline,
+  formatNumber,
+  renderSummary,
+} from './formatter.js';
+
+export {
+  themes,
+  getTheme,
+  getSeriesColor,
+  registerTheme,
+} from './themes.js';
+
+export type { ChartTheme } from './themes.js';

package/src/visualization/themes.ts

@@ -0,0 +1,60 @@
+/**
+ * Themes - Chart theme definitions
+ */
+
+export interface ChartTheme {
+  name: string;
+  background: string;
+  foreground: string;
+  gridColor: string;
+  colors: string[];
+  fontFamily: string;
+}
+
+export const themes: Record<string, ChartTheme> = {
+  dcyfr: {
+    name: 'dcyfr',
+    background: '#0a0a0a',
+    foreground: '#fafafa',
+    gridColor: '#262626',
+    colors: ['#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#8b5cf6', '#ec4899'],
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+  light: {
+    name: 'light',
+    background: '#ffffff',
+    foreground: '#171717',
+    gridColor: '#e5e5e5',
+    colors: ['#2563eb', '#059669', '#d97706', '#dc2626', '#7c3aed', '#db2777'],
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+  dark: {
+    name: 'dark',
+    background: '#171717',
+    foreground: '#f5f5f5',
+    gridColor: '#404040',
+    colors: ['#60a5fa', '#34d399', '#fbbf24', '#f87171', '#a78bfa', '#f472b6'],
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+};
+
+/**
+ * Get a theme by name
+ */
+export function getTheme(name: string): ChartTheme {
+  return themes[name] ?? themes.dcyfr;
+}
+
+/**
+ * Get color for a series index from a theme
+ */
+export function getSeriesColor(theme: ChartTheme, index: number): string {
+  return theme.colors[index % theme.colors.length];
+}
+
+/**
+ * Register a custom theme
+ */
+export function registerTheme(theme: ChartTheme): void {
+  themes[theme.name] = theme;
+}

package/tests/cell.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Tests for notebook/cell.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createCell,
+  codeCell,
+  markdownCell,
+  rawCell,
+  createOutput,
+  addOutput,
+  clearOutputs,
+  markRunning,
+  markCompleted,
+  markError,
+  hasOutputs,
+  filterCodeCells,
+  filterByTag,
+  getSourceLines,
+  countLines,
+} from '../src/notebook/index.js';
+
+describe('Cell Creation', () => {
+  it('creates a cell with defaults', () => {
+    const cell = createCell('code', 'console.log("hi")');
+    expect(cell.type).toBe('code');
+    expect(cell.source).toBe('console.log("hi")');
+    expect(cell.status).toBe('idle');
+    expect(cell.outputs).toEqual([]);
+    expect(cell.executionCount).toBeUndefined();
+    expect(cell.id).toBeTruthy();
+  });
+
+  it('creates a code cell shortcut', () => {
+    const cell = codeCell('const x = 1;');
+    expect(cell.type).toBe('code');
+    expect(cell.source).toBe('const x = 1;');
+  });
+
+  it('creates a markdown cell shortcut', () => {
+    const cell = markdownCell('# Title');
+    expect(cell.type).toBe('markdown');
+    expect(cell.source).toBe('# Title');
+  });
+
+  it('creates a raw cell shortcut', () => {
+    const cell = rawCell('raw content');
+    expect(cell.type).toBe('raw');
+  });
+
+  it('creates a cell with tags', () => {
+    const cell = createCell('code', 'x', { tags: ['important', 'setup'] });
+    expect(cell.tags).toEqual(['important', 'setup']);
+  });
+
+  it('creates a cell with metadata', () => {
+    const cell = createCell('code', 'x', { metadata: { custom: 'value' } });
+    expect(cell.metadata).toEqual({ custom: 'value' });
+  });
+});
+
+describe('Cell Outputs', () => {
+  it('creates an output', () => {
+    const output = createOutput('text', 'Hello');
+    expect(output.type).toBe('text');
+    expect(output.data).toBe('Hello');
+  });
+
+  it('creates an output with metadata', () => {
+    const output = createOutput('chart', '{}', 'application/json');
+    expect(output.mimeType).toBe('application/json');
+  });
+
+  it('adds output to a cell', () => {
+    const cell = codeCell('x');
+    const updated = addOutput(cell, createOutput('text', 'result'));
+    expect(updated.outputs).toHaveLength(1);
+    expect(cell.outputs).toHaveLength(0); // immutable
+  });
+
+  it('clears outputs', () => {
+    let cell = codeCell('x');
+    cell = addOutput(cell, createOutput('text', 'a'));
+    cell = addOutput(cell, createOutput('text', 'b'));
+    expect(cell.outputs).toHaveLength(2);
+    const cleared = clearOutputs(cell);
+    expect(cleared.outputs).toHaveLength(0);
+  });
+
+  it('hasOutputs returns correct value', () => {
+    const empty = codeCell('x');
+    expect(hasOutputs(empty)).toBe(false);
+    const withOutput = addOutput(empty, createOutput('text', 'hi'));
+    expect(hasOutputs(withOutput)).toBe(true);
+  });
+});
+
+describe('Cell Status', () => {
+  it('marks cell as running', () => {
+    const cell = codeCell('x');
+    const running = markRunning(cell, 1);
+    expect(running.status).toBe('running');
+  });
+
+  it('marks cell as completed', () => {
+    const cell = codeCell('x');
+    const completed = markCompleted(cell, [createOutput('text', 'done')]);
+    expect(completed.status).toBe('completed');
+    expect(completed.outputs).toHaveLength(1);
+  });
+
+  it('marks cell as error', () => {
+    const cell = codeCell('x');
+    const errored = markError(cell, 'Something failed');
+    expect(errored.status).toBe('error');
+    expect(errored.outputs).toHaveLength(1);
+    expect(errored.outputs[0].type).toBe('error');
+    expect(errored.outputs[0].data).toBe('Something failed');
+  });
+});
+
+describe('Cell Filtering', () => {
+  it('filters code cells', () => {
+    const cells = [codeCell('a'), markdownCell('b'), codeCell('c'), rawCell('d')];
+    const codeCells = filterCodeCells(cells);
+    expect(codeCells).toHaveLength(2);
+    expect(codeCells.every((c) => c.type === 'code')).toBe(true);
+  });
+
+  it('filters by tag', () => {
+    const cells = [
+      createCell('code', 'a', { tags: ['setup'] }),
+      createCell('code', 'b', { tags: ['cleanup'] }),
+      createCell('code', 'c', { tags: ['setup', 'important'] }),
+    ];
+    const setup = filterByTag(cells, 'setup');
+    expect(setup).toHaveLength(2);
+  });
+});
+
+describe('Cell Source', () => {
+  it('gets source lines', () => {
+    const cell = codeCell('line1\nline2\nline3');
+    const lines = getSourceLines(cell);
+    expect(lines).toEqual(['line1', 'line2', 'line3']);
+  });
+
+  it('counts lines', () => {
+    const cell = codeCell('a\nb\nc');
+    expect(countLines(cell)).toBe(3);
+  });
+
+  it('counts single line', () => {
+    const cell = codeCell('single');
+    expect(countLines(cell)).toBe(1);
+  });
+});

package/tests/dataset.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Tests for pipeline/dataset.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  inferColumnType,
+  inferSchema,
+  createDataset,
+  selectColumns,
+  filterRows,
+  sortBy,
+  uniqueValues,
+  groupBy,
+  getColumn,
+  getNumericColumn,
+  head,
+  tail,
+  addColumn,
+  renameColumn,
+  dropNulls,
+} from '../src/pipeline/index.js';
+
+describe('Type Inference', () => {
+  it('infers string type', () => expect(inferColumnType('hello')).toBe('string'));
+  it('infers number type', () => expect(inferColumnType(42)).toBe('number'));
+  it('infers boolean type', () => expect(inferColumnType(true)).toBe('boolean'));
+  it('infers null type', () => expect(inferColumnType(null)).toBe('null'));
+  it('infers undefined as null', () => expect(inferColumnType(undefined)).toBe('null'));
+  it('infers date type', () => expect(inferColumnType(new Date())).toBe('date'));
+  it('infers array type', () => expect(inferColumnType([1, 2])).toBe('array'));
+  it('infers object type', () => expect(inferColumnType({ a: 1 })).toBe('object'));
+});
+
+describe('Schema Inference', () => {
+  it('infers schema from rows', () => {
+    const rows = [
+      { name: 'Alice', age: 25 },
+      { name: 'Bob', age: 30 },
+    ];
+    const schema = inferSchema(rows, 'people');
+    expect(schema.name).toBe('people');
+    expect(schema.rows).toBe(2);
+    expect(schema.columns).toHaveLength(2);
+    expect(schema.columns.find((c) => c.name === 'name')?.type).toBe('string');
+    expect(schema.columns.find((c) => c.name === 'age')?.type).toBe('number');
+  });
+
+  it('handles empty rows', () => {
+    const schema = inferSchema([]);
+    expect(schema.rows).toBe(0);
+    expect(schema.columns).toHaveLength(0);
+  });
+
+  it('detects nullable columns', () => {
+    const rows = [
+      { name: 'Alice', score: 90 },
+      { name: 'Bob', score: null },
+    ];
+    const schema = inferSchema(rows);
+    const scoreCol = schema.columns.find((c) => c.name === 'score');
+    expect(scoreCol?.nullable).toBe(true);
+  });
+});
+
+describe('Dataset Creation', () => {
+  it('creates a dataset', () => {
+    const ds = createDataset([{ x: 1 }], 'test', 'A test dataset');
+    expect(ds.metadata.name).toBe('test');
+    expect(ds.metadata.description).toBe('A test dataset');
+    expect(ds.rows).toHaveLength(1);
+  });
+});
+
+describe('Dataset Operations', () => {
+  const data = createDataset([
+    { name: 'Alice', age: 25, city: 'NYC' },
+    { name: 'Bob', age: 30, city: 'LA' },
+    { name: 'Charlie', age: 22, city: 'NYC' },
+    { name: 'Diana', age: 35, city: 'SF' },
+  ]);
+
+  it('selects columns', () => {
+    const selected = selectColumns(data, ['name', 'age']);
+    expect(Object.keys(selected.rows[0])).toEqual(['name', 'age']);
+  });
+
+  it('filters rows', () => {
+    const filtered = filterRows(data, (r) => (r.age as number) > 25);
+    expect(filtered.rows).toHaveLength(2);
+  });
+
+  it('sorts ascending', () => {
+    const sorted = sortBy(data, 'age');
+    expect(sorted.rows[0].name).toBe('Charlie');
+    expect(sorted.rows[3].name).toBe('Diana');
+  });
+
+  it('sorts descending', () => {
+    const sorted = sortBy(data, 'age', false);
+    expect(sorted.rows[0].name).toBe('Diana');
+  });
+
+  it('gets unique values', () => {
+    const cities = uniqueValues(data, 'city');
+    expect(cities).toContain('NYC');
+    expect(cities).toContain('LA');
+    expect(cities).toContain('SF');
+  });
+
+  it('groups by column', () => {
+    const groups = groupBy(data, 'city');
+    expect(groups.get('NYC')).toHaveLength(2);
+    expect(groups.get('LA')).toHaveLength(1);
+  });
+
+  it('gets column values', () => {
+    const ages = getColumn(data, 'age');
+    expect(ages).toEqual([25, 30, 22, 35]);
+  });
+
+  it('gets numeric column values', () => {
+    const ages = getNumericColumn(data, 'age');
+    expect(ages).toEqual([25, 30, 22, 35]);
+  });
+
+  it('gets head', () => {
+    const top = head(data, 2);
+    expect(top.rows).toHaveLength(2);
+    expect(top.rows[0].name).toBe('Alice');
+  });
+
+  it('gets tail', () => {
+    const bottom = tail(data, 2);
+    expect(bottom.rows).toHaveLength(2);
+    expect(bottom.rows[1].name).toBe('Diana');
+  });
+
+  it('adds a computed column', () => {
+    const withLabel = addColumn(data, 'label', (r) => `${r.name}-${r.city}`);
+    expect(withLabel.rows[0].label).toBe('Alice-NYC');
+  });
+
+  it('renames a column', () => {
+    const renamed = renameColumn(data, 'name', 'fullName');
+    expect(renamed.rows[0].fullName).toBe('Alice');
+    expect(renamed.rows[0].name).toBeUndefined();
+  });
+
+  it('drops nulls', () => {
+    const withNulls = createDataset([
+      { a: 1, b: 'x' },
+      { a: null, b: 'y' },
+      { a: 3, b: null },
+    ]);
+    const cleaned = dropNulls(withNulls, ['a']);
+    expect(cleaned.rows).toHaveLength(2);
+  });
+});