npm - @quarri/claude-data-tools - Versions diffs - 1.2.7 → 1.3.0 - Mend

@quarri/claude-data-tools 1.2.7 → 1.3.0

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

package/package.json +1 -1
package/skills/quarri-chart/SKILL.md +409 -234

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@quarri/claude-data-tools",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "Quarri Data Assistant - Natural language data analysis with Quarri",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/quarri-chart/SKILL.md CHANGED Viewed

@@ -1,14 +1,14 @@
 ---
-description: Generate interactive Plotly charts rendered as MCP UI resources
+description: Generate interactive Plotly charts as HTML files
 globs:
 alwaysApply: false
 ---
 # /quarri-chart - Interactive Chart Generation
-Generate data visualizations as interactive **Plotly.js** charts using MCP UI resources.
+Generate data visualizations as interactive **Plotly.js** HTML files that open in the browser.
-**IMPORTANT**: Always use Plotly.js format. Do NOT generate React components, Recharts, Chart.js, or any other charting library. The MCP UI renderer only supports Plotly.js configuration objects.
+**IMPORTANT**: Always generate HTML files with Plotly.js from CDN. Do NOT generate React components, inline JSON, or any other format.
 ## When to Use
@@ -33,7 +33,7 @@ Use `/quarri-chart` when users want visualizations:
 ```sql
 -- BAD: Returns potentially thousands of products
-SELECT product_name, SUM(sales) FROM orders GROUP BY product_name
+SELECT product_name, SUM(sales) FROM quarri.schema GROUP BY product_name
 -- GOOD: Top 10 + Other
 WITH ranked AS (
@@ -54,7 +54,7 @@ ORDER BY total_sales DESC
 ```sql
 -- BAD: Daily data for 5 years = 1800+ points
-SELECT order_date, SUM(sales) FROM orders GROUP BY order_date
+SELECT order_date, SUM(sales) FROM quarri.schema GROUP BY order_date
 -- GOOD: Aggregate to months
 SELECT DATE_TRUNC('month', order_date) as month, SUM(sales) as total_sales
@@ -66,6 +66,9 @@ ORDER BY month
 ## Primary Workflow
 ### Step 1: Query the data (with appropriate aggregation)
+Use `quarri_execute_sql` to get the data:
 ```sql
 SELECT category, SUM(sales) as total_sales
 FROM quarri.schema
@@ -74,31 +77,386 @@ ORDER BY total_sales DESC
 LIMIT 20
 ```
