Skip to main content
Generate chart type and data preparation suggestions from a dataset. Send a GraphConfig and a prompt, receive a list of suggested visualizations.

​
Methods

​
generateSuggestions

Processes the request and returns the final result. Internally handles streaming and collects the response. 
async generateSuggestions(
  params: GenerateGraphSuggestionsParams,
  onProgress?: (event: ProgressEvent) => void,
  signal?: AbortSignal
): Promise<GenerateGraphSuggestionsResponse>

​
generateSuggestionsStream

Returns an async iterator that yields events as they arrive. 
async generateSuggestionsStream(
  params: GenerateGraphSuggestionsParams,
  signal?: AbortSignal
): Promise<AsyncIterableIterator<SSEEvent<GenerateGraphSuggestionsResponse>>>

​
Parameters

interface GenerateGraphSuggestionsParams {
  config: GraphConfig;
  userPrompt: string;
  metadata?: Metadata;
}
FieldTypeRequiredDescription
configGraphConfigYesThe chart configuration containing the dataset
userPromptstringYesNatural language description of what to visualize
metadataMetadataNoRequest tracking information

​
Response

interface GenerateGraphSuggestionsResponse {
  suggestions: Suggestion[];
}
FieldTypeDescription
suggestionsSuggestion[]List of chart type suggestions

​
Suggestion

interface Suggestion {
  dataPrepPrompt: string;
  chartType: AiChartType;
  summary: string;
}
FieldTypeDescription
dataPrepPromptstringPrompt describing how to prepare the data for this chart
chartTypeAiChartTypeSuggested chart type (see AiChartType)
summarystringShort description of what the chart would show
The response is validated with Zod. Invalid responses throw an error.

​
Basic Usage

import { GraphyAiSdk } from '@graphysdk/agents-sdk';
import type { GraphConfig } from '@graphysdk/core';

const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
});

const config: GraphConfig = {
  type: 'column',
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'sales', label: 'Sales' },
      { key: 'region', label: 'Region' },
    ],
    rows: [
      { month: 'Jan', sales: 100, region: 'North' },
      { month: 'Feb', sales: 120, region: 'South' },
      { month: 'Mar', sales: 115, region: 'North' },
    ],
  },
};

const result = await ai.generateSuggestions({
  config,
  userPrompt: 'Show me interesting trends',
});

for (const suggestion of result.suggestions) {
  console.log(`${suggestion.chartType}: ${suggestion.summary}`);
}

​
With Progress Callback

Use the onProgress callback to show real-time progress: 
const result = await ai.generateSuggestions(
  {
    config,
    userPrompt: 'What charts would best show this data?',
  },
  (progress) => {
    console.log(progress.message);
  }
);

​
Streaming

For full control over the event stream: 
import { isProgressEvent, isCompleteEvent, isErrorEvent } from '@graphysdk/agents-sdk';

const stream = await ai.generateSuggestionsStream({
  config,
  userPrompt: 'Suggest charts for sales analysis',
});

for await (const event of stream) {
  if (isProgressEvent(event)) {
    console.log(event.message);
  }

  if (isCompleteEvent(event)) {
    console.log('Suggestions:', event.data.suggestions);
  }

  if (isErrorEvent(event)) {
    console.error('Error:', event.error);
  }
}
See Streaming for cancellation and React patterns.

​
Error Handling

import { isGraphyApiError } from '@graphysdk/agents-sdk';

try {
  const result = await ai.generateSuggestions({
    config,
    userPrompt: 'Suggest charts',
  });
} catch (error) {
  if (isGraphyApiError(error)) {
    console.error('API error:', error.message);
  }
}
See Error Handling for retry behavior and error types.