@quarri/claude-data-tools 1.1.0 → 1.2.0

package/skills/quarri-chart/SKILL.md

@@ -1,12 +1,12 @@
 ---
-description: Generate charts in multiple formats - QuickChart URLs, matplotlib, or ASCII
+description: Generate interactive Plotly charts rendered as MCP UI resources
 globs:
 alwaysApply: false
 ---
 
-# /quarri-chart - Flexible Chart Generation
+# /quarri-chart - Interactive Chart Generation
 
-Generate data visualizations in multiple formats optimized for Claude Code users.
+Generate data visualizations as interactive Plotly charts using MCP UI resources.
 
 ## When to Use
 
@@ -14,73 +14,45 @@ Use `/quarri-chart` when users want visualizations:
 - "Create a chart of revenue by month"
 - "Visualize customer distribution"
 - "Show me a graph of this data"
-- "What's the best way to display these results?"
+- "Chart sales by category"
 
-## Output Formats
+## Primary Workflow
 
-### 1. QuickChart URL (DEFAULT)
-
-Generate a URL that renders instantly in any browser or terminal with image support.
-
-**When to use**: Quick visualization, sharing, embedding in documents
-
-```
-https://quickchart.io/chart?c={encoded_config}
-```
-
-**Example**:
-```
-https://quickchart.io/chart?c={type:'bar',data:{labels:['Q1','Q2','Q3','Q4'],datasets:[{label:'Revenue',data:[120,150,180,200]}]}}
+### Step 1: Query the data
+```sql
+SELECT category, SUM(sales) as total_sales
+FROM orders
+GROUP BY category
+ORDER BY total_sales DESC
 ```
 
-### 2. Matplotlib Code
-
-Generate Python code that creates and saves chart images.
-
-**When to use**: Custom styling, publication-quality charts, local files
-
-```python
-import matplotlib.pyplot as plt
-import pandas as pd
+### Step 2: Return chart as MCP UI resource
 
-# Data
-categories = ['Q1', 'Q2', 'Q3', 'Q4']
-values = [120, 150, 180, 200]
-
-# Create figure
-fig, ax = plt.subplots(figsize=(10, 6))
-ax.bar(categories, values, color='#4F46E5')
-
-# Styling
-ax.set_xlabel('Quarter')
-ax.set_ylabel('Revenue ($K)')
-ax.set_title('Quarterly Revenue')
-ax.spines['top'].set_visible(False)
-ax.spines['right'].set_visible(False)
-
-# Save
-plt.tight_layout()
-plt.savefig('revenue_chart.png', dpi=150)
-plt.show()
-```
-
-### 3. ASCII Chart
-
-Terminal-friendly text visualization for quick inspection.
-
-**When to use**: Terminal environments, quick data review, no graphics support
+After getting the data, construct a Plotly 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" }
+  }
+}
 ```
-Revenue by Quarter
 
-Q1 |████████████         | $120K
-Q2 |███████████████      | $150K
-Q3 |██████████████████   | $180K
-Q4 |████████████████████ | $200K
-    0        100       200
-```
+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 }`
 
-## Chart Selection Logic
+## Chart Type Selection
 
 ### Decision Tree
 
@@ -96,315 +68,237 @@ START: What is the primary analysis goal?
    └─→ 2-7 categories → VERTICAL BAR
    └─→ 8-15 categories → HORIZONTAL BAR
    └─→ 15+ categories → TOP N + "Other"
-   └─→ Multiple dimensions → GROUPED BAR
 
 3. SHOWING DISTRIBUTION?
    └─→ Continuous data → HISTOGRAM
    └─→ Categorical → BAR (sorted)
-   └─→ Compare groups → BOX PLOT
 
 4. PARTS OF A WHOLE?
    └─→ 2-6 parts → PIE/DONUT
-   └─→ 7+ parts → STACKED BAR (100%)
+   └─→ 7+ parts → STACKED BAR
 
 5. RELATIONSHIP BETWEEN VARIABLES?
    └─→ Two numeric → SCATTER PLOT
