antvis/AVA

AVA – AI‑native Visual Analytics

What it is

• AVA is a TypeScript library that lets you load tabular data, ask natural‑language questions about it, and get back both a textual answer and a chart. It does the heavy lifting with a large language model (LLM) and, for larger data sets, SQLite/IndexedDB.

Key capabilities

Feature	What you get
Natural‑language queries	Write questions like “What is the average revenue by region?” and AVA returns a summary, the raw data, and the code that produced it.
Query suggestions	AVA can propose a list of likely analyses based on the loaded data, each with a confidence score and a short rationale.
LLM‑powered analysis	The LLM interprets the query, decides whether to run JavaScript (small data) or SQL (large data), and produces a natural‑language explanation.
Smart data handling	Datasets under ~10 KB are processed in‑memory with generated JS; larger ones are stored in SQLite (Node) or IndexedDB (browser) and queried with SQL.
Visualization generation	After analysis, AVA can emit a chart description in the GPT‑Vis syntax, the chart type, and a ready‑to‑embed HTML snippet.
Cross‑environment	Works in browsers and Node.js without code changes.

Typical workflow

1. Create an instance with LLM credentials.
2. Load data – CSV file/path, CSV string, JSON array, remote URL, or free‑form text.
3. Ask or get suggestions – suggest() returns a ranked list of possible analyses; analysis(query) runs a chosen query.
4. Visualize – Pass the analysis result to visualize() to obtain chart code and HTML.
5. Dispose – Call dispose() to clean up SQLite/IndexedDB resources.

Example (Node or browser)

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

const ava = new AVA({
  llm: { model: 'ling-1t', apiKey: 'YOUR_API_KEY', baseURL: 'https://my-llm.com' },
  sqlThreshold: 2 * 1024 * 1024, // 2 MB
});

await ava.loadCSV('data/companies.csv');
const suggestions = await ava.suggest(3);
const result = await ava.analysis(suggestions[0].query);
console.log(result.text);               // natural‑language answer
console.log(result.data);               // raw data table
console.log(result.code ?? result.sql); // JS or SQL that produced it

const viz = await ava.visualize(result);
if (viz) {
  console.log(viz.chartType); // e.g. "column"
  document.body.innerHTML = viz.html; // render chart in a browser
}

ava.dispose();

Architecture at a glance

• Data module – loads CSV, JSON, URLs, or extracts tables from plain text.
• Metadata extraction – infers column types and basic statistics.
• Size check – decides between in‑memory JS helpers (< 10 KB) or SQLite/IndexedDB (≥ 10 KB).
• Analysis module – LLM generates either JavaScript code or SQL, which AVA executes.
• LLM summary – turns raw results into a readable paragraph.
• Visualization module (optional) – detects a visual intent, picks a chart type, and emits GPT‑Vis syntax plus a self‑contained HTML chart.

Who might use it

• Data analysts who want quick, conversational exploration of CSV/JSON files.
• Developers building dashboards that need an “ask‑your‑data” feature without writing custom query logic.
• Educators demonstrating how LLMs can bridge natural language and data visualization.

Getting started

npm install @antv/ava   # or pnpm/yarn

Then follow the quick‑start code above.

License: MIT – free for commercial and non‑commercial use.

---

Links

• Website / demo: https://ava.antv.vision
• Documentation: https://ava.antv.vision/documentation
• Related projects: GPT‑Vis (chart generation), Vercel AI SDK (LLM integration)