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.

async evaluate(
  params: EvaluateParams,
  signal?: AbortSignal
): Promise<EvaluateResponse>

Parameters

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

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

Response

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.

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

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

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

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 for retry behavior and error types.

Get Started

TypeScript SDK

REST API

Reference

Method

evaluate

Parameters

Response

ChartFitEntry

ChartFitFactor

Basic Usage

Error Handling

​Method

​evaluate

​Parameters

​Response

​ChartFitEntry

​ChartFitFactor

​Basic Usage

​Error Handling

Method

evaluate

Parameters

Response

ChartFitEntry

ChartFitFactor

Basic Usage

Error Handling