Smart Charts

Upload a data file → get interactive charts and analysis reports, automatically.

Quick Start / 快速上手

3 步生成图表：

1. 上传数据 — 将 CSV / Excel / JSON 文件拖入对话框
2. 确认分析方向 — 查看数据摘要，确认推荐的图表类型
3. 查看结果 — 交互式图表（HTML）+ 分析报告（Markdown）

示例：

用户: 帮我分析这份销售数据 [上传 sales_2024.csv]

AI:  已加载 sales_2024.csv（120 行 × 8 列）
     关键字段: date, region, product, revenue, profit, quantity

     推荐分析方向:
     1. 各区域营收对比 → 柱状图
     2. 月度营收趋势   → 折线图
     3. 产品利润占比   → 饼图

     确认后开始生成？

用户: 确认

AI:  [生成交互式图表] [生成分析报告]

Activation Triggers / 触发条件

Load this skill when any of the following is met:

• User mentions: "analyze data", "generate chart", "data visualization", "chart", "visualization"

/ 用户提到：「分析数据」「生成图表」「数据可视化」

• User provides a data file and asks for analysis or visualization
• User asks to generate charts or a report from tabular data

Capability Boundaries / 能力边界

Supported / 支持

Limitations / 限制

Installation / 安装

# 标准安装（含哈希校验，确保包完整性）
pip install -r requirements.txt --require-hashes

# 如需更新依赖版本，先重新生成哈希
python {skill_base}/core/generate_hashes.py

Dependencies / 依赖

> All versions are pinned with == and verified with SHA256 hashes to prevent supply-chain attacks.

> ECharts is loaded via CDN (jsdelivr) — no local installation required.

Security / 安全机制

LLM-generated transform code is executed with multiple safety layers:

What happens when code is blocked:

