Type Reference - Graphy SDK

Complete type definitions for the Graphy AI SDK.

GraphConfig

The chart configuration object. See Graph Config Schema for the complete reference.

import type { GraphConfig } from '@graphysdk/core';

GenerateGraphParams

Request parameters for the Chart Maker Agent.

interface GenerateGraphParams {
  config: GraphConfig;
  userPrompt?: string;
  metadata?: Metadata;
  storytellingOptions?: StorytellingOptions;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The current chart configuration
`userPrompt`	`string`	No	Natural language instruction
`metadata`	`Metadata`	No	Request tracking information
`storytellingOptions`	`StorytellingOptions`	No	Prune storytelling from config content client-side (SDK only).

GenerateGraphResponse

Response from the Chart Maker Agent.

interface GenerateGraphResponse {
  config: GraphConfig;
  response: {
    message: string;
    steps?: string[];
  };
}

Field	Type	Description
`config`	`GraphConfig`	Updated chart configuration. Narrative (title, subtitle, caption) is embedded in `config.content` as TipTap JSON documents.
`response.message`	`string`	Explanation of changes made
`response.steps`	`string[]`	Optional breakdown of modifications

GenerateMutationParams

Request parameters for the Mutation Agent.

interface GenerateMutationParams {
  config: GraphConfig;
  userPrompt?: string;
  metadata?: Metadata;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The current chart configuration, including the dataset to transform
`userPrompt`	`string`	No	Natural language description of the transformation to apply
`metadata`	`Metadata`	No	Request tracking information

GenerateMutationResponse

Response from the Mutation Agent.

interface GenerateMutationResponse {
  response: {
    message: string;
    steps: string[];
  };
  config: GraphConfig;
}

Field	Type	Description
`response.message`	`string`	Explanation of the transformations applied
`response.steps`	`string[]`	Ordered breakdown of each transformation step
`config`	`GraphConfig`	Updated chart configuration with the transformed dataset

GenerateAnnotationsParams

Request parameters for the Annotation Agent.

interface GenerateAnnotationsParams {
  config: GraphConfig;
  userPrompt?: string;
  metadata?: Metadata;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The current chart configuration to annotate
`userPrompt`	`string`	No	Natural language description of the annotations to add or remove
`metadata`	`Metadata`	No	Request tracking information

GenerateAnnotationsResponse

Response from the Annotation Agent.

interface GenerateAnnotationsResponse {
  response: {
    message: string;
    steps: string[];
  };
  config: GraphConfig;
}

Field	Type	Description
`response.message`	`string`	Explanation of the annotations applied
`response.steps`	`string[]`	Ordered breakdown of each annotation step
`config`	`GraphConfig`	Updated chart configuration with annotations applied

GenerateNarrativeParams

Request parameters for the Narrative Agent.

interface GenerateNarrativeParams {
  config: GraphConfig;
  userPrompt: string;
  metadata?: Metadata;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The chart configuration to narrate
`userPrompt`	`string`	Yes	Natural language instruction for the narrative
`metadata`	`Metadata`	No	Request tracking information

GenerateNarrativeResponse

Response from the Narrative Agent.

interface GenerateNarrativeResponse {
  response: {
    message: string;
  };
  config: GraphConfig;
}

Field	Type	Description
`response.message`	`string`	Explanation of the narrative produced
`config`	`GraphConfig`	Updated chart configuration. Title, subtitle, and caption are written into `config.content` as TipTap JSON documents.

GenerateGraphSuggestionsParams

Request parameters for the Suggestions Agent.

interface GenerateGraphSuggestionsParams {
  config: GraphConfig;
  userPrompt?: string;
  metadata?: Metadata;
  maxSuggestionCount?: 1 | 2 | 3 | 4;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The chart configuration containing the dataset
`userPrompt`	`string`	No	Natural language description of what to visualize
`metadata`	`Metadata`	No	Request tracking information
`maxSuggestionCount`	`1` \| `2` \| `3` \| `4`	No	Optional cap (1–4) passed to the model for how many suggestions to aim for. Omitted uses the default (4). Responses are not truncated if longer.

GenerateGraphSuggestionsResponse

Response from the Suggestions Agent.

interface GenerateGraphSuggestionsResponse {
  suggestions: Suggestion[];
}

Field	Type	Description
`suggestions`	`Suggestion[]`	List of chart type suggestions

Suggestion

A single chart suggestion returned by the Suggestions Agent.

interface Suggestion {
  dataPrepPrompt: string;
  chartType: AiChartType;
  summary: string;
}

Field	Type	Description
`dataPrepPrompt`	`string`	Prompt describing how to prepare the data for this chart
`chartType`	`AiChartType`	Suggested chart type
`summary`	`string`	Short description of what the chart would show

ExtractFromProseParams

Request parameters for the Extract Agent.

interface ExtractFromProseParams {
  sourceText?: string;
  attachments?: ExtractAttachmentInput[];
  images?: ExtractImageInput[];
  metadata?: Metadata;
}

Field	Type	Required	Description
`sourceText`	`string`	No	Raw text to extract data from. Up to 500,000 characters.
`attachments`	`ExtractAttachmentInput[]`	No	Images, PDFs, and spreadsheets to extract data from. Up to 12 entries.
`images`	`ExtractImageInput[]`	No	Deprecated. Legacy image array — use `attachments` instead.
`metadata`	`Metadata`	No	Request tracking information

Provide sourceText, attachments, or both — at least one is required. images and attachments cannot be combined in a single request.

ExtractAttachmentInput

A discriminated union tagged by kind, used for the Extract Agent’s attachments array. Construct entries with the buildImageAttachment, buildPdfAttachment, and buildSpreadsheetAttachment helpers.

type ExtractAttachmentInput =
  | { kind: 'image'; mimeType: string; dataBase64: string }
  | { kind: 'document'; mimeType: string; dataBase64: string }
  | { kind: 'spreadsheet'; mimeType: string; dataBase64: string; filename?: string };

`kind`	Accepted formats	Decoded size limit
`'image'`	PNG, JPEG, WebP, GIF	2 MB each, 8 max
`'document'`	PDF	6 MB each, 2 max
`'spreadsheet'`	Excel `.xlsx`	6 MB each, 2 max

A request accepts up to 12 attachments and 12 MB combined decoded size.

ExtractFromProseResponse

Response from the Extract Agent.

interface ExtractFromProseResponse {
  response: {
    message: string;
  };
  config: GraphConfig;
  extractMeta: ExtractMeta | null;
  lastAccuracyEvaluation?: ExtractAccuracyEvaluation;
}

Field	Type	Description
`response.message`	`string`	Summary of what was extracted
`config`	`GraphConfig`	Chart configuration containing the extracted dataset
`extractMeta`	`ExtractMeta \| null`	Trust metadata for the extraction, or `null` when unavailable
`lastAccuracyEvaluation`	`ExtractAccuracyEvaluation`	The agent’s final self-check of the extracted data, when performed

ExtractMeta

Trust metadata attached to an extraction result.

interface ExtractMeta {
  confidence: ExtractConfidence;
  needsUserInput: boolean;
  warnings: string[];
  cellConfidence?: Array<{
    rowIndex: number;
    columnKey: string;
    confidence: ExtractConfidence;
    quote?: string;
  }>;
}

type ExtractConfidence = 'high' | 'medium' | 'low';

Field	Type	Description
`confidence`	`ExtractConfidence`	Overall confidence in the extraction
`needsUserInput`	`boolean`	Whether the result should be reviewed before use
`warnings`	`string[]`	Notes about ambiguous, conflicting, or missing source data
`cellConfidence`	`Array<…>`	Optional per-cell confidence, each with a supporting source quote

ExtractAccuracyEvaluation

The Extract Agent’s self-check of an extraction result.

interface ExtractAccuracyEvaluation {
  score: number;
  issues: string[];
  sufficient: boolean;
  summary: string;
}

Field	Type	Description
`score`	`number`	Accuracy score, from `0` to `1`
`issues`	`string[]`	Specific accuracy problems the agent identified
`sufficient`	`boolean`	Whether the accuracy is good enough to use as-is
`summary`	`string`	Human-readable summary of the accuracy check

StorytellingOptions

SDK-only options to prune storytelling fields from the config content after the API returns. For each option set to true, the SDK removes that field from config.content before returning.

interface StorytellingOptions {
  excludeTitle?: boolean;
  excludeSubtitle?: boolean;
  excludeCaption?: boolean;
}

Field	Type	Description
`excludeTitle`	`boolean`	If true, the SDK removes `config.content.title`.
`excludeSubtitle`	`boolean`	If true, the SDK removes `config.content.subtitle`.
`excludeCaption`	`boolean`	If true, the SDK removes `config.content.caption`.

Metadata

Optional tracking information for requests.

interface Metadata {
  callId?: string;
  locale?: string;
  effort?: 'low' | 'medium' | 'high';
  /** @deprecated Prefer `effort`. */
  storytellingEffort?: 'none' | 'low' | 'medium' | 'high';
  budget?: InvocationBudget;
  executionMode?: 'agentic' | 'fast';
}

Field	Type	Description
`callId`	`string`	Optional. Identifier for tracking and debugging.
`locale`	`string`	Locale for responses (e.g., `en-US`, `fr-FR`).
`effort`	`'low' \| 'medium' \| 'high'`	Preferred invocation tier; stored on the invocation and forwarded to nested agents. Default `medium` when omitted.
`storytellingEffort`	`'none' \| 'low' \| 'medium' \| 'high'`	Deprecated — prefer `effort`. Still accepted for chart narrative and to infer `effort` when `effort` is omitted.
`budget`	`InvocationBudget`	Optional hard caps on time, tokens, and cost for the request.
`executionMode`	`'agentic' \| 'fast'`	Execution strategy: `agentic` runs the full multi-step loop, `fast` runs a single-shot plan.

InvocationBudget

Optional hard limits applied to a single request. The server merges any provided fields with its own per-agent defaults.

interface InvocationBudget {
  maxWallClockMs?: number;
  maxTotalTokens?: number;
  maxCostUsd?: number;
}

Field	Type	Description
`maxWallClockMs`	`number`	Hard wall-clock timeout for the request, in milliseconds
`maxTotalTokens`	`number`	Hard cap on total tokens consumed
`maxCostUsd`	`number`	Hard cap on request cost, in USD

SSE Events

ProgressEvent

interface ProgressEvent {
  type: 'progress';
  message: string;
  agentId?: string;
  executionId?: string;
  iteration?: number;
  metadata?: Record<string, unknown>;
}

CompleteEvent

interface CompleteEvent<T> {
  type: 'complete';
  data: T;
}

ErrorEvent

interface ErrorEvent {
  type: 'error';
  error: string;
  code?: string;
  retryable?: boolean;
}

PreviewEvent

An incremental preview of an agent’s work-in-progress result. The payload is spread at the top level, and its shape depends on the agent.

interface PreviewEvent {
  type: 'preview';
  [key: string]: unknown;
}

ReasoningEvent

A reasoning message emitted by an agent as it works.

interface ReasoningEvent {
  type: 'reasoning';
  agentId: string;
  executionId: string;
  message: string;
}

SSEEvent Union

type SSEEvent<T> = ProgressEvent | CompleteEvent<T> | ErrorEvent | PreviewEvent | ReasoningEvent;

Error Types

GraphyApiError

Error thrown by the SDK when an API request fails. Covers HTTP errors, SSE stream errors, and network failures.

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

class GraphyApiError extends Error {
  readonly status: number | undefined;
  readonly code: string | undefined;
  readonly retryable: boolean;

