Eval kapısı (promote yönetişimi)

Agent versiyonlama ile bir agent'ın birden çok sürümü journal'da tutulur ve dilediğiniz sürüm promote ile aktif edilir. Ama "yeni system prompt'u/modeli üretime aç" kararı insan takdirine bırakılırsa regresyon riski vardır. evalGate, bunu otomatikleştirir: createStudioApp'a bir { datasetId, minAvg } verildiğinde, her promote isteği ÖNCE o eval dataset suite'ini koşturur; suite'in tüm aggregate skorları minAvg eşiğini geçmezse promote 412 ile reddedilir — sürüm aktif olmaz.

Tipik senaryo: production agent'ınız için bir regresyon dataset'i (ör. sık sorulan sorular + beklenen cevaplar) tanımlarsınız; bir mühendis yeni bir system prompt sürümü ekleyip promote etmeye çalıştığında, suite geçmezse Studio bunu otomatik engeller — kararın kendisi de (geçti/kaldı + aggregate skorlar) audit log'a agent.gate olayı olarak düşer, kim ne zaman denedi kalıcı iz bırakır.

evalGate ayrı bir paket değil — @gnldev/studio'nun createStudioApp (veya createStudioApi) çağrısına verilen bir seçenektir. Devreye girmesi için aynı çağrıya bir datasets (StudioDatasets sözleşmesi) sağlamanız ŞARTTIR — datasets yoksa promote isteği 501 döner.

import { createStudioApp } from '@gnldev/studio';
import type { StudioDatasets, EvalDatasetResultLike } from '@gnldev/studio';
import { evalDataset } from '@gnldev/evals';

1) StudioDatasets sözleşmesini uygulayın — Studio çekirdeği @gnldev/evals'a bağımlı değildir; siz datasets.run(id) içinde evalDataset'i çağırıp EvalDatasetResultLike ile yapısal olarak uyumlu bir sonuç döndürürsünüz:

const datasets: StudioDatasets = {
  list: () => [{ id: 'regression', cases: 12, description: 'Frequently asked questions' }],
  run: async (id) => {
    const report = await evalDataset({
      dataset: regressionDataset, // { id: 'regression', cases: [...] }
      run: async (input, { runId }) => gnl.run('starwars', { runId, prompt: input }),
      scorers: [exactMatch()],
      journal,
    });
    return report; // { datasetId, cases, aggregate }
  },
};

2) evalGate'i createStudioApp'a verin — datasetId hangi suite'in koşulacağını, minAvg (varsayılan 0.5) geçme eşiğini belirler:

app.route('/studio', createStudioApp({
  reader: toJournal(storage.runs),
  gnl: createStudioRunner(gnl, config, { toJsonSchema: aiToolSchema }),
  datasets,                                     // required — without it evalGate returns 501
  evalGate: { datasetId: 'regression', minAvg: 0.7 },
  auth,
}));

3) Promote isteği artık kapıdan geçer — POST /managed-agents/:name/promote çağrıldığında Studio önce datasets.run('regression')'ı koşturur; her aggregate skor 0.7'nin altındaysa (`failing`) istek 412 ile reddedilir, hiçbiri altında değilse sürüm aktif edilir:

POST /studio/api/managed-agents/starwars/promote
{ "version": 3 }

// 412 Precondition Failed
{
  "error": "the eval gate FAILED: exact-match=0.42<0.7 — promotion refused",
  "aggregate": { "exact-match": 0.42 }
}
// an 'agent.gate' event lands in the audit log: { version: 3, datasetId: 'regression', minAvg: 0.7, aggregate, passed: false }

POST /studio/api/managed-agents/starwars/promote
{ "version": 3 }

// 200 OK
{ "ok": true, "name": "starwars", "active": 3, "previous": 2 }
// 'agent.gate' (passed: true) lands in the audit log first, then 'agent.promote'