# AVA
**Repository Path**: antv/AVA
## Basic Information
- **Project Name**: AVA
- **Description**: A framework for automated visual analytics.
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: ai
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 18
- **Forks**: 2
- **Created**: 2020-04-15
- **Last Updated**: 2026-10-21
## Categories & Tags
**Categories**: charting-components
**Tags**: None
## README
AVA, AI-native Visual Analytics
[AVA](https://github.com/antvis/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](https://ava.antv.vision/documentation/analysis/overview/)** โ Turn questions into executable queries, computed results, and summaries.
- ๐ **[Visualization](https://ava.antv.vision/documentation/visualization/overview/)** โ Recommend chart types and generate chart specifications and HTML.
- ๐ **[Data profiling](https://ava.antv.vision/documentation/data/schema/#profile-a-dataset)** โ Inspect tables and calculate missing-value counts, ranges, and averages.
- ๐ก **[Question suggestions](https://ava.antv.vision/documentation/analysis/overview/#suggest-questions)** โ Discover useful questions based on your data's structure and available statistics.
- ๐ **[App and agent integration](https://ava.antv.vision/documentation/agent-skill/)** โ Use AVA through its SDK, CLI, or agent skill.
- โ๏ธ **[Multiple execution engines](https://ava.antv.vision/documentation/engines/overview/)** โ Use DuckDB, Python/pandas, or remote databases in Node.js, and JavaScript in browsers.
- ๐งฉ **[Composable workflows](https://ava.antv.vision/documentation/analysis/overview/#translate-and-execute-separately)** โ Combine data loading, query generation, direct queries, and chart rendering.
## ๐ Getting started
### ๐ฆ Installation
Install the v4 beta with Node.js 22.13+:
```bash
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](__tests__/datasets/sales.csv) to your working directory. The sample contains 240 orders across 2025, with products, regions, channels, sales, and profit.
```typescript
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:
```typescript
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:
```typescript
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:
| 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 |
| Pen Set | 232.20 | 127.71 | โ104.49 |
| Bookshelf | 1,225.50 | 1,251.30 | +25.80 |
| Copy Paper | 59.19 | 137.06 | +77.87 |
| Notebook | 31.50 | 137.03 | +105.53 |
| Keyboard | 215.64 | 1,015.31 | +799.67 |
| Office Chair | 1,253.00 | 5,262.60 | +4,009.60 |
Laptops contributed the largest decline, while office chairs delivered the largest increase.
#### Visualize charts
Chart each product's contribution to the sales change:
```typescript
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:
```typescript
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:
```typescript
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:
```typescript
await ava.dispose();
```
## ๐ Connect your data
Connect files and databases, or load inline data.
Load an Excel workbook with `source()`:
```typescript
await ava.source({ type: 'excel', options: { path: './sales.xlsx' } });
```
See the [data source guide](https://ava.antv.vision/documentation/data/sources/) for connection settings and engine support.
For browser applications, use `@antv/ava/browser` with inline data. See [runtime configuration](https://ava.antv.vision/documentation/browser/).
## ๐งฉ 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.
```bash
npm install -g @antv/ava@beta
npx skills add antvis/AVA
```
In a new agent session, ask:
```text
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](https://ava.antv.vision/documentation/agent-skill/).
### Use from the CLI
Configure your model and load a CSV:
```bash
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`:
```bash
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](https://ava.antv.vision/documentation/reference/cli/).
## ๐ Resources
- [Documentation](https://ava.antv.vision/documentation/) โ Guides and examples
- [Analysis strategies](https://ava.antv.vision/documentation/analysis/strategies/) โ Direct, loop, and subset execution
- [API Reference](https://ava.antv.vision/documentation/reference/api/) โ Methods and configuration
- [AI](https://ava.antv.vision/ai/) โ Try out AVA in the browser environment
- [Benchmarks](https://ava.antv.vision/documentation/reference/benchmarks/) โ Evaluation results
- [Issues](https://github.com/antvis/AVA/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](https://github.com/antvis/GPT-Vis) - Visualization components
- [Chart Visualization Skills](https://github.com/antvis/chart-visualization-skills) - LLM skills for charts
- [Vercel AI SDK](https://sdk.vercel.ai/) - LLM integration
## ๐ Papers
[VizLinter](https://vegalite-linter.idvxlab.com/) - 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๏ผ](https://oversea.cnki.net/KCMS/detail/detail.aspx?dbcode=CJFD&dbname=CJFDAUTO&filename=MSDG202203021&uniplatform=OVERSEAS_EN&v=HcZsiecIxauSoKEB1s92_BImgnrMiazYsfZUpb-gcl0zXYx_MEwv5alz1UgtPjz1) - ่ๆๅฎ, ็ๅๅ. ๆฐๆฎๅฏ่งๅ่ฎพ่ฎก็็ฑปๅๅญฆๅฎ่ทต, ใ็พๆฏๅคง่งใ, 2022(3), 149-152.
## โ๏ธ License
MIT
