@outsidedata/dolex 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +75 -53
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,18 +1,47 @@
1
- # Dolex
1
+ ```
2
+ ██████╗ ██████╗ ██╗ ███████╗ ██╗ ██╗
3
+ ██╔══██╗ ██╔═══██╗ ██║ ██╔════╝ ╚██╗██╔╝
4
+ ██║ ██║ ██║ ██║ ██║ █████╗ ╚███╔╝
5
+ ██║ ██║ ██║ ██║ ██║ ██╔══╝ ██╔██╗
6
+ ██████╔╝ ╚██████╔╝ ███████╗ ███████╗ ██╔╝ ██╗
7
+ ╚═════╝ ╚═════╝ ╚══════╝ ╚══════╝ ╚═╝ ╚═╝
8
+ ```
2
9
 
3
- **Visualization intelligence for AI.** 43 handcrafted chart patterns — far beyond bar, line, and pie.
10
+ **Your AI data analyst.** Not a chart library — a complete analytical engine that turns raw data into insight.
4
11
 
5
- 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.
12
+ ---
6
13
 
7
- ## Install
14
+ ## The Problem
8
15
 
9
- ```bash
10
- npm install @outsidedata/dolex
11
- ```
16
+ Right now, getting real analysis out of an AI means one of two things:
17
+
18
+ 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.
19
+
20
+ 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.
21
+
22
+ 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.
23
+
24
+ ## What It Actually Is
25
+
26
+ Dolex is an MCP server that gives your AI assistant a complete data analysis toolkit:
27
+
28
+ **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.
29
+
30
+ **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.
31
+
32
+ **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.
33
+
34
+ **Multi-view dashboards** — N-panel layouts with global filter controls and cross-view interactions. Not static images — interactive HTML with linked highlighting.
35
+
36
+ **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.
37
+
38
+ **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.
39
+
40
+ ## Install
12
41
 
13
- ## Claude Desktop
42
+ ### Claude Desktop
14
43
 
15
- Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
44
+ Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
16
45
 
17
46
  ```json
18
47
  {
@@ -25,74 +54,67 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
25
54
  }
26
55
  ```
27
56
 
28
- Restart Claude Desktop. Dolex's 17 tools appear in the tool picker.
29
-
30
- ## Claude Code
57
+ ### Claude Code
31
58
 
32
59
  ```bash
33
60
  claude mcp add dolex -- npx @outsidedata/dolex
34
61
  ```
35
62
 
36
- ## Other MCP Clients
37
-
38
- Any MCP-compatible client (ChatGPT, VS Code, Goose, etc.) can connect via stdio:
63
+ ### Any MCP Client
39
64
 
40
65
  ```bash
41
66
  npx @outsidedata/dolex
42
67
  ```
43
68
 
44
- ## What It Does
69
+ ## The Query Engine
45
70
 
46
- You give Claude your data and ask a question. Dolex analyzes the data shape and your intent, then picks the right visualization from 43 handcrafted patterns — not the obvious chart, the *informative* one.
71
+ 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.
47
72
 
48
- Charts render inline in the conversation as interactive HTML. No external dependencies, no CDN calls, fully offline.
73
+ The DSL compiles to SQL under the hood but the LLM never writes raw SQL. Instead it works with a structured, validated query language:
49
74
 
50
- ### Tools
75
+ **Aggregations**: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `median`, `stddev`, `p25`, `p75`, `percentile`
51
76
 
52
- | Tool | What it does |
53
- |------|-------------|
54
- | `visualize` | Inline data + intent → ranked chart recommendations |
55
- | `visualize_from_source` | Data source + DSL query + intent → chart recommendations |
56
- | `list_patterns` | Browse all 43 patterns |
57
- | `refine_visualization` | Tweak a chart — sort, limit, flip axes, colors, title |
58
- | `add_source` | Connect CSV, SQLite, PostgreSQL, or MySQL |
59
- | `list_sources` | List connected sources |
60
- | `remove_source` | Disconnect a source |
61
- | `describe_source` | Column profiles and sample rows |
62
- | `analyze_source` | Auto-generate an analysis plan with DSL queries |
63
- | `query_source` | Run a declarative query (joins, aggregations, filters) |
64
- | `create_dashboard` | Multi-view dashboard with filters and cross-filtering |
65
- | `refine_dashboard` | Iterate on a dashboard |
66
- | `server_status` | Inspect cached data |
67
- | `clear_cache` | Clear cached specs and results |
68
- | `report_bug` | Generate a sanitized bug report |
69
- | `export_html` | Get raw HTML for a chart |
70
- | `screenshot` | Render a chart to PNG |
77
+ **Window functions**: `lag`, `lead`, `rank`, `dense_rank`, `row_number`, `running_sum`, `running_avg`, `pct_of_total` — with partition and order control
78
+
79
+ **Time bucketing**: group by `day`, `week`, `month`, `quarter`, `year` — automatic date parsing
80
+
81
+ **Joins**: inner and left joins across tables within the same source, with dot-notation field references and ambiguity detection
82
+
83
+ **Filters**: before aggregation (`filter`) and after (`having`), with operators `=`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `not_in`, `between`, `like`, `is_null`, `is_not_null`
71
84
 
