vizagent-dashboard 0.1.1

Compile CSV/XLSX data and DashboardSpec into validated offline HTML dashboards.

⭐ vizagent-dashboard

Turn business requirements into HTML dashboards — Use your own AI

You bring your data + your AI subscription. We compile them into a single HTML dashboard.

_{pip install → one command → interactive HTML dashboard. No database, no server, no hidden API bills.}

pip install vizagent-dashboard
vizagent build --data sales.xlsx --requirement "每月销售额趋势" --output dashboard/
# ✓ Dashboard generated in 3.2s → dashboard/output.html
# Open in browser — done.

---

✨ Features

• 🧠 AI-Powered, Your AI — In Agent Skill mode the host AI (Claude, Codex, …) authors the DashboardSpec using reasoning you already pay for — no extra API key, no hidden bills.
• 🔧 Zero-API Spec Mode — Prefer no AI at all? Write a structured DashboardSpec JSON and compile deterministically — zero LLM calls, zero API cost, works fully offline. The --requirement flag steers a built-in deterministic planner (still no LLM).
• 📦 Single HTML Output — One self-contained file. No server, no database, no build step. Drop it on any static host or open directly in a browser.
• 📊 Rich Charts — Line, bar, pie, scatter, map (China/world), KPI cards — powered by ECharts, inlined for offline use.
• 🎨 5 Clean-Room Themes — midnight-ops, paper-light, warm-editorial, clinical-light, signal-dark. No third-party brand names or assets. Switch with --theme <name>.
• 📁 CSV & Excel — Read from .csv or .xlsx, multiple sheets supported with per-sheet data-coverage tracking.
• ✅ Built-in Validation — Static + optional Playwright checks for truncation, external-script dependency, empty series, unbound maps, and row-level data coverage.
• 🔒 Secure by Default — Content Security Policy, HTML escaping, path traversal protection.
• 🤖 Agent Skill Ready — Loadable as a Claude Code / Codex skill under skills/build-data-dashboard/.

---

🔑 API Key Model (Clear & Simple)

Mode	Who pays for AI?	API Key needed?
Agent Skill (Claude/Codex)	You — already paying for your AI subscription	The skill uses your host AI's reasoning — no separate key to configure
CLI — Spec mode (--spec)	Nobody — compiler is fully deterministic	❌ No API key needed
CLI — Planner mode (--requirement)	Nobody — a built-in deterministic planner steers the Spec from keywords	❌ No API key needed

There is no config command and no --planner flag. The compiler and planner never call an LLM. All AI reasoning happens in your host agent (Agent Skill mode) — charged to your own subscription, never to this project.

---

🖼️ Gallery — one data file, five looks

同一份电商数据，5 个 clean-room 主题各编译一次。下图为其中 4 个主题的实际渲染首屏（截图来自 examples/ecommerce/）：

midnight-ops（默认） 深靛灰背景、蓝绿数据色	paper-light 暖白纸张、墨色文字
warm-editorial 浅米色、暗红重点	signal-dark 炭黑、琥珀青信号

第五个主题 clinical-light 可用 --theme clinical-light 自行构建查看。

---

🎨 5 Clean-Room Themes

One data file, five looks — each a generic, brand-free token set. Pick a theme that matches your story:

Theme	Vibe	Best for
midnight-ops (default)	深靛灰背景、蓝绿数据色	运营监控、技术演示
paper-light	暖白纸张、墨色文字	经营汇报、长时间阅读
warm-editorial	浅米色、暗红重点	内容分析、趋势故事
clinical-light	冷白、蓝青强调	健康、设备、服务质量
signal-dark	炭黑、琥珀青信号	告警、基础设施、高优先级状态

Legacy IDs (monitor-dark, paper-brief, paper-linen, minimal-doc, clean-slate, fitness-glass, command-post, amber-console) resolve to the closest theme above.

Switch with --theme <name>:

