> ## 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.

# Evaluation

Score how well every chart type fits a dataset. Unlike the other agents, `evaluate` is deterministic — it runs a rule-based scorer with no language model, so it returns in a single fast response and uses no tokens.

## Method

### evaluate

Scores the dataset and returns the ranked result. There is no streaming variant — the result is computed synchronously on the server.

```typescript theme={null}
async evaluate(
  params: EvaluateParams,
  signal?: AbortSignal
): Promise<EvaluateResponse>
```

## Parameters

```typescript theme={null}
interface EvaluateParams {
  config: GraphConfig;
  chartFamily?: ChartFamily;
  metadata?: Metadata;
}
```

| Field         | Type          | Required | Description                                                                                                                                      |
| ------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `config`      | `GraphConfig` | Yes      | The chart configuration. Only `config.data` is scored.                                                                                           |
| `chartFamily` | `ChartFamily` | No       | Optional family hint — one of `comparison`, `relationship`, `distribution`, `composition`. When set, chart types in that family get a fit bonus. |
| `metadata`    | `Metadata`    | No       | Request tracking information                                                                                                                     |

<Note>
  `evaluate` is deterministic — it reads only `config.data` and the optional `chartFamily`. The chart `type`, styling, and annotations on `config` are ignored.
</Note>

## Response

```typescript theme={null}
interface EvaluateResponse {
  ranking: ChartFitEntry[];
}
```

| Field     | Type              | Description                                                       |
| --------- | ----------------- | ----------------------------------------------------------------- |
| `ranking` | `ChartFitEntry[]` | Every supported chart type, scored and ranked by fit (best first) |

The response is validated with Zod. Invalid responses throw an error.

### ChartFitEntry

A single chart type, scored against the dataset.

```typescript theme={null}
interface ChartFitEntry {
  rank: number;
  type: AiChartType;
  score: number;
  verdict: ChartFitVerdict;
  factors: ChartFitFactor[];
}

type ChartFitVerdict = 'ok' | 'disqualified';
```

| Field     | Type               | Description                                                                          |
| --------- | ------------------ | ------------------------------------------------------------------------------------ |
| `rank`    | `number`           | 1-based rank in `ranking`. Stable as scoring rules evolve — prefer it over `score`.  |
| `type`    | `AiChartType`      | The chart type being scored (see [AiChartType](/agents/reference/types#aicharttype)) |
| `score`   | `number`           | Raw fit score. Drifts as rules change; use `rank` and `verdict` for stable checks.   |
| `verdict` | `ChartFitVerdict`  | `ok` if the chart type is usable, `disqualified` if a rule rules it out              |
| `factors` | `ChartFitFactor[]` | The individual reasons that contributed to the score                                 |

### ChartFitFactor

```typescript theme={null}
interface ChartFitFactor {
  kind: ChartFitFactorKind;
  label: string;
  weight: number;
  reason: string;
}

type ChartFitFactorKind =
  | 'deal-breaker'
  | 'pro'
  | 'con'
  | 'family'
  | 'specificity'
  | 'continuity';
```

| Field    | Type                 | Description                            |
| -------- | -------------------- | -------------------------------------- |
| `kind`   | `ChartFitFactorKind` | The category of the factor             |
| `label`  | `string`             | Short label for the factor             |
| `weight` | `number`             | How much the factor moved the score    |
| `reason` | `string`             | Why the factor applies to this dataset |

***

## Basic Usage

```typescript theme={null}
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: 'product', label: 'Product' },
      { key: 'revenue', label: 'Revenue' },
      { key: 'units', label: 'Units Sold' },
    ],
    rows: [
      { product: 'Widget A', revenue: 4200, units: 120 },
      { product: 'Widget B', revenue: 3100, units: 90 },
      { product: 'Widget C', revenue: 5600, units: 60 },
    ],
  },
};

const result = await ai.evaluate({ config });

const best = result.ranking[0];
console.log(`Best fit: ${best.type} — rank ${best.rank}, ${best.verdict}`);
```

***

## Error Handling

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

try {
  const result = await ai.evaluate({ config });
} catch (error) {
  if (isGraphyApiError(error)) {
    console.error('API error:', error.message);
  }
}
```

See [Error Handling](/agents/sdk/errors) for retry behavior and error types.