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) |
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);
}
}