vizagent build --data sales.xlsx --theme paper-light --output dashboard/

---

🚀 Quick Start

1. Install

pip install vizagent-dashboard

2. Prepare your data

Save your data as CSV or Excel:

# sales.xlsx
# ┌──────────┬──────────┬──────────┬──────────┐
# │ 月份     │ 销售额   │ 类别     │ 地区     │
# ├──────────┼──────────┼──────────┼──────────┤
# │ 2026-01  │ 128000   │ 数码     │ 华东     │
# │ 2026-02  │ 135000   │ 数码     │ 华东     │
# │ ...      │ ...      │ ...      │ ...      │
# └──────────┴──────────┴──────────┴──────────┘

3. Build your dashboard

vizagent build \
  --data sales.xlsx \
  --requirement "月度销售额趋势，按类别和地区拆分，包含关键指标" \
  --output my-dashboard/

4. Open my-dashboard/output.html in your browser

---

📖 Usage

# Spec mode: data file + structured spec → zero API cost
vizagent build --data data.xlsx --spec spec.json --output dashboard/

# Planner mode: data file + requirement keywords → deterministic Spec (still no LLM)
vizagent build --data data.xlsx --requirement "按省份的销售额地图" --output dashboard/

# Specify theme
vizagent build --data data.xlsx --theme midnight-ops --output dashboard/

# Full pipeline
vizagent build \
  --data data.xlsx \
  --requirement "展示各品类季度趋势，顶部 KPI 卡片显示总额和增长" \
  --theme paper-light \
  --output dashboard/

Options

Option	Default	Description
--data	required	Path to CSV or Excel file
--requirement	""	Business requirement; steers the deterministic planner (no LLM)
--spec	—	Path to DashboardSpec JSON (zero-API mode)
--theme	from Spec or midnight-ops	Theme override; see Themes
--page-mode	single_page	single_page or tabs
--deployment	embedded	embedded (offline) or cdn
--output	./output	Output directory
--browser	false	Run the Playwright validation gate
--open	false	Open dashboard in browser after build

---

🏗️ Architecture

┌──────────────┐    ┌────────────┐    ┌──────────────┐
│  CSV / XLSX  │───▶│  Inventory │───▶│   Compiler   │───▶ output.html
│  (your data) │    │  (analyze) │    │  (generate)  │
└──────────────┘    └────────────┘    └──────────────┘
                          │                  │
                          ▼                  ▼
                   ┌──────────────┐   ┌──────────────┐
                   │ Requirement  │   │  Validator   │
                   │ (NLP → spec) │   │  (quality)   │
                   └──────────────┘   └──────────────┘

Key design: The Compiler is fully deterministic — no LLM, no API call, no network. The Planner (requirement → Spec) is a deterministic keyword planner, not an LLM. In Agent Skill mode the host AI authors the DashboardSpec using its own reasoning. In spec mode, the entire pipeline works offline with zero API cost.

---

🤖 Agent Skill Mode

vizagent-dashboard ships as a loadable Claude Code / Codex skill at skills/build-data-dashboard/ (with SKILL.md + agents/openai.yaml). The host AI reads the inventory, authors a DashboardSpec, then runs the vizagent CLI to compile and validate:

vizagent inventory --data <file> --output data.inventory.json
vizagent compile  --data <file> --spec <spec.json> --output dashboard/
vizagent validate --data <file> --spec <spec.json> --html dashboard/output.html

The skill uses your host AI's own reasoning — you're already paying for your AI subscription, no extra key to configure.

---

🧪 Development

# Clone
git clone https://github.com/Carloslee96/vizagent-dashboard.git
cd vizagent-dashboard

# Install in editable mode
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Lint
pip install ruff
ruff check src/ tests/

---

📄 License

Apache 2.0 © VizAgent Team. See LICENSE.

---

🌟 Star History

---

No database. No server. Just one HTML file.
You bring your data and your AI subscription — we do the rest.