> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Type Reference

Complete type definitions for the Graphy AI SDK.

## GraphConfig

The chart configuration object. See [Graph Config Schema](/sdk/reference/graph-config) for the complete reference.

```typescript theme={null}
import type { GraphConfig } from '@graphysdk/agents-sdk';
```

***

## GenerateGraphParams

Request parameters for the Chart Maker Agent.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
interface GenerateGraphSuggestionsResponse {
  suggestions: Suggestion[];
}
```

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

***

## Suggestion

A single chart suggestion returned by the Suggestions Agent.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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

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

### CompleteEvent

```typescript theme={null}
interface CompleteEvent<T> {
  type: 'complete';
  data: T;
}
```

### ErrorEvent

```typescript theme={null}
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.

```typescript theme={null}
interface PreviewEvent {
  type: 'preview';
  [key: string]: unknown;
}
```

### ReasoningEvent

A reasoning message emitted by an agent as it works.

```typescript theme={null}
interface ReasoningEvent {
  type: 'reasoning';
  agentId: string;
  executionId: string;
  message: string;
}
```

### SSEEvent Union

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
interface GraphyApiErrorOptions {
  status?: number;
  code?: string;
  retryable?: boolean;
}
```

### isGraphyApiError

Type guard for narrowing unknown errors to `GraphyApiError`:

```typescript theme={null}
import { isGraphyApiError } from '@graphysdk/agents-sdk';

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

***

## Configuration Types

### ClientConfig

```typescript theme={null}
interface ClientConfig {
  apiKey: string;
  baseUrl: string;
  timeout?: number;
  retryConfig?: RetryConfig;
  logger?: Logger;
}
```

### RetryConfig

```typescript theme={null}
interface RetryConfig {
  attempts: number;
  delay: number;
  backoff: number;
}
```

**Defaults:**

```typescript theme={null}
{
  attempts: 3,
  delay: 1000,
  backoff: 2
}
```

### Logger

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
import { AiChartTypeEnum, GenerateGraphResponseSchema } from '@graphysdk/agents-sdk';

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.