@outsidedata/dolex 0.1.1 → 0.1.3

package/README.md

@@ -1,34 +1,47 @@
-# Dolex
+```
+ ██████╗   ██████╗  ██╗      ███████╗ ██╗  ██╗
+ ██╔══██╗ ██╔═══██╗ ██║      ██╔════╝ ╚██╗██╔╝
+ ██║  ██║ ██║   ██║ ██║      █████╗    ╚███╔╝
+ ██║  ██║ ██║   ██║ ██║      ██╔══╝    ██╔██╗
+ ██████╔╝ ╚██████╔╝ ███████╗ ███████╗ ██╔╝ ██╗
+ ╚═════╝   ╚═════╝  ╚══════╝ ╚══════╝ ╚═╝  ╚═╝
+```
 
-**Visualization intelligence for AI.** 43 handcrafted chart patterns — far beyond bar, line, and pie.
+**Your AI data analyst.** Not a chart library — a complete analytical engine that turns raw data into insight.
 
-Every AI assistant suggests a bar chart. Dolex suggests the *right* chart — bump charts for rankings, beeswarms for distributions, connected dot plots for two-metric comparisons, waffle charts for precise proportions.
+---
 
-## Features
+## The Problem
 
-- **43 Visualization Patterns** across 7 categories: comparison, distribution, composition, time, relationship, flow, and geo
-- **Pattern Selector** — analyzes data shape + user intent, scores every pattern, returns ranked recommendations with reasoning
-- **Data Source Connectors** — connect CSV, SQLite, PostgreSQL, or MySQL; query with a declarative DSL including joins, aggregations, and time bucketing
-- **React Components** — 43 thin-wrapper components with D3 lifecycle management
-- **HTML Builders** — 43 self-contained HTML documents, perfect for MCP Apps / iframes
-- **MCP Server** — 17 tools for Claude Desktop, ChatGPT, VS Code, and any MCP-compatible client
-- **Dashboard Builder** — multi-view dashboards with global filters and cross-view interactions
-- **Compound Visualizations** — chart + data table with linked highlighting
-- **Design System** — dark/light themes with color palettes, typography, and spacing tokens
-- **Smart Labels** — truncation, abbreviation, collision avoidance, adaptive strategies
-- **Offline Maps** — choropleth and proportional symbol maps with 33 embedded TopoJSON files covering world, continents, US states/counties, and 17 country subdivision maps
+Right now, getting real analysis out of an AI means one of two things:
 
-## Install
+1. **The Python REPL loop** — Claude writes a script, runs it, gets an error, fixes it, runs it again, gets a different error, and eventually produces a matplotlib chart with default styling that you'd be embarrassed to put in a deck.
 
-```bash
-npm install @outsidedata/dolex
-```
+2. **"Here's a bar chart"** — every AI assistant reaches for the same three chart types because they optimize for the most likely token, not the most informative visualization.
+
+Dolex replaces both. No Python. No REPL. No `import pandas`. No `plt.show()`. No debugging dependency conflicts. Just point it at your data and ask questions.
+
+## What It Actually Is
+
+Dolex is an MCP server that gives your AI assistant a complete data analysis toolkit:
+
+**A query engine** — point it at a CSV or SQLite file and query it with a declarative DSL. Joins across tables, aggregations (sum, avg, median, stddev, percentiles), time bucketing (group by month/quarter/year), window functions (lag, lead, rank, running totals, percent of total), filters, having clauses, sorting, and limits. Everything pandas can do, without the Python.
+
+**43 handcrafted visualization patterns** — not chart.js defaults. Bump charts for rankings, beeswarms for distributions, Sankey diagrams for flows, ridgeline plots for comparing distributions, connected dot plots for two-metric comparisons, calendar heatmaps for temporal patterns, and 37 more. Each pattern has selection rules that encode real data visualization expertise.
+
+**Pattern intelligence** — Dolex doesn't just render charts. It analyzes the shape of your data and your intent, scores all 43 patterns, and recommends the one that actually communicates the insight — not the obvious one.
+
+**Multi-view dashboards** — N-panel layouts with global filter controls and cross-view interactions. Not static images — interactive HTML with linked highlighting.
+
+**Auto-analysis planning** — give it a dataset and it generates a structured analysis plan: which columns matter, what relationships to explore, what charts to build, with ready-to-execute queries for each step.
 
-## MCP Server Setup
+**Offline everything** — charts render as self-contained HTML. 33 TopoJSON map files ship with the package. Zero CDN calls, zero external dependencies. Works air-gapped.
+
+## Install
 
 ### Claude Desktop
 