  constructor(message: string, options?: GraphyApiErrorOptions);
}

Property	Type	Description
`status`	`number \| undefined`	HTTP status code, if from an HTTP response
`code`	`string \| undefined`	Machine-readable error code from the API
`retryable`	`boolean`	Whether the SDK considers this error retryable

GraphyApiErrorOptions

interface GraphyApiErrorOptions {
  status?: number;
  code?: string;
  retryable?: boolean;
}

isGraphyApiError

Type guard for narrowing unknown errors to GraphyApiError:

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

if (isGraphyApiError(error)) {
  console.error(error.status, error.code, error.retryable);
}

Configuration Types

ClientConfig

interface ClientConfig {
  apiKey: string;
  baseUrl: string;
  timeout?: number;
  retryConfig?: RetryConfig;
  logger?: Logger;
}

RetryConfig

interface RetryConfig {
  attempts: number;
  delay: number;
  backoff: number;
}

Defaults:

{
  attempts: 3,
  delay: 1000,
  backoff: 2
}

Logger

interface Logger {
  log: (...args: unknown[]) => void;
  warn: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
  debug: (...args: unknown[]) => void;
}

AiChartType

Supported chart types for AI operations.

type AiChartType =
  | 'line'
  | 'areaStacked'
  | 'bar'
  | 'groupedBar'
  | 'stackedBar'
  | '100StackedBar'
  | 'column'
  | 'groupedColumn'
  | 'stackedColumn'
  | '100StackedColumn'
  | 'combo'
  | 'pie'
  | 'donut'
  | 'funnel'
  | 'heatmap'
  | 'scatter'
  | 'bubble'
  | 'waterfall'
  | 'table'
  | 'mekko';

Type	Description
`line`	Line chart
`areaStacked`	Stacked area chart
`bar`	Horizontal bar chart
`groupedBar`	Grouped horizontal bars
`stackedBar`	Stacked horizontal bars
`100StackedBar`	100% stacked horizontal bars
`column`	Vertical column chart
`groupedColumn`	Grouped vertical columns
`stackedColumn`	Stacked vertical columns
`100StackedColumn`	100% stacked vertical columns
`combo`	Combined line and column
`pie`	Pie chart
`donut`	Donut chart
`funnel`	Funnel chart
`heatmap`	Heatmap
`scatter`	Scatter plot
`bubble`	Bubble chart
`waterfall`	Waterfall chart
`table`	Data table
`mekko`	Marimekko chart

Zod Schemas

The SDK exports Zod schemas for runtime validation:

import { AiChartTypeEnum, GenerateGraphResponseSchema } from '@graphysdk/agents-sdk';

// Validate a response
const validated = GenerateGraphResponseSchema.parse(response);

​GraphConfig

​GenerateGraphParams

​GenerateGraphResponse

​GenerateMutationParams

​GenerateMutationResponse

​GenerateAnnotationsParams

​GenerateAnnotationsResponse

​GenerateNarrativeParams

​GenerateNarrativeResponse

​GenerateGraphSuggestionsParams

​GenerateGraphSuggestionsResponse

​Suggestion

​ExtractFromProseParams

​ExtractAttachmentInput

​ExtractFromProseResponse

​ExtractMeta

​ExtractAccuracyEvaluation

​StorytellingOptions

​Metadata

​InvocationBudget

​SSE Events

​ProgressEvent

​CompleteEvent

​ErrorEvent

​PreviewEvent

​ReasoningEvent

​SSEEvent Union

​Error Types

​GraphyApiError

​GraphyApiErrorOptions

​isGraphyApiError

​Configuration Types

​ClientConfig

​RetryConfig

​Logger

​AiChartType

​Zod Schemas