AVA

# AVA - AI-Native Visual Analytics

> AVA is a technology framework designed for more convenient visual analytics, powered by AI.

## Overview

AVA, a complete rewrite focused on **AI-native 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.

## Key Features

- **Natural Language Queries**: Ask questions about your data in plain English
- **Query Suggestions**: Get AI-recommended analysis queries based on your data characteristics
- **LLM-Powered Analysis**: Leverages large language models for intelligent data analysis
- **Data Profiling**: Compute deterministic table and field statistics without an LLM call
- **Modular Architecture**: Clean separation of concerns with data, analysis, and visualization modules
- **Dual Environment**: Runs in both Node.js (DuckDB engine) and browsers (interpreter engine)

## Quick Start

### Node.js

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

// Initialize with LLM config
const ava = new AVA({
  llm: {
    model: 'ling-1t',
    apiKey: 'YOUR_API_KEY',
    baseURL: 'LLM_BASE_URL',
  },
  // engine: { type: 'duckdb' } is the default; no need to specify
});

// Load data from various sources — all through ava.load({ type, options })
await ava.load({ type: 'csv-file', options: { path: 'data/companies.csv' } }); // Node.js
await ava.load({ type: 'json', options: { data: [{ city: '杭州', gdp: 18753 }, { city: '上海', gdp: 43214 }] } });
await ava.load({ type: 'text', options: { text: '杭州 100，上海 200，北京 300' } });
await ava.load({ type: 'mysql', options: { host: 'localhost', database: 'mydb', user: 'root', password: 'secret' } });

// Profile the loaded data with the default metrics
const profile = await ava.profile();
console.log(profile.tables[0].metrics.row_count);

// Or request only the metrics you need
const focusedProfile = await ava.profile({
  metrics: ['row_count', 'null_count', 'min', 'max', 'mean', { id: 'top_values', limit: 5 }],
});

// Get AI-suggested queries
const suggestions = await ava.suggest(5); // Get top 5 suggestions (default: 3)
console.log(suggestions[0]);
// { query: "What is the average GDP by city?", score: 0.95, reason: "Reveals economic patterns across cities" }

// Ask questions in natural language
const result = await ava.analyze('What is the average revenue by region?');
console.log(result);

// Or use a suggested query
const suggestedResult = await ava.analyze(suggestions[0].query);
console.log(suggestedResult);

// Clean up
ava.dispose();
```

### Browser

```typescript
import { AVA } from '@antv/ava/browser';

const ava = new AVA({
  llm: {
    model: 'ling-1t',
    apiKey: 'YOUR_API_KEY',
    baseURL: 'LLM_BASE_URL',
  },
  engine: { type: 'interpreter' },
});

// Browser supports inline data sources only
await ava.load({ type: 'json', options: { data: [{ city: '杭州', gdp: 18753 }] } });
await ava.load({ type: 'csv', options: { csv: 'city,gdp\n杭州,18753\n上海,43214' } });
await ava.load({ type: 'text', options: { text: '杭州 100，上海 200' } });

const result = await ava.analyze('What is the total GDP?');
const viz = await ava.visualize(result);