-Add this to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
@@ -41,128 +54,67 @@ Add this to your Claude Desktop configuration file (`~/Library/Application Suppo
 }
 ```
 
-Restart Claude Desktop. You'll see Dolex's 17 tools available in the tool picker.
-
 ### Claude Code
 
 ```bash
 claude mcp add dolex -- npx @outsidedata/dolex
 ```
 
-### Other MCP Clients
-
-Any MCP-compatible client (ChatGPT, VS Code, Goose, etc.) can connect via stdio:
+### Any MCP Client
 
 ```bash
 npx @outsidedata/dolex
 ```
 
-### MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `visualize` | Takes inline data + intent, returns visualization recommendations |
-| `visualize_from_source` | Takes a data source + DSL query + intent, returns visualization recommendations |
-| `list_patterns` | Browse all 43 available patterns |
-| `refine_visualization` | Tweak a visualization — sort, limit, flip axes, change colors, update title |
-| `add_source` | Connect a data source (CSV, SQLite, PostgreSQL, MySQL) |
-| `list_sources` | List all connected data sources |
-| `remove_source` | Disconnect and remove a data source |
-| `describe_source` | Column profiles for a data source |
-| `analyze_source` | Generate a structured analysis plan with ready-to-execute DSL queries |
-| `query_source` | Run a declarative DSL query against a data source |
-| `create_dashboard` | Multi-view dashboard with global filters and cross-view interactions |
-| `refine_dashboard` | Iterate on a dashboard — add/remove views, change layout, filters, themes |
-| `server_status` | Inspect cached data in server memory |
-| `clear_cache` | Clear cached specs and query results |
-| `report_bug` | Generate a sanitized bug report |
-| `export_html` | Return full self-contained HTML for a visualization |
-| `screenshot` | Render a visualization to PNG via headless Chromium |
-
-## Pattern Catalog
-
-| Category | Patterns |
-|----------|----------|
-| **Comparison** (9) | Bar, Diverging Bar, Slope Chart, Connected Dot Plot, Bump Chart, Lollipop, Bullet, Grouped Bar, Waterfall |
-| **Distribution** (7) | Histogram, Beeswarm, Violin, Ridgeline, Strip Plot, Box Plot, Density Plot |
-| **Composition** (9) | Stacked Bar, Waffle, Treemap, Sunburst, Circle Pack, Metric, Donut, Marimekko, Icicle |
-| **Time** (7) | Line, Area, Small Multiples, Sparkline Grid, Calendar Heatmap, Stream Graph, Horizon Chart |
-| **Relationship** (5) | Scatter, Connected Scatter, Parallel Coordinates, Radar, Heatmap |
-| **Flow** (4) | Sankey, Alluvial, Chord, Funnel |
-| **Geo** (2) | Choropleth, Proportional Symbol |
-
-## Library Usage
-
-### Pattern Selection
-
-```typescript
-import { selectPattern, registry } from '@outsidedata/dolex';
-
-const result = selectPattern(data, columns, 'compare rankings over time');
-console.log(result.recommended.pattern.name); // "Bump Chart"
-console.log(result.recommended.reasoning);
-
-const patterns = registry.getAll(); // 43 patterns
-const comparison = registry.getByCategory('comparison'); // 9 patterns
-```
-
-### React Components
+## The Query Engine
 
-```tsx
-import { BumpChart, Beeswarm, Waffle, Scatter, Line } from '@outsidedata/dolex/react';
+Drop a CSV on Claude and start asking questions. No schema definition, no imports, no setup. Dolex profiles your data automatically — column types, distributions, cardinality, sample values — and gives the LLM everything it needs to write smart queries.
 
-function Dashboard({ spec }) {
-  return <BumpChart spec={spec} width={800} height={500} />;
-}
-```
-
-Available components: `Bar`, `DivergingBar`, `SlopeChart`, `BumpChart`, `ConnectedDotPlot`, `Lollipop`, `Bullet`, `GroupedBar`, `Waterfall`, `Histogram`, `Beeswarm`, `StripPlot`, `Violin`, `Ridgeline`, `BoxPlot`, `DensityPlot`, `StackedBar`, `Waffle`, `Treemap`, `Sunburst`, `CirclePack`, `Metric`, `Donut`, `Marimekko`, `Icicle`, `Line`, `Area`, `SmallMultiples`, `SparklineGrid`, `CalendarHeatmap`, `StreamGraph`, `HorizonChart`, `Scatter`, `ConnectedScatter`, `ParallelCoordinates`, `Radar`, `Heatmap`, `Sankey`, `Alluvial`, `Chord`, `Funnel`, `Choropleth`, `ProportionalSymbol`
+The DSL compiles to SQL under the hood but the LLM never writes raw SQL. Instead it works with a structured, validated query language:
 
-### HTML Builders (MCP Apps / Iframes)
+**Aggregations**: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `median`, `stddev`, `p25`, `p75`, `percentile`
 
-```typescript
-import { buildChartHtml } from '@outsidedata/dolex/html';
+**Window functions**: `lag`, `lead`, `rank`, `dense_rank`, `row_number`, `running_sum`, `running_avg`, `pct_of_total` — with partition and order control
 
-const html = buildChartHtml(spec);
-// Complete self-contained HTML document with embedded D3 + data
-```
-
-### Theme
+**Time bucketing**: group by `day`, `week`, `month`, `quarter`, `year` — automatic date parsing
 
-```typescript
-import { theme, getTheme } from '@outsidedata/dolex/theme';
+**Joins**: inner and left joins across tables within the same source, with dot-notation field references and ambiguity detection
 
-const dark = getTheme('dark');
-const palette = dark.palettes.categorical;
-```
+**Filters**: before aggregation (`filter`) and after (`having`), with operators `=`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `not_in`, `between`, `like`, `is_null`, `is_not_null`
 
-### Smart Labels
+Every query is validated before execution — field names are checked against the schema with fuzzy "did you mean?" suggestions for typos.
 
-```typescript
-import { labelStrategy, truncateLabel, abbreviate } from '@outsidedata/dolex/utils';
+## 43 Patterns
 
-const strategy = labelStrategy(['January Sales', 'February Sales', ...], 400);
-```
-
-## Exports Map
-
-| Import Path | Contents |
-|-------------|----------|
-| `@outsidedata/dolex` | Types, patterns, theme, utilities, HTML builders |
-| `@outsidedata/dolex/react` | React components (requires React >=18) |
-| `@outsidedata/dolex/html` | Self-contained HTML chart builders |
-| `@outsidedata/dolex/theme` | Design system tokens |
-| `@outsidedata/dolex/utils` | Smart labels, responsive, export utilities |
-| `@outsidedata/dolex/patterns` | Pattern registry and selector |
+| Category | What they're for |
+|----------|-----------------|
+| **Comparison** (9) | Bar, Diverging Bar, Slope Chart, Connected Dot Plot, Bump Chart, Lollipop, Bullet, Grouped Bar, Waterfall |
+| **Distribution** (7) | Histogram, Beeswarm, Violin, Ridgeline, Strip Plot, Box Plot, Density Plot |
+| **Composition** (9) | Stacked Bar, Waffle, Treemap, Sunburst, Circle Pack, Metric, Donut, Marimekko, Icicle |
+| **Time** (7) | Line, Area, Small Multiples, Sparkline Grid, Calendar Heatmap, Stream Graph, Horizon Chart |
+| **Relationship** (5) | Scatter, Connected Scatter, Parallel Coordinates, Radar, Heatmap |
+| **Flow** (4) | Sankey, Alluvial, Chord, Funnel |
+| **Geo** (2) | Choropleth, Proportional Symbol — 33 offline maps (world, US, continents, 17 countries) |
 
-## Development
+## Tools
 
-```bash
-npm run build        # TypeScript compilation
-npm test             # Run tests (818 tests)
-npm run dev          # Watch mode for MCP server
-npm run mcp:stdio    # Run MCP server via tsx
-```
+| Tool | What it does |
+|------|-------------|
+| `add_source` | Point at a CSV or SQLite file |
+| `describe_source` | Profile columns, stats, sample rows |
+| `analyze_source` | Auto-generate an analysis plan |
+| `query_source` | Run queries with the full DSL |
+| `visualize` | Inline data → ranked chart recommendations |
+| `visualize_from_source` | Query + visualize in one step |
+| `refine_visualization` | Iterate on a chart |
+| `create_dashboard` | Multi-view dashboard with filters |
+| `refine_dashboard` | Iterate on a dashboard |
+| `list_patterns` | Browse all 43 patterns |
+| `export_html` | Get raw HTML |
+| `screenshot` | Render to PNG |
+| `server_status` | Inspect server state |
+| `clear_cache` | Reset |
+| `report_bug` | File a bug report |
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outsidedata/dolex",
-  "version": "0.1.1",
-  "description": "Visualization intelligence for AI — 43 handcrafted chart patterns with React components, MCP server, and self-contained HTML builders",
+  "version": "0.1.3",
+  "description": "AI data analyst — 43 handcrafted visualization patterns, query engine with window functions, and auto-analysis planning via MCP",
   "type": "module",
   "license": "MIT",
   "keywords": [