Değerlendirme: scorer & LLM-judge

@gnldev/evals, bir agent run'ının çıktısını journal trace'inden (kaydedilmiş model/araç geçmişinden) puanlar — canlı çağrıya değil, journal'a bakar. Bu yüzden puanlama deterministiktir ve replayable'dır: aynı journal her koştuğunda kural-tabanlı scorer'lar (exactMatch, contains, regex, embeddingSimilarity) aynı puanı verir; scoreRun ile çağrılan LLM-judge sonucu bile journal'a memoize edildiği için resume'da tekrar model çağrısı yapmaz, ilk seferki puanı döner.

Tipik senaryo: bir agent'ı bir dataset'teki N test-case üzerinden koşturup her case'i skorla, ortalamayı al — bunun için evalDataset kullanılır. Suite bir journal ile çağrılırsa her case durable şekilde memoize edilir: suite ortasında çökerse tamamlanan case'ler tekrar koşmaz, kalanlar kaldığı yerden devam eder (resumable eval suite).

Paket @gnldev/durable'a peer-dependency ile bağlıdır (journal okuma/yazma için); LLM-judge için de ai (AI SDK) gerekir.

pnpm add @gnldev/evals @gnldev/durable ai

import { scoreRun, exactMatch, contains, regexScore, embeddingSimilarity, llmJudge, evalDataset } from '@gnldev/evals';
import {
  faithfulness, hallucination, answerRelevancy, toxicity, bias, completeness, contextPrecision, toneConsistency,
} from '@gnldev/evals';
import { createDatasetsManager } from '@gnldev/evals';

1) Tamamlanmış bir run'ı puanla — scoreRun, bir JournalReader üzerinden run'ın journal trace'ini okur, son model entry'sinin metnini çıkarır ve verilen scorer'ları bu metne uygular:

import { scoreRun, exactMatch, llmJudge } from '@gnldev/evals';

const res = await scoreRun(reader, runId, [
  exactMatch(),
  llmJudge({ model, rubric: 'Is the answer correct and concise?' }),
], { expected: 'Paris' });

// res.output   -> the last model output in the journal
// res.scores   -> { 'exact-match': { score, reason }, 'llm-judge': { score, reason } }

reader, Journal arayüzünü de karşılıyorsa (ör. SqliteStorage örneği) scoreRun her scorer sonucunu `${runId}:proc:eval:${name}` anahtarıyla journal'a memoize eder — böylece aynı run tekrar puanlanırsa (veya resume edilirse) llmJudge bile ikinci kez model çağrısı yapmaz. Bunu { memo: false } ile kapatabilirsin.

2) Bir dataset üzerinde toplu değerlendirme — evalDataset, agent'ı dataset'teki her case'te koşturur, skorlar ve scorer başına ortalamayı toplar:

import { evalDataset } from '@gnldev/evals';

const report = await evalDataset({
  dataset: { id: 'qa-suite', cases: [
    { id: 'c1', input: 'What is the capital of France?', expected: 'Paris' },
  ] },
  run: async (input, { runId }) => {
    // run the agent for this case; return { output } or a string
    return runAgent(input, { runId });
  },
  scorers: [exactMatch()],
  journal, // when given, case results are memoized -> a resumable suite
});

// report.aggregate -> { 'exact-match': 0.8 } (0..1 ortalama)

journal parametresi verildiğinde her case `evalds:${dataset.id}` altında `case:${caseId}` anahtarıyla memoize edilir; suite ortasında çökme durumunda tamamlanmış case'ler journal'dan döner, koşulmaz.

3) Kural-tabanlı scorer'lar tek başına — Scorer arayüzünü uygulayan bu fonksiyonlar scoreRun/evalDataset olmadan da doğrudan çağrılabilir:

const exact = exactMatch();
await exact.score({ output: 'Paris', expected: 'Paris' }); // { score: 1, reason: 'exact match' }

const emb = embeddingSimilarity(
  (text) => embed({ model: embeddingModel, value: text }).then((r) => r.embedding),
  { threshold: 0.85 },
);
await emb.score({ output: '...', expected: '...' });

4) Hazır scorer'lar — 8 hazır scorer, llmJudge üzerine kurulu rubric'lerdir (faithfulness, hallucination, answerRelevancy, toxicity, bias, completeness, contextPrecision, toneConsistency) — hepsi generateText'i doğrudan çağırmaz, llmJudge'ı sarar; bu yüzden scoreRun/dataset memoizasyonu bedava gelir.

import { faithfulness, hallucination, toxicity } from '@gnldev/evals';