ava.dispose();
```

## Architecture

AVA uses a modular pipeline architecture with a pluggable engine registry:

1. **Data Module**: Load from multiple sources (inline CSV/JSON/text, local/remote files, or databases via load)
2. **Metadata Extract**: Type inference and structural schema
3. **Engine Registry**: Pluggable analysis engines
   - **DuckDB Engine** (Node.js): SQL via in-memory DuckDB
   - **Interpreter Engine** (Browser): JavaScript sandbox execution
   - **Supabase Engine** (Node.js): Remote SQL via Supabase API
4. **Analysis Module**: Generate & Execute Query
5. **LLM Summary**: Natural Language Response
6. **Visualization Module (Optional)**: Chart generation with type detection and recommendation

### Engine Registry

Engines are registered by the entry point, so the core `AVA` class never imports any engine implementation directly. This keeps Node-only engines (DuckDB, Supabase) out of browser bundles.

- **Node.js** (`@antv/ava`): registers `duckdb`, `supabase`, and `interpreter` engines
- **Browser** (`@antv/ava/browser`): registers only the `interpreter` engine

## API Reference

### Constructor
- `new AVA(config: AVAConfig)` - Initialize AVA instance with LLM configuration and options
  - `llm`: required model config `{ model, apiKey, baseURL? }`
  - `engine?`: engine selection and options
    - `{ type: 'duckdb', memoryLimit?, threads?, maxTempDirectorySize?, queryTimeoutMs? }` (default, Node.js only)
    - `{ type: 'interpreter' }` (browser-compatible)
    - `{ type: 'supabase' }` (Node.js only)

### Data Loading
- `load(config)` - Load any data source; `{ type, options }`. Returns the dataset `Schema` (`{ tables: TableSchema[] }`; a source may expose multiple tables, e.g. a MySQL database, each registered as its own view).
  - inline types: `'csv'` (`{ csv }`, raw CSV content string), `'json'` (`{ data }`), `'text'` (`{ text }`, extracts data from unstructured text using LLM)
  - file types (`{ path, headers? }`, a local path or http(s) URL): `'csv-file'`, `'json-file'`, `'parquet'`, `'excel'` (one view per sheet) — Node.js only
  - database types: `'mysql'` (`{ host, port?, database, user?, password?, ssh? }`), `'postgresql'` (`{ host, port?, database, user?, password?, schema?, ssh? }`), `'mongodb'` (`{ connection?, host?, port?, database, user?, password?, authSource?, srv?, tls?, ssl?, tlsCAFile?, tlsAllowInvalidCertificates? }` — `connection` advanced string takes precedence) — all tables/collections are auto-discovered and exposed — Node.js only

### Data Profiling
- `profile(options?: ProfileOptions)` - Compute statistics for the loaded dataset without calling the LLM.
  - Default metrics: `row_count`, `null_count`, `distinct_count`, `top_values`, `min`, `max`, `mean`
  - Passing `metrics` replaces the defaults; `metrics: []` returns the enriched structure without scanning data
  - Other built-ins: `duplicate_count`, `min_length`, `max_length`, `sum`, `stddev`, `median`
  - `top_values` accepts `limit` (default `3`) and `maxDistinctRatio` (default `0.5`)
  - Returns the loaded schema plus `generatedAt`; every table has `metrics`, and every field has `logicalType` and `metrics`
  - Missing metric keys mean the metric was not requested, did not apply to that field type, or was unavailable

```typescript
const profile = await ava.profile({
  metrics: ['row_count', 'null_count', 'distinct_count', { id: 'top_values', limit: 5 }],
});

console.log(profile.tables[0].metrics.row_count);
console.log(profile.tables[0].fields[0].logicalType);
console.log(profile.tables[0].fields[0].metrics);
```

### Query Suggestions
- `suggest(count?: number)` - Get AI-recommended analysis queries based on dataset characteristics (default: 3)
  - Returns: Array of `{ query: string, score: number, reason: string }`
  - Queries are sorted by score in descending order
  - Score ranges from 0 to 1, indicating meaningfulness

### Analysis
- `analyze(query: string, config?: AnalysisConfig)` - Analyze data with natural language query; `config.strategy` selects `direct` (default) or `{ type: 'loop', maxSteps?: number }` (`maxSteps` defaults to 12)
  - Returns: `{ query, text, data, sql? }` (`sql` is the DuckDB SQL executed for the analysis, DuckDB engine only)

### Visualization
- `visualize(analysisResult)` - Generate chart output from analysis result
  - Returns: `{ chartType, syntax, html } | null` (`null` when no visualization intent or no usable data)

### Cleanup
- `dispose()` - Clean up resources and close database connections

## Environment Support

### Node.js

- Full feature set backed by an in-memory DuckDB instance (LLM generates SQL)
- Inline data (csv/json/text), local/remote files (csv-file/json-file/parquet/excel), and databases (mysql/postgresql) via `load`
- File system access for CSV loading, plus remote files such as OSS signed URLs
- Database sources ATTACH through DuckDB's mysql/postgres extensions; every table is auto-discovered and exposed to the LLM (with optional SSH tunneling)
- Supabase engine for remote SQL execution via Supabase Management API

### Browser

- Lightweight interpreter engine for client-side analytics
- Inline data sources only: `csv`, `json`, `text`
- JavaScript sandbox execution with `stat` helper functions
- No file system or database access
- Import from `@antv/ava/browser` to avoid bundling Node.js dependencies

## Best Practices

- Always call `ava.dispose()` when done to free resources
- Wrap async calls in try-catch blocks for error handling
- Validate data format before loading
- Never expose API keys in client-side code
- Use `@antv/ava/browser` in browser environments to avoid bundling Node.js dependencies

## Resources

- GitHub Repository: https://github.com/antvis/AVA
- Documentation: https://ava.antv.vision/documentation
- Issues: https://github.com/antvis/AVA/issues
- Related Projects:
  - GPT-Vis: https://github.com/antvis/GPT-Vis
  - Chart Visualization Skills: https://github.com/antvis/chart-visualization-skills
  - Vercel AI SDK: https://sdk.vercel.ai/

## License

MIT License - Copyright (c) AntV

---

For full documentation, visit: https://ava.antv.vision/documentation
For the complete README, see: https://github.com/antvis/AVA/blob/ai/README.md

More agent context in antvis/AVA

One other file this repository gives its agents.