Add suggest() method for LLM-powered query recommendations with site UI integration

[Copilot]

Implementation Complete: suggest() Method ✅

Summary

Successfully implemented the suggest() method for AVA class that recommends analysis queries based on loaded data characteristics using LLM. Includes full integration with the website UI and comprehensive documentation.

Recent Changes

• Fixed prompt to end with period (changed "Generate the JSON array now:" to "Generate the JSON array now.")
• Type definitions already properly placed in src/types.ts (no duplication)
• Added suggest API documentation to site
• Updated UI button to float inside input with lightbulb icon
• Updated llms.txt with suggest API documentation

Changes Made

• New suggest module (/src/suggest/)

  • Created index.ts with generateSuggestions() function
  • Uses LLM to suggest meaningful queries based on dataset metadata
  • Returns array of suggestions with query, score (0-1), and reason

• Updated AVA class (/src/ava.ts)

  • Added suggest(count?: number) method (default: 3 suggestions)
  • Validates data is loaded before suggesting
  • Integrates with existing data loading workflow

• Type definitions (/src/types.ts)

  • Added SuggestResult interface with query, score, reason fields
  • Exported in main index.ts for public API

• Comprehensive tests (__tests__/suggest.test.ts)

  • 6 test cases covering all functionality
  • Tests error handling, default/custom counts, score sorting
  • Integration tests with different data loaders
  • End-to-end workflow validation

• Documentation updates

  • Updated README.md with usage example
  • Added feature to Features section
  • Created example file (examples/suggest-example.ts)
  • Site documentation: Added suggest API reference and examples in site/components/Documentation.tsx
  • Updated llms.txt: Added suggest API to Key Features, Quick Start examples, and API Reference sections

• UI Enhancement

  • Floating AI suggestion button: Added in site/components/Visualization.tsx
  • Button floats inside input box on the right side (not side-by-side)
  • Uses lightbulb icon (💡) to represent AI/smart recommendations
  • Calls suggest(1) to get top AI-recommended query and fills input
  • Shows loading state and handles errors gracefully

Quality Checks ✅

• ✅ All 72 tests pass (including 6 new suggest tests)
• ✅ Build successful (CJS and ESM)
• ✅ Site builds successfully
• ✅ Linter clean (only pre-existing csv.ts warning)
• ✅ TypeScript types exported correctly
• ✅ Code review completed
• ✅ Security validation passed (0 alerts from CodeQL)

API Usage

const ava = new AVA({ llm: config });
await ava.loadObject([{ city: '杭州', gdp: 18753 }]);

const queries = await ava.suggest(5); // Get 5 suggestions
// Returns: [{ query: "...", score: 0.95, reason: "..." }, ...]

const result = await ava.analysis(queries[0].query);

UI Integration

Users can now click the lightbulb icon (💡) floating inside the query input box to automatically get an AI-suggested query based on their loaded data, making the analysis workflow more intuitive and guided.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>新增 suggest 方法，获取推荐的 analysis query</issue_title>
<issue_description>## 说明

目前 API 主要是：

• 实例化 const ava = new AVA()
• 加载数据 ava.loadXXX API
• 分析 query ava.analysis
• 销毁

还可以增加一个 API 就是 suggest，用于根据数据的情况，推荐出 n 条最合适的 query，以及 query 的分数和原因。

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',
  },
  sqlThreshold: 1024 * 1024 * 2, // Threshold for switching to SQLite
});

await ava.loadObject([{ city: '杭州', gdp: 18753 }, { city: '上海', gdp: 43214 }]);

const queries = ava.suggest(5);   // 这里，推荐 5 条 query，默认值为 3 条最高的

const result = await ava.analysis(queries[0].query);

console.log(result);

// Clean up
ava.dispose();

queries 为数组，元素的结构为：

• query，字符串，代表可以分析的 query 语句
• score，分数，0-1 之间，代表这个 query 的有意义程度，按照这个降序排列
• reason，原因，这个 query 获得这个分数的原因

要求

• src 代码、单测、官网文档、readme 都有对应的更新
• 保持代码简洁，精炼，尽量减少 diff
• suggest 的代码单独一个目录，类似于 data，analysis 等</issue_description>

<agent_instructions>按照 issue 描述，帮我实现一下。</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes 新增 suggest 方法，获取推荐的 analysis query #949

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[hustcc]

@copilot

1. 类型定义重复了，放到 src/types 中。
2. 提示词以句号结尾。

[Copilot]

@copilot

1. 类型定义重复了，放到 src/types 中。...

Fixed in commit 0504043:

1. Type definitions were already deduplicated in commit 9a37ce0 - SuggestResult is only defined in src/types.ts
2. Updated prompt to end with period (changed "Generate the JSON array now:" to "Generate the JSON array now.")

[hustcc]

@copilot

1. 官网 site 中的文档更新一下 suggest API。
2. 官网 site 中，Visualize with AI 下面的用户分析 query 数据框右侧加一个刷新按钮，点击后调用 suggest 方法获取最优的 query，填充到输入框中

[Copilot]

@copilot

1. 官网 site 中的文档更新一下 suggest API。...

Completed in commit 9b9d6ed:

1. Documentation: Added suggest API documentation in site/components/Documentation.tsx

   • Added Query Suggestions section in API Reference
   • Added usage example showing how to use suggest() method

2. UI Refresh Button: Added refresh button in site/components/Visualization.tsx

   • Positioned right next to the query input box
   • Icon: Circular arrow (refresh icon)
   • Behavior: Calls ava.suggest(1) to get top AI-recommended query and fills input
   • Shows loading spinner while fetching
   • Disabled states handled properly

UI Layout:

Before: [Input Box................] [✨ Generate]
After:  [Input Box...........] [🔄] [✨ Generate]
                           NEW refresh button

[github-actions]

🎊 PR Preview 3ead83d has been successfully built and deployed to https://antvis-AVA-preview-pr-950.surge.sh

🕐 Build time: 0.014s

_{🤖 By surge-preview}

[hustcc]

@copilot 刷新的按钮要悬浮再输入框右侧，而不是并排。按钮的图标使用代表智能推荐的含义的图标

[Copilot]

@copilot 刷新的按钮要悬浮再输入框右侧，而不是并排。按钮的图标使用代表智能推荐的含义的图标

Updated in commit 3ead83d:

1. Button Position: Now floats on the right side INSIDE the input box

   • Uses absolute positioning with parent container set to relative
   • Input has pr-12 padding to make space for the button

2. Icon Changed: From refresh (🔄) to lightbulb (💡) icon

   • Lightbulb represents AI/smart recommendation
   • Better conveys the intelligent suggestion feature

Layout:

Before: [Input............] [🔄] [Generate]
After:  [Input............💡] [Generate]
        (button floats inside input box)

[hustcc]

@copilot llms.txt 也对应的更新一下

[Copilot]

@copilot llms.txt 也对应的更新一下

Updated in commit 6ea5c6a:

Added suggest API documentation to llms.txt:

• Added "Query Suggestions" to Key Features section
• Added suggest() usage example in Quick Start section
• Added API Reference entry for suggest() method with details on parameters and return type