Skip to main content
Transform a chart’s dataset with natural language. Send a GraphConfig and a prompt, receive a GraphConfig with the dataset reshaped — filtered, grouped, aggregated, derived, and sorted.

​
Methods

​
generateMutation

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

​
generateMutationStream

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

​
Parameters

interface GenerateMutationParams {
  config: GraphConfig;
  userPrompt?: string;
  metadata?: Metadata;
}
FieldTypeRequiredDescription
configGraphConfigYesThe current chart configuration, including the dataset to transform
userPromptstringNoNatural language description of the transformation to apply
metadataMetadataNoRequest tracking information

​
Response

interface GenerateMutationResponse {
  response: {
    message: string;
    steps: string[];
  };
  config: GraphConfig;
}
FieldTypeDescription
response.messagestringExplanation of the transformations applied
response.stepsstring[]Ordered breakdown of each transformation step
configGraphConfigUpdated chart configuration with the transformed dataset
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: 'region', label: 'Region' },
      { key: 'sales', label: 'Sales' },
    ],
    rows: [
      { region: 'North', sales: 100 },
      { region: 'South', sales: 80 },
      { region: 'North', sales: 120 },
      { region: 'South', sales: 95 },
    ],
  },
};

const result = await ai.generateMutation({
  config,
  userPrompt: 'Total sales by region, sorted highest first',
});

console.log(result.config); // GraphConfig with the aggregated dataset
console.log(result.response.steps); // Ordered list of transformations applied

​
With Progress Callback

Use the onProgress callback to show real-time progress without full streaming: 
const result = await ai.generateMutation(
  {
    config,
    userPrompt: 'Keep only the last 12 months and add a 3-month moving average',
  },
  (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.generateMutationStream({
  config,
  userPrompt: 'Filter to the EMEA region and rank by revenue',
});

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

  if (isCompleteEvent(event)) {
    console.log('Result:', event.data.config);
  }

  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.generateMutation({
    config,
    userPrompt: 'Group sales by region',
  });
} catch (error) {
  if (isGraphyApiError(error)) {
    console.error('API error:', error.message);
  }
}
See Error Handling for retry behavior and error types.