-   └─→ With grouping → SCATTER with colors
-
-DEFAULT: TABLE (when visualization unclear)
 ```
 
-## QuickChart Configuration
+## Plotly Templates
 
 ### Bar Chart
 ```javascript
 {
-  type: 'bar',
-  data: {
-    labels: ['A', 'B', 'C'],
-    datasets: [{
-      label: 'Values',
-      data: [10, 20, 15],
-      backgroundColor: '#4F46E5'
-    }]
-  },
-  options: {
-    title: { display: true, text: 'Chart Title' },
-    legend: { display: false }
+  "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" }
   }
 }
 ```
 
-### Line Chart
+### Horizontal Bar (many categories)
 ```javascript
 {
-  type: 'line',
-  data: {
-    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
-    datasets: [{
-      label: 'Revenue',
-      data: [100, 120, 115, 140],
-      borderColor: '#4F46E5',
-      fill: false
-    }]
+  "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 }
   }
 }
 ```
 
-### Horizontal Bar
+### Line Chart (time series)
 ```javascript
 {
-  type: 'horizontalBar',
-  data: {
-    labels: ['Product A', 'Product B', 'Product C'],
-    datasets: [{
-      data: [300, 250, 200],
-      backgroundColor: ['#4F46E5', '#10B981', '#F59E0B']
-    }]
+  "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" }
   }
 }
 ```
 
-### Pie/Donut Chart
+### Multi-Line Chart
 ```javascript
 {
-  type: 'doughnut',
-  data: {
-    labels: ['Desktop', 'Mobile', 'Tablet'],
-    datasets: [{
-      data: [60, 30, 10],
-      backgroundColor: ['#4F46E5', '#10B981', '#F59E0B']
-    }]
+  "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" }
   }
 }
 ```
 
-### Scatter Plot
+### Pie/Donut Chart
 ```javascript
 {
-  type: 'scatter',
-  data: {
-    datasets: [{
-      label: 'Data Points',
-      data: [{x: 1, y: 2}, {x: 2, y: 4}, {x: 3, y: 3}],
-      backgroundColor: '#4F46E5'
-    }]
+  "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"
   }
 }
 ```
 
-## Matplotlib Templates
-
-### Bar Chart
-```python
-import matplotlib.pyplot as plt
-
-fig, ax = plt.subplots(figsize=(10, 6))
-categories = ['A', 'B', 'C', 'D']
-values = [25, 40, 30, 35]
-
-bars = ax.bar(categories, values, color='#4F46E5', edgecolor='white')
-ax.bar_label(bars, fmt='%.0f')
-
-ax.set_ylabel('Value')
-ax.set_title('Category Comparison')
-ax.spines['top'].set_visible(False)
-ax.spines['right'].set_visible(False)
-
-plt.tight_layout()
-plt.savefig('bar_chart.png', dpi=150)
+### 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" }
+  }
+}
 ```
 
-### Line Chart
-```python
-import matplotlib.pyplot as plt
-import matplotlib.dates as mdates
-
-fig, ax = plt.subplots(figsize=(12, 6))
-dates = ['2024-01', '2024-02', '2024-03', '2024-04']
-values = [100, 120, 115, 140]
-
-ax.plot(dates, values, marker='o', color='#4F46E5', linewidth=2, markersize=8)
-ax.fill_between(dates, values, alpha=0.1, color='#4F46E5')
-
-ax.set_ylabel('Revenue ($K)')
-ax.set_title('Monthly Revenue Trend')
-ax.grid(True, alpha=0.3)
-ax.spines['top'].set_visible(False)
-ax.spines['right'].set_visible(False)
-
-plt.tight_layout()
-plt.savefig('line_chart.png', dpi=150)
+### 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"
+  }
+}
 ```
 
-### Horizontal Bar (for many categories)
-```python
-import matplotlib.pyplot as plt
+## Color Palettes
 
-fig, ax = plt.subplots(figsize=(10, 8))
-categories = ['Product A', 'Product B', 'Product C', 'Product D', 'Product E']
-values = [45, 38, 32, 28, 22]
+```javascript
+// Primary (single series)
+const PRIMARY = '#4F46E5';
 
-bars = ax.barh(categories, values, color='#4F46E5')
-ax.bar_label(bars, fmt='%.0f', padding=5)
+// Categorical (multiple series)
+const CATEGORICAL = ['#4F46E5', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6', '#EC4899', '#06B6D4', '#84CC16'];
 
-ax.set_xlabel('Sales ($K)')
-ax.set_title('Top Products by Sales')
-ax.invert_yaxis()  # Largest at top
-ax.spines['top'].set_visible(False)
-ax.spines['right'].set_visible(False)
+// Sequential (gradient)
+const SEQUENTIAL = ['#E0E7FF', '#A5B4FC', '#818CF8', '#6366F1', '#4F46E5', '#4338CA', '#3730A3'];
 
-plt.tight_layout()
-plt.savefig('horizontal_bar.png', dpi=150)
+// Diverging (positive/negative)
+const DIVERGING_NEG = '#EF4444';
+const DIVERGING_POS = '#10B981';
 ```
 
-## ASCII Chart Generation
-
-### Horizontal Bar (ASCII)
-```
-def ascii_bar_chart(data, title, max_width=40):
-    """Generate ASCII horizontal bar chart"""
-    print(f"\n{title}\n")
-    max_val = max(data.values())
+## Number Formatting
 
-    for label, value in data.items():
-        bar_len = int((value / max_val) * max_width)
-        bar = '█' * bar_len
-        print(f"{label:>15} |{bar} {value:,.0f}")
+```javascript
+// Currency
+tickformat: '$,.0f'      // $1,234,567
+tickformat: '$,.2f'      // $1,234,567.89
+tickformat: '$~s'        // $1.2M
 
-    print(f"{'':>15}  {'─' * max_width}")
+// Percentages
+tickformat: '.1%'        // 45.2%
 