CodeValidationError: 代码包含危险关键字，已阻止执行: open(
  Reason: 这些关键字可能用于文件操作，在数据转换场景中不需要。
  如确需使用，请检查数据是否需要预处理。

The error message explains why the code was blocked and how to resolve it.

User Guidance / 用户引导

When no data file is provided

Prompt the user:

> Please upload the data file(s) you want to analyze. Supported formats:

> - CSV (.csv / .tsv / .txt)

> - Excel (.xlsx / .xls)

> - JSON (.json)

>

> You can drag files directly into the chat box. Multiple files are supported.

When data files are provided

Step 1 — Parse and display a unified summary:

> Files loaded: 3

>

> | File | Rows | Cols | Key Fields |

> |------|------|------|------------|

> | east_sales.csv | 120 | 8 | date, revenue, profit… |

> | south_sales.csv | 98 | 8 | date, revenue, profit… |

> | products.xlsx | 45 | 5 | name, category, price… |

Step 2 — Infer file relationships and recommend an analysis strategy:

Step 3 — Execute after user confirmation.

Error handling

Each error message explains why it happened and what to do about it:

Execution Workflow

1. Obtain data file(s)
   └─ User uploads file(s) directly (primary method)
   └─ Or user provides file path(s)

2. Parse data
   └─ Call data_parser.py on all files
   └─ Single file  → parse directly
   └─ Multiple files → parse each, assess merge feasibility

3. Confirm & recommend
   └─ Display a summary table for all files
   └─ Recommend: merge / separate / join
   └─ Recommend chart type(s) based on data characteristics

3.5 Data transform (when needed)
   └─ Compare original data structure with the target chart's input format
   └─ If they match → skip transform, proceed to Step 4
   └─ If they don't match → LLM generates pandas transform code
   └─ Security check: keyword blacklist + AST whitelist validation
   └─ User confirmation: show code preview, wait for approval (skipped when auto_confirm=True in programmatic calls)
   └─ Execute in sandbox → producing a standardized DataFrame
   └─ If transform fails → feed error back to LLM for retry (max 2 attempts)
   └─ If retry still fails → fall back to original data + _prepare_axes auto-detection

4. Generate charts
   └─ Call chart_generator.py → produces ECharts HTML
   └─ Merged data  → cross-group comparison charts
   └─ Separate data → independent charts per file
   └─ Chart type is chosen by the LLM based on data shape

5. Check for a report template
   └─ Scan the templates/ subdirectory under the skill base
   └─ Read each meta.json; let the LLM judge relevance
   └─ No matching template → skip to free-form generation

6. Generate analysis report
   └─ Matching template found → fill template.md with data insights
   └─ No matching template    → LLM generates report freely

7. Present results
   └─ Interactive charts: use preview_url (HTML)
   └─ Markdown report:    use open_result_view

Configuration

output_dir:    output directory (optional; default: ./smart_charts_output)
templates_dir: report template directory (optional; default: ./templates)

> Important: Never hard-code absolute paths. All paths must be provided by the user or resolved dynamically from the working directory.

Data Parsing — CLI Reference

Usage / 调用方式

> Note: {skill_base} refers to the root directory of this skill (the directory containing SKILL.md). Replace it with the actual path when running commands manually.

# Single file / 单文件
python {skill_base}/core/data_parser.py <file_path> [--summary]

# Multiple files / 多文件
python {skill_base}/core/data_parser.py <file1> <file2> ... [--summary]

# Multiple files with auto-merge / 多文件自动合并
python {skill_base}/core/data_parser.py <file1> <file2> ... [--merge] [--summary]

Merge behavior:

Supported formats

Chart Generation — CLI Reference

Usage / 调用方式

python {skill_base}/core/chart_generator.py \
  <file_path> <chart_type> \
  --title "Chart Title" \
  --x-axis "date" \
  --y-axis "revenue profit" \
  --output-dir "./output"

Parameters

Supported chart types

Report Templates

Users can store custom report templates under the templates_dir directory.

Directory structure

templates/
├── _template_index.json         # Auto-generated metadata index
└── <template_id>/               # Each template has its own directory
    ├── meta.json                # Template metadata card
    ├── template.md              # Template content
    └── original.docx            # Source file (optional)

meta.json schema

{
  "id": "<auto_generated>",
  "name": "Monthly Sales Report",
  "description": "For monthly sales summaries: revenue trend, top products, regional breakdown.",
  "scenarios": ["monthly sales report", "sales performance review", "quarterly comparison"],
  "variables": ["period", "revenue", "profit", "order_count", "mom_growth", "yoy_growth"],
  "categories": ["sales", "finance", "business analysis"],
  "format": "markdown",
  "created_time": "<auto_generated>",
  "modified_time": "<auto_generated>"
}

LLM-driven template matching

Template matching is performed by the LLM, not by hard-coded algorithms.

1. Discover — template_manager.get_all_templates_summary() collects metadata
2. Analyze — LLM reasons about the user task and data characteristics
3. Select — LLM picks the best-matching template (or none)
4. Fill — Load template content and fill with data insights

Fallback behavior:

Template variable syntax (auto-detected)

Template Management

Supported template formats

Operations / 操作指令

Upload / Save a template

• Triggers: upload template, add template, save template

User: Save this sales report as a template.
AI:   Template saved: "Sales Report" (Markdown, 8 variables detected)

View template library

• Triggers: my templates, template list, show templates

User: Show my templates.
AI:   Your templates (3):
      1. Monthly Sales Report (Markdown) — monthly sales analysis
      2. Project Progress (Word) — project tracking
      3. Financial Report (PDF) — financial analysis

Auto-matching (seamless)

User: Analyze this month's sales data.
AI:   Matched template: "Monthly Sales Report"
      Auto-filling variables: revenue, profit, growth rate
      Generating professional report…

Template management error handling

Key Principles

1. Multi-file first — Users often upload multiple files. Guide proactively; handle batches gracefully.
2. Confirm before executing — Always show a data summary and confirm understanding before recommending analysis direction.
3. LLM chooses chart types — Recommend based on data semantics; never hard-code mapping rules.
4. Template-first report generation — Use a saved template when a good match exists; fall back to free-form only when necessary.
5. Dynamic path resolution — Absolute paths must never be hard-coded; resolve all paths at runtime.
6. Immediate result presentation — Charts via preview_url; Markdown reports via open_result_view.
7. Data adapt first — When data structure doesn't match the chart's input format, LLM should proactively generate transform code rather than force-rendering with raw data.
8. Security by default — All LLM-generated code must pass blacklist + AST validation; user confirmation is required in interactive mode (skipped when auto_confirm=True in programmatic calls, but security checks still apply).

Chart Input Format Spec

Each chart type expects the DataFrame in a specific shape. LLM must check whether the raw data matches; if not, generate transform code.

Transform Code Generation Prompt

When the raw data structure doesn't match the target chart's input format, use the following prompt template to generate transform code:

Known information:
- Raw data columns: {columns_with_dtypes}
- Data sample (first 5 rows): {sample}
- Target chart type: {chart_type}
- Required format for this chart: {chart_input_spec}

Generate a pandas code snippet that transforms df into a result DataFrame matching the chart's input format.

Rules:
1. Only use variables: df, pd, np
2. Must produce a variable named result (pd.DataFrame)
3. Do not modify df in-place; use df.copy() or chain operations
4. Keep code concise; prefer pandas built-in methods (pivot_table, melt, groupby, rename, etc.)
5. If raw data already matches the required format, output an empty string
6. Do NOT use: import, open, exec, eval, os, sys, subprocess, file I/O, network calls

Output format:

{one-line description of what the transform does}

{transform_code}

Common transform examples