antvis/ava

AVA ( Visual Analytics) is a technology framework designed for more convenient visual analytics. The first A has multiple meanings: AI native, Automated, Augmented, and VA stands for Visual Analytics. It can assist users in unstructured data loading, data processing and analysis, as well as visualization code generation.

✨ Features

• 💬 Natural-language analysis — Turn questions into executable queries, computed results, and summaries.
• 📊 Visualization — Recommend chart types and generate chart specifications and HTML.
• 🔍 Data profiling — Inspect tables and calculate missing-value counts, ranges, and averages.
• 💡 Question suggestions — Discover useful questions based on your data’s structure and available statistics.
• 🔌 App and agent integration — Use AVA through its SDK, CLI, or agent skill.
• ⚙️ Multiple execution engines — Use DuckDB, Python/pandas, or remote databases in Node.js, and JavaScript in browsers.
• 🧩 Composable workflows — Combine data loading, query generation, direct queries, and chart rendering.

🚀 Getting started

📦 Installation

Install the v4 beta with Node.js 22.13+:

npm install @antv/ava@beta

💻 Usage

Investigate a monthly sales decline: measure the change, identify the largest contributors, and visualize the breakdown.

Load data

Download sales.csv to your working directory. The sample contains 240 orders across 2025, with products, regions, channels, sales, and profit.

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

const ava = new AVA({
  llm: {
    model: '',
    apiKey: '',
    // baseURL: '',
  },
});

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

Ask questions

Measure the overall change using sales, the amount after discounts:

const overview = await ava.analyze(`
  Compare total sales in January and February 2025 using the sales column.
  Include the change and percentage change.
`);
console.log(overview.text);

Expected: sales fell from 38,897.18 to 21,804.11, down 17,093.07 (43.94%).

Find the products contributing to the decline:

const result = await ava.analyze(`
  Compare January and February 2025 sales by product using the sales column.
  Show both months and the change, ordered by the largest decline.
`);
console.log(result.text);
console.table(result.data);

Expected breakdown:

Laptops contributed the largest decline, while office chairs delivered the largest increase.

Visualize charts

Chart each product’s contribution to the sales change:

import { writeFile } from 'node:fs/promises';

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

Open sales-change.html in a browser with internet access.

Find questions to explore

Get suggested questions for your data:

const suggestions = await ava.suggest();
console.log(suggestions);

💡 Suggested questions

How do sales change month by month?

Which products contribute the most profit?

How do sales compare across channels?

Understand your data

Check missing values and sales ranges:

console.log(await ava.schema());
console.log(await ava.profile({ metrics: ['row_count', 'null_count', 'min', 'max'] }));

The sample has one missing region and one missing quantity.

Release resources when finished:

await ava.dispose();

🔌 Connect your data

Connect files and databases, or load inline data.

Load an Excel workbook with source():

await ava.source({ type: 'excel', options: { path: './sales.xlsx' } });

See the data source guide for connection settings and engine support.

For browser applications, use @antv/ava/browser with inline data. See runtime configuration.

🧩 More ways to use AVA

The agent and CLI workflows run on Node.js 22.13+ on macOS or Linux.

Use with an Agent

Your agent plans the analysis; AVA runs queries and creates charts.

npm install -g @antv/ava@beta
npx skills add antvis/AVA

In a new agent session, ask:

Use the AVA skill to analyze ./sales.csv. Compare January and February 2025
sales, identify the products contributing most to the change, and save a chart.

This workflow uses your agent’s existing model. See agent setup.

Use from the CLI

Configure your model and load a CSV:

npm install -g @antv/ava@beta

export OPENAI_API_KEY=''
export OPENAI_MODEL=''
# export OPENAI_BASE_URL=''

ava source ./sales.csv

Use the dataset ID returned by source:

ava analyze '' 'Compare January and February 2025 sales by product, including the change.'
ava dispose ''

analyze returns the answer as JSON. dispose releases the dataset. See all CLI commands.

📚 Resources

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

🤝 Developer Contributions

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.

🔗 Related Projects

• GPT-Vis - Visualization components
• Chart Visualization Skills - LLM skills for charts
• Vercel AI SDK - LLM integration

📑 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