> ## 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/core';
```

***

## 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);
```