-# Example
-data = {'Electronics': 45000, 'Clothing': 32000, 'Home': 28000}
-ascii_bar_chart(data, "Revenue by Category")
+// Large numbers
+tickformat: '~s'         // 1.2M, 3.4K
 ```
 
-**Output:**
-```
-Revenue by Category
+## MCP UI Resource Format
 
-    Electronics |████████████████████████████████████████ 45,000
-       Clothing |████████████████████████████            32,000
-           Home |████████████████████████                28,000
-                 ────────────────────────────────────────
-```
+The chart should be returned as an MCP UI resource with the following structure:
 
-### Vertical Bar (ASCII)
-```
-def ascii_vertical_bar(data, title, height=10):
-    """Generate ASCII vertical bar chart"""
-    print(f"\n{title}\n")
-    max_val = max(data.values())
-
-    for row in range(height, 0, -1):
-        line = ""
-        for value in data.values():
-            threshold = (row / height) * max_val
-            line += "  █  " if value >= threshold else "     "
-        print(f"{int(max_val * row / height):>6} |{line}")
-
-    print(f"{'':>6} +{'─────' * len(data)}")
-    labels = "".join(f"{k:^5}" for k in data.keys())
-    print(f"{'':>8}{labels}")
-
-# Example
-data = {'Q1': 120, 'Q2': 150, 'Q3': 180, 'Q4': 200}
-ascii_vertical_bar(data, "Quarterly Revenue")
-```
-
-### Sparkline (ASCII)
-```
-def ascii_sparkline(values, width=30):
-    """Generate inline ASCII sparkline"""
-    chars = '▁▂▃▄▅▆▇█'
-    min_val, max_val = min(values), max(values)
-    range_val = max_val - min_val or 1
-
-    line = ""
-    for v in values:
-        idx = int((v - min_val) / range_val * (len(chars) - 1))
-        line += chars[idx]
-
-    return f"[{line}] {values[0]:,.0f} → {values[-1]:,.0f}"
-
-# Example
-monthly = [100, 105, 98, 112, 120, 118, 125, 130, 128, 140, 145, 155]
-print(f"Revenue trend: {ascii_sparkline(monthly)}")
-# Output: Revenue trend: [▁▂▁▃▄▄▅▆▅▇▇█] 100 → 155
+```json
+{
+  "type": "chart",
+  "title": "Chart Title",
+  "plotly": {
+    "data": [/* Plotly data traces */],
+    "layout": {/* Plotly layout config */}
+  }
+}
 ```
 
-## Workflow
-
-1. **Analyze data shape**:
-   - Count rows and columns
-   - Identify column types (numeric, categorical, date)
-   - Check value distributions
-
-2. **Determine visualization goal**:
-   - Parse user question for intent
-   - Consider data characteristics
-
-3. **Select chart type**:
-   - Apply decision tree
-   - Consider data density and readability
-
-4. **Choose output format**:
-   - Default: QuickChart URL (instant rendering)
-   - If user needs customization: matplotlib code
-   - If terminal-only: ASCII chart
-
-5. **Generate and present**:
-   - Show chart or URL
-   - Include rationale
-   - Suggest alternatives
-
-## Output Format
-
-```markdown
-## Visualization: [Data Description]
-
-### Analysis
-- Data: [rows] rows, [columns] columns
-- Question type: [trend/comparison/distribution/etc.]
-- Key columns: [list]
+This is automatically rendered by Claude Code when you include the resource block in your response.
 
-### Recommended Chart: [Type]
-**Why**: [Brief rationale]
+## Alternative Outputs
 
-### Chart
-
-**QuickChart URL** (click to view):
-[URL]
-
-**Alternative: Matplotlib Code**
-```python
-[Code block]
+### QuickChart URL (for sharing/embedding)
+When user specifically needs a URL:
 ```
-
-**Alternative: ASCII Preview**
-```
-[ASCII chart]
+https://quickchart.io/chart?c={type:'bar',data:{labels:['A','B','C'],datasets:[{data:[10,20,15]}]}}
 ```
 
-### Alternatives
-- [Alternative chart 1]: [When it might be better]
-- [Alternative chart 2]: [When it might be better]
+### ASCII Chart (terminal only)
+When user is in a terminal-only environment:
 ```
+Sales by Category
 
-## Color Palettes
-
-```python
-# Primary palette
-PRIMARY = '#4F46E5'  # Indigo
-
-# Categorical (multiple series)
-CATEGORICAL = ['#4F46E5', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6', '#EC4899']
-
-# Sequential (single metric, gradient)
-SEQUENTIAL = ['#E0E7FF', '#A5B4FC', '#818CF8', '#6366F1', '#4F46E5']
-
-# Diverging (positive/negative)
-DIVERGING = ['#EF4444', '#FCA5A5', '#E5E7EB', '#86EFAC', '#22C55E']
+Technology      |████████████████████████████████████████ $5.47M
+Furniture       |██████████████████████████████████      $4.73M
+Office Supplies |██████████████████████████████          $4.14M
+                 0              $3M              $6M
 ```
 
 ## Integration