72
- ### Patterns
85
+ Every query is validated before execution — field names are checked against the schema with fuzzy "did you mean?" suggestions for typos.
73
86
 
74
- | Category | Patterns |
75
- |----------|----------|
87
+ ## 43 Patterns
88
+
89
+ | Category | What they're for |
90
+ |----------|-----------------|
76
91
  | **Comparison** (9) | Bar, Diverging Bar, Slope Chart, Connected Dot Plot, Bump Chart, Lollipop, Bullet, Grouped Bar, Waterfall |
77
92
  | **Distribution** (7) | Histogram, Beeswarm, Violin, Ridgeline, Strip Plot, Box Plot, Density Plot |
78
93
  | **Composition** (9) | Stacked Bar, Waffle, Treemap, Sunburst, Circle Pack, Metric, Donut, Marimekko, Icicle |
79
94
  | **Time** (7) | Line, Area, Small Multiples, Sparkline Grid, Calendar Heatmap, Stream Graph, Horizon Chart |
80
95
  | **Relationship** (5) | Scatter, Connected Scatter, Parallel Coordinates, Radar, Heatmap |
81
96
  | **Flow** (4) | Sankey, Alluvial, Chord, Funnel |
82
- | **Geo** (2) | Choropleth, Proportional Symbol |
83
-
84
- ### Data Connectors
85
-
86
- - **CSV** — load local CSV files into an in-memory SQLite database
87
- - **SQLite** — read-only access to SQLite databases
88
- - **PostgreSQL** — connect to Postgres instances
89
- - **MySQL** — connect to MySQL instances
90
-
91
- All connectors support the declarative DSL query language with joins, aggregations, groupBy (with time bucketing), filters, orderBy, and limit.
97
+ | **Geo** (2) | Choropleth, Proportional Symbol — 33 offline maps (world, US, continents, 17 countries) |
92
98
 
93
- ### Offline Maps
99
+ ## Tools
94
100
 
95
- 33 TopoJSON files ship with the package — world maps, US states/counties, 6 continent maps, and 17 country subdivision maps (Germany, France, Japan, China, etc.). All map data is embedded inline in the chart HTML. No CDN calls, ever.
101
+ | Tool | What it does |
102
+ |------|-------------|
103
+ | `add_source` | Point at a CSV or SQLite file |
104
+ | `describe_source` | Profile columns, stats, sample rows |
105
+ | `analyze_source` | Auto-generate an analysis plan |
106
+ | `query_source` | Run queries with the full DSL |
107
+ | `visualize` | Inline data → ranked chart recommendations |
108
+ | `visualize_from_source` | Query + visualize in one step |
109
+ | `refine_visualization` | Iterate on a chart |
110
+ | `create_dashboard` | Multi-view dashboard with filters |
111
+ | `refine_dashboard` | Iterate on a dashboard |
112
+ | `list_patterns` | Browse all 43 patterns |
113
+ | `export_html` | Get raw HTML |
114
+ | `screenshot` | Render to PNG |
115
+ | `server_status` | Inspect server state |
116
+ | `clear_cache` | Reset |
117
+ | `report_bug` | File a bug report |
96
118
 
97
119
  ## License
98
120
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@outsidedata/dolex",
3
- "version": "0.1.2",
4
- "description": "Visualization intelligence for AI — 43 handcrafted chart patterns with React components, MCP server, and self-contained HTML builders",
3
+ "version": "0.1.3",
4
+ "description": "AI data analyst — 43 handcrafted visualization patterns, query engine with window functions, and auto-analysis planning via MCP",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "keywords": [