const res = await scoreRun(reader, runId, [
  faithfulness({ model }),   // sample.context gerektirir — yoksa { score: 0, reason: 'context gerekli: ...' }
  hallucination({ model }),  // needs context; DIRECTION: 1.0 = NO hallucination (good)
  toxicity({ model }),       // needs neither context nor input; it scores the output alone
], { context: retrievedChunks });

Yön semantiği (tüm scorer'larda ortak): yüksek skor = iyi sonuç. Bu, isimden ters sezilebilecek scorer'larda (hallucination, toxicity, bias) kafa karıştırabilir: ör. hallucination skoru 1.0 "halüsinasyon YOK" demektir, "halüsinasyon VAR" değil.

Bağlam gerektiren scorer'lar (faithfulness, hallucination, contextPrecision) sample.context, soru gerektirenler (answerRelevancy, completeness) sample.input ister — eksikse sessizce 1.0 vermez, { score: 0, reason: '...' } döner. Her scorer ayrıca sampleFields ile llmJudge'a hangi ek alanların (input/context) prompt'a ekleneceğini açıkça bildirir — toxicity/bias/toneConsistency bilerek sampleFields: [] kullanır (alakasız bağlamla kirlenmesin diye — ör. bağlam zehirliyse çıktı temiz olsa bile yanlış düşük toxicity skoru çıkmasın).

5) Dataset versiyonlama + deney karşılaştırma — createDatasetsManager, evalDataset'in üstüne journal-tabanlı bir katman ekler: dataset'in versiyon geçmişini tutar, deneyleri (experiment) idempotent kaydeder ve iki deneyi karşılaştırır (regresyon/iyileşme).

import { createDatasetsManager } from '@gnldev/evals';

const manager = createDatasetsManager(journal); // journal 'listKeys' desteklemeli

await manager.saveDataset(dataset);   // no new version is opened when the content is unchanged (hash comparison)

const exp1 = await manager.runExperiment({
  datasetId: 'qa-suite', run: runAgent, scorers: [exactMatch()], experimentId: 'baseline',
});
const exp2 = await manager.runExperiment({
  datasetId: 'qa-suite', run: runAgentV2, scorers: [exactMatch()], experimentId: 'candidate', label: 'yeni prompt',
});
// a second call with the same experimentId does NOT re-run evalDataset — it returns the recorded result (idempotent)

const diff = await manager.compare('qa-suite', 'baseline', 'candidate');
// diff.aggregate -> per scorer { baseline, candidate, delta }
// diff.regressions / diff.improvements -> how many cases got worse or better

Buradaki iki aile hiç model çağırmaz. Dört metin scorer’ı — contentSimilarity, keywordCoverage, textualDifference, answerSimilarity — çıktı ve beklenenin saf fonksiyonlarıdır: maliyet yok, gecikme yok, üzerine düşünülecek non-determinizm yok. Bir LLM-judge’ın hem yavaş hem pahalı olacağı büyük bir regresyon suite’i için doğru varsayılan bunlardır.

Trajectory scorer’ları başka bir soruyu cevaplar: "cevap iyi mi" değil, "ajan makul bir yol izledi mi". createTrajectoryScorer, tool-çağrısı dizisini dört boyuta karşı skorlar — içermesi gereken sıralı bir alt dizi, sırası önemsiz ama bulunması gereken tool’lar, hiç bulunmaması gerekenler, ve bir çağrı bütçesi. Bütçeyi aşmak ya da yasak bir tool’a dokunmak skoru sıfırlamaz, oransal olarak düşürür.

Regresyon diff’inin kullandığı karar dizisinin aynısını okur (buildDecisionSequence); böylece "karar noktası" bütün sistemde tek bir şey demektir, iki pakette birbirine benzeyen iki şey değil.

import { createTrajectoryScorer, trajectoryScorerFor, contentSimilarity } from '@gnldev/evals';

const path = createTrajectoryScorer({
  expectedTools: ['searchDocs', 'summarise'],  // ordered subsequence; extras in between are fine
  requiredTools: ['citeSource'],               // must appear, order irrelevant
  forbiddenTools: ['deleteRecord'],            // a hit degrades the score proportionally
  maxToolCalls: 8,                             // over budget degrades, it does not zero
});

// bound to a reader: the sample carries a runId and the scorer looks the run up
const fromJournal = trajectoryScorerFor(reader, { requiredTools: ['citeSource'] });

await evalDataset({ dataset, run, scorers: [path, contentSimilarity()], journal });