-### Step 2: Return chart as MCP UI resource
-After getting the data, construct a **Plotly.js** configuration and include it in your response. The chart will be rendered as an interactive UI component.
-**Example Plotly config for bar chart:**
-```json
-{
-  "data": [{
-    "x": ["Category A", "Category B", "Category C"],
-    "y": [450000, 380000, 290000],
-    "type": "bar",
-    "marker": { "color": "#4F46E5" }
-  }],
-  "layout": {
-    "title": "Sales by Category",
-    "xaxis": { "title": "Category" },
-    "yaxis": { "title": "Sales ($)", "tickformat": "$,.0f" }
-  }
-}
+### Step 2: Generate HTML file with Plotly
+Write an HTML file that:
+1. Loads Plotly.js from CDN
+2. Embeds the query results as a JavaScript data array
+3. Builds Plotly traces from the data
+4. Renders the chart
+### Step 3: Open in browser
+Use `open <filepath>` (macOS) or `xdg-open <filepath>` (Linux) to display the chart.
+## HTML Template
+Use this template structure for all charts:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>CHART_TITLE</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>CHART_TITLE</h1>
+  <div id="chart"></div>
+  <script>
+    // Data from query results
+    const data = DATA_ARRAY;
+    // Build Plotly traces
+    const traces = [TRACE_CONFIG];
+    // Layout configuration
+    const layout = LAYOUT_CONFIG;
+    // Render chart
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
+```
+## Complete Examples
+### Bar Chart Example
+**Query:**
+```sql
+SELECT category, SUM(sales) as total_sales
+FROM quarri.schema
+GROUP BY category
+ORDER BY total_sales DESC
+```
+**HTML file to write:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Sales by Category</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>Sales by Category</h1>
+  <div id="chart"></div>
+  <script>
+    const data = [
+      { category: "Technology", total_sales: 836154.03 },
+      { category: "Furniture", total_sales: 741999.80 },
+      { category: "Office Supplies", total_sales: 719047.03 }
+    ];
+    const traces = [{
+      x: data.map(d => d.category),
+      y: data.map(d => d.total_sales),
+      type: 'bar',
+      marker: { color: '#4F46E5' },
+      text: data.map(d => '$' + (d.total_sales / 1000).toFixed(0) + 'K'),
+      textposition: 'auto'
+    }];
+    const layout = {
+      xaxis: { title: 'Category' },
+      yaxis: { title: 'Sales ($)', tickformat: '$,.0f' },
+      margin: { t: 20, r: 20, b: 60, l: 80 }
+    };
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
+```
+### Line Chart Example (Time Series)
+**Query:**
+```sql
+SELECT DATE_TRUNC('month', order_date) as month, SUM(sales) as total_sales
+FROM quarri.schema
+GROUP BY DATE_TRUNC('month', order_date)
+ORDER BY month
+```
+**HTML file to write:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Monthly Sales Trend</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>Monthly Sales Trend</h1>
+  <div id="chart"></div>
+  <script>
+    const data = [
+      { month: "2021-01-01", total_sales: 94925.57 },
+      { month: "2021-02-01", total_sales: 59751.25 },
+      { month: "2021-03-01", total_sales: 115973.79 }
+      // ... more data points
+    ];
+    const traces = [{
+      x: data.map(d => d.month),
+      y: data.map(d => d.total_sales),
+      type: 'scatter',
+      mode: 'lines+markers',
+      line: { color: '#4F46E5', width: 3 },
+      marker: { size: 8 }
+    }];
+    const layout = {
+      xaxis: { title: 'Month' },
+      yaxis: { title: 'Sales ($)', tickformat: '$,.0f' },
+      margin: { t: 20, r: 20, b: 60, l: 80 }
+    };
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
+```
+### Multi-Series Line Chart
+**Query:**
+```sql
+SELECT DATE_TRUNC('month', order_date) as month, category, SUM(sales) as total_sales
+FROM quarri.schema
+GROUP BY DATE_TRUNC('month', order_date), category
+ORDER BY month, category
+```
+**HTML file to write:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Sales Trend by Category</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>Sales Trend by Category</h1>
+  <div id="chart"></div>
+  <script>
+    const data = [
+      { month: "2021-01-01", category: "Furniture", total_sales: 28262.03 },
+      { month: "2021-01-01", category: "Office Supplies", total_sales: 21879.28 },
+      { month: "2021-01-01", category: "Technology", total_sales: 44784.26 }
+      // ... more data points
+    ];
+    // Group by category
+    const categories = [...new Set(data.map(d => d.category))];
+    const colors = ['#4F46E5', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6'];
+    const traces = categories.map((cat, i) => {
+      const catData = data.filter(d => d.category === cat);
+      return {
+        x: catData.map(d => d.month),
+        y: catData.map(d => d.total_sales),
+        name: cat,
+        type: 'scatter',
+        mode: 'lines+markers',
+        line: { color: colors[i % colors.length], width: 2 }
+      };
+    });
+    const layout = {
+      xaxis: { title: 'Month' },
+      yaxis: { title: 'Sales ($)', tickformat: '$,.0f' },
+      margin: { t: 20, r: 20, b: 60, l: 80 },
+      legend: { orientation: 'h', y: -0.15 }
+    };
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
 ```
-The response should include this as a resource block with:
-- URI: `ui://quarri/chart`
-- MIME type: `application/vnd.quarri.chart+json`
-- Content: JSON with `type: "chart"` and `plotly: { data, layout }`
+### Horizontal Bar Chart (Many Categories)
+**HTML file to write:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Top 10 Products by Sales</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>Top 10 Products by Sales</h1>
+  <div id="chart"></div>
+  <script>
+    const data = [
+      { product_name: "Canon imageCLASS 2200", total_sales: 61599.82 },
+      { product_name: "Fellowes PB500", total_sales: 27453.38 }
+      // ... more products
+    ];
+    // Reverse for horizontal bar (top item at top)
+    const sorted = [...data].reverse();
+    const traces = [{
+      y: sorted.map(d => d.product_name),
+      x: sorted.map(d => d.total_sales),
+      type: 'bar',
+      orientation: 'h',
+      marker: { color: '#4F46E5' }
+    }];
+    const layout = {
+      xaxis: { title: 'Sales ($)', tickformat: '$,.0f' },
+      margin: { t: 20, r: 20, b: 60, l: 200 }
+    };
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
+```
+### Pie/Donut Chart
+**HTML file to write:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Sales Distribution</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>Sales Distribution by Category</h1>
+  <div id="chart"></div>
+  <script>
+    const data = [
+      { category: "Technology", total_sales: 836154.03 },
+      { category: "Furniture", total_sales: 741999.80 },
+      { category: "Office Supplies", total_sales: 719047.03 }
+    ];
+    const traces = [{
+      labels: data.map(d => d.category),
+      values: data.map(d => d.total_sales),
+      type: 'pie',
+      hole: 0.4,
+      marker: { colors: ['#4F46E5', '#10B981', '#F59E0B'] },
+      textinfo: 'label+percent'
+    }];
+    const layout = {
+      margin: { t: 20, r: 20, b: 20, l: 20 },
+      showlegend: true
+    };
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
+```
+### Grouped Bar Chart
+**HTML file to write:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Year over Year Comparison</title>
+  <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background: #f8fafc; }
+    #chart { width: 100%; height: 600px; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { color: #1e293b; font-size: 1.5rem; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <h1>Year over Year Comparison</h1>
+  <div id="chart"></div>
+  <script>
+    const data = [
+      { year: 2023, quarter: "Q1", sales: 120000 },
+      { year: 2023, quarter: "Q2", sales: 150000 },
+      { year: 2024, quarter: "Q1", sales: 140000 },
+      { year: 2024, quarter: "Q2", sales: 165000 }
+    ];
+    const years = [...new Set(data.map(d => d.year))];
+    const colors = ['#4F46E5', '#10B981'];
+    const traces = years.map((year, i) => {
+      const yearData = data.filter(d => d.year === year);
+      return {
+        x: yearData.map(d => d.quarter),
+        y: yearData.map(d => d.sales),
+        name: String(year),
+        type: 'bar',
+        marker: { color: colors[i] }
+      };
+    });
+    const layout = {
+      barmode: 'group',
+      xaxis: { title: 'Quarter' },
+      yaxis: { title: 'Sales ($)', tickformat: '$,.0f' },
+      margin: { t: 20, r: 20, b: 60, l: 80 }
+    };
+    Plotly.newPlot('chart', traces, layout, { responsive: true });
+  </script>
+</body>
+</html>
+```
 ## Chart Type Selection
@@ -129,158 +487,6 @@ START: What is the primary analysis goal?
    └─→ Two numeric → SCATTER PLOT
 ```
-## Plotly Templates
-### Bar Chart
-```javascript
-{
-  "data": [{
-    "x": ["Category A", "Category B", "Category C"],
-    "y": [450000, 380000, 290000],
-    "type": "bar",
-    "marker": {
-      "color": ["#4F46E5", "#7C3AED", "#A78BFA"]
-    },
-    "text": ["$450K", "$380K", "$290K"],
-    "textposition": "auto"
-  }],
-  "layout": {
-    "title": "Sales by Category",
-    "xaxis": { "title": "Category" },
-    "yaxis": { "title": "Sales ($)", "tickformat": "$,.0f" }
-  }
-}
-```
-### Horizontal Bar (many categories)
-```javascript
-{
-  "data": [{
-    "y": ["Product A", "Product B", "Product C", "Product D", "Product E"],
-    "x": [85000, 72000, 65000, 58000, 45000],
-    "type": "bar",
-    "orientation": "h",
-    "marker": { "color": "#4F46E5" }
-  }],
-  "layout": {
-    "title": "Top Products by Revenue",
-    "xaxis": { "title": "Revenue ($)", "tickformat": "$,.0f" },
-    "margin": { "l": 120 }
-  }
-}
-```
-### Line Chart (time series)
-```javascript
-{
-  "data": [{
-    "x": ["2024-01", "2024-02", "2024-03", "2024-04", "2024-05", "2024-06"],
-    "y": [120000, 135000, 128000, 145000, 160000, 175000],
-    "type": "scatter",
-    "mode": "lines+markers",
-    "line": { "color": "#4F46E5", "width": 3 },
-    "marker": { "size": 8 }
-  }],
-  "layout": {
-    "title": "Monthly Revenue Trend",
-    "xaxis": { "title": "Month" },
-    "yaxis": { "title": "Revenue ($)", "tickformat": "$,.0f" }
-  }
-}
-```
-### Multi-Line Chart
-```javascript
-{
-  "data": [
-    {
-      "x": ["Jan", "Feb", "Mar", "Apr"],
-      "y": [100, 120, 115, 140],
-      "name": "Product A",
-      "type": "scatter",
-      "mode": "lines+markers"
-    },
-    {
-      "x": ["Jan", "Feb", "Mar", "Apr"],
-      "y": [80, 95, 110, 120],
-      "name": "Product B",
-      "type": "scatter",
-      "mode": "lines+markers"
-    }
-  ],
-  "layout": {
-    "title": "Product Comparison",
-    "xaxis": { "title": "Month" },
-    "yaxis": { "title": "Sales" }
-  }
-}
-```
-### Pie/Donut Chart
-```javascript
-{
-  "data": [{
-    "labels": ["Technology", "Furniture", "Office Supplies"],
-    "values": [5471124, 4730801, 4144724],
-    "type": "pie",
-    "hole": 0.4,
-    "marker": {
-      "colors": ["#4F46E5", "#10B981", "#F59E0B"]
-    },
-    "textinfo": "label+percent"
-  }],
-  "layout": {
-    "title": "Sales Distribution by Category"
-  }
-}
-```
-### Scatter Plot
-```javascript
-{
-  "data": [{
-    "x": [/* x values */],
-    "y": [/* y values */],
-    "mode": "markers",
-    "type": "scatter",
-    "marker": {
-      "size": 10,
-      "color": "#4F46E5",
-      "opacity": 0.7
-    }
-  }],
-  "layout": {
-    "title": "Correlation Analysis",
-    "xaxis": { "title": "Variable X" },
-    "yaxis": { "title": "Variable Y" }
-  }
-}
-```
-### Grouped Bar Chart
-```javascript
-{
-  "data": [
-    {
-      "x": ["Q1", "Q2", "Q3", "Q4"],
-      "y": [120, 150, 180, 200],
-      "name": "2023",
-      "type": "bar"
-    },
-    {
-      "x": ["Q1", "Q2", "Q3", "Q4"],
-      "y": [140, 165, 195, 220],
-      "name": "2024",
-      "type": "bar"
-    }
-  ],
-  "layout": {
-    "title": "Year over Year Comparison",
-    "barmode": "group"
-  }
-}
-```
 ## Color Palettes
 ```javascript
@@ -313,41 +519,36 @@ tickformat: '.1%'        // 45.2%
 tickformat: '~s'         // 1.2M, 3.4K
 ```
-## MCP UI Resource Format
+## File Output
-The chart should be returned as an MCP UI resource with the following structure:
-```json
-{
-  "type": "chart",
-  "title": "Chart Title",
-  "plotly": {
-    "data": [/* Plotly data traces */],
-    "layout": {/* Plotly layout config */}
-  }
-}
+**Always write to a descriptive filename:**
+```
+/tmp/quarri-chart-sales-by-category.html
+/tmp/quarri-chart-monthly-trend.html
+/tmp/quarri-chart-top-products.html
 ```
-This is automatically rendered by Claude Code when you include the resource block in your response.
-## Alternative Outputs
+**Then open in browser:**
+```bash
+# macOS
+open /tmp/quarri-chart-sales-by-category.html
-### QuickChart URL (for sharing/embedding)
-When user specifically needs a URL:
-```
-https://quickchart.io/chart?c={type:'bar',data:{labels:['A','B','C'],datasets:[{data:[10,20,15]}]}}
+# Linux
+xdg-open /tmp/quarri-chart-sales-by-category.html
 ```
-### ASCII Chart (terminal only)
-When user is in a terminal-only environment:
-```
-Sales by Category
+## Validation Checklist
-Technology      |████████████████████████████████████████ $5.47M
-Furniture       |██████████████████████████████████      $4.73M
-Office Supplies |██████████████████████████████          $4.14M
-                 0              $3M              $6M
-```
+Before generating a chart, verify:
+1. **Format**: Generating an HTML file with Plotly.js from CDN
+2. **Data embedded**: Query results are in a `const data = [...]` JavaScript array
+3. **Data points**: ≤ 500 points total (aggregate or sample if more)
+4. **Categories**: ≤ 20 categories (use Top N + Other if more)
+5. **Time granularity**: Appropriate for date range (don't show daily for multi-year)
+6. **Aggregation**: Never chart raw transactions - always GROUP BY
+7. **File written**: HTML file saved to /tmp/quarri-chart-*.html
+8. **Browser opened**: File opened with `open` or `xdg-open`
 ## Integration
@@ -355,29 +556,3 @@ Charts work best when combined with:
 - `/quarri-query`: Get data first, then visualize
 - `/quarri-analyze`: Called as part of full analysis pipeline
 - `/quarri-insights`: Visual support for statistical findings
-## Validation Checklist
-Before generating a chart, verify:
-1. **Library**: Using Plotly.js format (NOT React, Recharts, Chart.js, D3, or others)
-2. **Data points**: ≤ 500 points total (aggregate or sample if more)
-3. **Categories**: ≤ 20 categories (use Top N + Other if more)
-4. **Time granularity**: Appropriate for date range (don't show daily for multi-year)
-5. **Aggregation**: Never chart raw transactions - always GROUP BY
-**Output format must be:**
-```json
-{
-  "data": [{ /* Plotly trace */ }],
-  "layout": { /* Plotly layout */ }
-}
-```
-**NOT:**
-```jsx
-// WRONG - Do not generate React components
-<BarChart data={data}>
-  <Bar dataKey="value" />
-</BarChart>
-```