AVA

English | 简体中文

AVA ( Visual Analytics) is a technology framework designed for more convenient visual analytics. A stands for AI-native, Automated, and Augmented; VA stands for Visual Analytics.

[!NOTE] Think of AVA as PandasAI for JavaScript. 💬📊🤖

It brings natural-language data analysis and visualization to your apps and AI agents.

✨ Why AVA?

🚀 Getting started

Install AVA with Node.js 22.13+:

npm install @antv/ava

💻 Usage

Download sales.csv and configure your model:

import { AVA } from '@antv/ava';

const ava = new AVA({
  llm: {
    model: '<your-model>',
    apiKey: '<your-api-key>',
    // baseURL: '<your-provider-api-url>',
  },
});

1. Load

await ava.source({ type: 'csv-file', options: { path: './sales.csv' } });

[!NOTE] Data preview

First 3 of 240 rows, selected columns:

order_date	product	sales
2025-01-01	Monitor	224.10
2025-01-02	Office Chair	680.20
2025-01-04	Monitor	2,191.20

2. Explore

Inspect the structure and data quality, then add business definitions:

const schema = await ava.schema();
const profile = await ava.profile({ metrics: ['row_count', 'null_count'] });
await ava.semantic(undefined, () => ({
  description: 'Use the sales column for amounts after discounts and order_date for monthly comparisons.',
}));

[!NOTE] Analysis context

Context	Details
Structure	data: 12 columns
Quality	240 rows; 1 missing region and 1 missing quantity
Semantics	sales is after discounts; monthly comparisons use order_date

3. Suggest

const suggestions = await ava.suggest(3);

[!NOTE] Suggested questions (examples)

• How did sales change from January to February 2025?
• Which products contributed most to the sales decline?
• How do sales and profit vary by region?

4. Analyze

const result = await ava.analyze(
  'Compare January and February 2025 sales by product. Show both months and the change, ordered by the largest decline.'
);

[!NOTE] Analysis result

Total sales fell 43.94%, led by a 16,092.10 decline in laptop sales.

First 3 of 9 products:

Product	January sales	February sales	Change
Laptop	19,688.10	3,596.00	−16,092.10
Standing Desk	9,655.80	5,546.10	−4,109.70
Monitor	6,536.25	4,731.00	−1,805.25

5. Visualize

const chart = await ava.visualize({
  query: 'Plot the sales change by product from January to February 2025 as a bar chart.',
  data: result.data,
});

[!NOTE] Chart preview

Powered by GPT-Vis.

🔌 Connect your data

[!TIP] Missing a data source? 💡🛠️

💬 Open an issue · 🛠️ Submit a pull request

🎯 Benchmarks

We evaluate AVA on established benchmarks to measure the accuracy and efficiency of its data analysis.

Evaluation setup and reports →

🧩 More ways to use AVA

Use with an Agent

Ask your AI agent:

Install the AVA skill with `npx skills add antvis/AVA`, then follow its setup instructions.

Agent setup guide →

Use from the CLI

Load and analyze data from your terminal:

ava source ./sales.csv
ava analyze '<dataset-id>' 'Compare January and February 2025 sales by product.'

See the CLI guide for setup and commands.

📚 Resources

• Documentation — Guides and examples
• Analysis strategies — Direct and loop execution
• API Reference — Methods and configuration
• AI — Try out AVA in the browser environment
• Benchmarks — Evaluation results
• Issues — Bug reports and feature requests

🤝🛠️ Contributing

Contributions are welcome. Include tests, examples, and documentation with new features.

Run npm test to test your changes. For model-backed tests, copy .env.example to .env and add your model settings.

📑 Papers

VizLinter - Chen, Q., Sun, F., Xu, X., Chen, Z., Wang, J. and Cao, N., 2021. VizLinter: A Linter and Fixer Framework for Data Visualization. IEEE transactions on visualization and computer graphics, 28(1), pp.206-216.

《数据可视化设计的类型学实践》（Exploring the Typology of Visualization Design） - 蓝星宇, 王嘉喆. 数据可视化设计的类型学实践, 《美术大观》, 2022(3), 149-152.

⚖️ License

MIT