niceeval 0.2.1 → 0.4.0

package/src/report/types.ts

@@ -0,0 +1,210 @@
+// niceeval/report 的公开类型:指标(Metric)、维度(Dimension)与计算函数产物
+// (即 niceeval/report/react 组件的 props)。数据契约照抄 docs/reports.md
+// 「计算函数与数据契约」——这些不是持久化格式,没有 format / schemaVersion 信封;
+// 兼容性跟随 npm 版本。
+
+import type { AttemptHandle } from "../results/types.ts";
+
+// ───────────────────────── 指标与聚合 ─────────────────────────
+
+/** 两级聚合里单级的折叠方式。 */
+export type Aggregator = "mean" | "sum" | "min" | "max" | ((values: number[]) => number);
+
+/**
+ * 两级聚合:「每格 attempt 数相等」是幻觉(earlyExit 让失败的题天然比通过的题样本多),
+ * 平铺求均值会让分数和重试策略纠缠;所以先题内折叠、再跨题折叠,默认宏平均。
+ */
+export interface MetricAggregate {
+  /** 第一级:同一 (eval × 快照) 的多 attempt → 一个题级值;默认 "mean"。 */
+  perEval?: Aggregator;
+  /** 第二级:分组内的题级值 → 格子终值;默认 "mean"。 */
+  across?: Aggregator;
+}
+
+/**
+ * 指标:纯函数,吃一个 AttemptHandle 吐一个值(null = 此 attempt 测不了这个指标,
+ * 不进聚合;0 = 测了结果是零,照常进),外加名字、两级聚合方式和渲染提示。
+ * 内置指标与自定义指标是同一个类型,没有特权。
+ */
+export interface Metric {
+  /** MetricColumn.key 与列头的来源;同一次计算里重名是错误。 */
+  name: string;
+  /** 列头;省略时用 name。 */
+  label?: string;
+  description?: string;
+  /** 渲染提示:越高越好还是越低越好(排序方向、轴向、涨跌配色用)。 */
+  better?: "higher" | "lower";
+  /** 驱动内置格式化:"%" → 87%、"ms" → 1.2s、"$" → $0.31、其余 → 1.2k 缩写。 */
+  unit?: string;
+  /**
+   * 声明式前置:不满足 → null,语义等价于在 value 开头 return null。
+   * 单独设字段是因为这一步最容易忘(忘了它,code-golf 会奖励「写得短的坏代码」)。
+   */
+  where?: (attempt: AttemptHandle) => boolean;
+  value(attempt: AttemptHandle): number | null | Promise<number | null>;
+  aggregate?: MetricAggregate;
+  /** 覆盖 unit 驱动的内置格式化。 */
+  display?: (value: number) => string;
+}
+
+/**
+ * 维度:attempt 分到哪一组。内置维度就是 EvalResult 已有的身份字段;自定义维度是一个函数。
+ * - "evalGroup" = eval id 的第一段:"algebra/quadratic" → "algebra"(考试里的「科目」)
+ * - "snapshot"  = "<experimentId> @ <startedAt>",把两次快照并排成行,与 view 的 Compare 同口径
+ */
+export type Dimension =
+  | "agent"
+  | "model"
+  | "experiment"
+  | "eval"
+  | "evalGroup"
+  | "snapshot"
+  | { name: string; of: (attempt: AttemptHandle) => string };
+
+// ───────────────────────── 计算产物(组件 props)─────────────────────────
+
+export interface MetricColumn {
+  /** = metric.name,与 cells 的键对应。 */
+  key: string;
+  label: string;
+  unit?: string;
+  /** 渲染提示:排序方向、轴向、涨跌配色。 */
+  better?: "higher" | "lower";
+}
+
+export interface MetricCell {
+  /** 聚合后的值;null = 该组没有任何有效样本。 */
+  value: number | null;
+  /** 已格式化("87%" / "1.2k lines" / "$0.31"),前端可直接渲染。 */
+  display: string;
+  /** 有效 attempt 数(值为 null 的不计入)。 */
+  samples: number;
+  /** 组内 attempt 总数;samples < total = 有 attempt 测不了这个指标。 */
+  total: number;
+  /** 这个格子由哪些 attempt 算出 —— 回到证据的引用。 */
+  refs?: AttemptRef[];
+}
+
+// AttemptRef 的家在 niceeval/results:Reports 的 refs、view 深链、copyRun 用同一个证据身份。
+// 这里 import + re-export,公共 API 入口不变。
+import type { AttemptRef } from "../results/types.ts";
+export type { AttemptRef };
+
+export interface TableData {
+  /** 行维度名,如 "agent"。 */
+  dimension: string;
+  columns: MetricColumn[];
+  rows: { key: string; cells: Record<string, MetricCell> }[];
+}
+
+export interface MatrixData {
+  /** 行维度名,如 "eval"。 */
+  rows: string;
+  /** 列维度名,如 "agent"。 */
+  columns: string;
+  metric: MetricColumn;
+  /** 稀疏:没有样本的格子不出现。 */
+  cells: { row: string; column: string; cell: MetricCell }[];
+}
+
+export interface ScoreboardData {
+  /** 被打分的维度名,如 "agent"。 */
+  of: string;
+  fullMarks: number;
+  /** 实际生效的权重表(按匹配顺序:最长前缀在前)—— 成绩单可审计。 */
+  weights: { prefix: string; weight: number }[];
+  rows: {
+    key: string;
+    /** 已折算到 fullMarks。 */
+    total: { value: number; display: string };
+    subjects: {
+      /** 科目(subjects 维度的值)。 */
+      key: string;
+      /** 加权得分。 */
+      earned: number;
+      /** 科目分值合计。 */
+      possible: number;
+      /** 题数。 */
+      evals: number;
+      /** 无任何样本、按 0 计的题数 —— 固定分母的如实注脚。 */
+      missing: number;
+    }[];
+  }[];
+}
+
+export interface ScatterData {
+  /** 点维度名,如 "experiment"。 */
+  points: string;
+  /** 系列维度名,如 "agent"。 */
+  series?: string;
+  /** better: "lower" → 组件反向画轴,「好」的角落恒在右上。 */
+  x: MetricColumn;
+  y: MetricColumn;
+  rows: {
+    /** 点的键,如 "compare/bub-high"。 */
+    key: string;
+    /** 所属系列,如 "bub"。 */
+    series?: string;
+    x: MetricCell;
+    /** 任一为 null 的点组件不画,注脚如实报数(点仍留在 rows 里,可数)。 */
+    y: MetricCell;
+  }[];
+}
+
+export interface OverviewData {
+  snapshots: { experimentId: string; agent: string; model?: string; startedAt: string }[];
+  totals: {
+    evals: number;
+    attempts: number;
+    passed: number;
+    failed: number;
+    errored: number;
+    skipped: number;
+    /** 任一 attempt 报了成本才有;全缺 = null,不编 0。 */
+    costUSD: number | null;
+    durationMs: number;
+  };
+  /** 选择器的警告透传进来,RunOverview 直接渲染 —— 诚实不靠使用者记得渲染。 */
+  warnings: string[];
+}
+
+export interface DeltaData {
+  columns: MetricColumn[];
+  rows: {
+    /** pair 的 label,如 "bub"。 */
+    key: string;
+    /** 基线侧。 */
+    a: { experimentId: string };
+    /** 对比侧。 */
+    b: { experimentId: string };
+    cells: Record<
+      string,
+      {
+        a: MetricCell;
+        b: MetricCell;
+        /** b.value - a.value;任一侧 null → null,不硬算。 */
+        delta: number | null;
+        /** 已带符号("+12%" / "-$0.80"),涨跌好坏由 better 判定。 */
+        display: string;
+      }
+    >;
+  }[];
+}
+
+export interface CaseListData {
+  rows: {
+    eval: string;
+    experimentId: string;
+    agent: string;
+    outcome: "failed" | "errored";
+    /** errored 的错误摘要(已过 redact)。 */
+    error?: string;
+    failedAssertions: { name: string; score: number; detail?: string; evidence?: string }[];
+    durationMs: number;
+    costUSD?: number;
+    /** 每条案例都能回到证据。 */
+    ref: AttemptRef;
+  }[];
+  /** limit 之外还有几条,如实报,不静默截断。 */
+  truncated: number;
+}

package/src/results/copy.ts

@@ -0,0 +1,200 @@
+// copyRun:把选中快照按格式感知地复制到另一个目录(设计见 docs/results-lib.md「复制与瘦身」)。
+//
+// 发布场景的原语:只带指定工件、只带选中的 attempt,布局知识不外泄。
+// 工件复制忠实于源(copyFile 原字节,不重新序列化、不消毒);summary.json 按选中条目重建,
+// 版本元数据保留,榜单计数按选中条目重算 —— 产物是一个 openResults / `niceeval view`
+// 都能直接读的合法 run 目录。
+
+import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import type { EvalResult, RunSummary } from "../runner/types.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../runner/types.ts";
+import type { Usage } from "../o11y/types.ts";
+import { artifactFileOf, attemptDirOf } from "./format.ts";
+import { isNewerRun } from "./select.ts";
+import type { ArtifactKind, AttemptHandle, RunHandle, SnapshotHandle } from "./types.ts";
+import { ARTIFACT_KINDS } from "./types.ts";
+
+export interface CopyRunOptions {
+  /** 要带上的工件种类;省略 = 全部五类。diff 可达百 MB、o11y 查看器不读,发布时常见地不带。 */
+  artifacts?: ArtifactKind[];
+}
+
+export interface CopiedRun {
+  /** 目标 run 目录的绝对路径(summary.json 所在目录)。 */
+  dir: string;
+  /** 重建后的 summary(与写入磁盘的一致)。 */
+  summary: RunSummary;
+  /** 复制过程中的警告(如多个 attempt 落到同一目录);不静默。 */
+  warnings: string[];
+}
+
+/**
+ * 把 `snapshots` 里的全部 attempt 复制成 `destDir` 下的一个 run 目录。
+ * 快照可以来自不同物理 run(latestPerExperiment 的典型输出);两个 attempt 落到同一
+ * 工件目录时保留最新 run 的那份并出 warning —— 复制前先 dedupeAttempts 可避免。
+ */
+export async function copyRun(
+  snapshots: SnapshotHandle | SnapshotHandle[],
+  destDir: string,
+  opts?: CopyRunOptions,
+): Promise<CopiedRun> {
+  const selected = Array.isArray(snapshots) ? snapshots : [snapshots];
+  if (selected.length === 0) {
+    throw new Error(
+      "copyRun got no snapshots to copy. Check the experiments filter, or pass snapshots from openResults()/latestPerExperiment().",
+    );
+  }
+  const kinds = opts?.artifacts ?? [...ARTIFACT_KINDS];
+  const dest = resolve(destDir);
+
+  const sourceRuns = uniqueRuns(selected);
+  for (const run of sourceRuns) {
+    if (resolve(run.dir) === dest) {
+      throw new Error(`copyRun destination ${dest} is a source run directory. Pick a different destination.`);
+    }
+  }
+
+  // 第一趟:按目标工件目录选出胜者(最新 run 的那份),顺序取首次出现处 —— 两趟避免
+  // 「旧的先落盘、新的再去清理覆盖」的中间态。
+  const winners = new Map<string, AttemptHandle>();
+  const order: string[] = [];
+  const warnings: string[] = [];
+  for (const snapshot of selected) {
+    for (const attempt of snapshot.attempts) {
+      const relDir = attemptDirOf(attempt.result);
+      const existing = winners.get(relDir);
+      if (!existing) {
+        winners.set(relDir, attempt);
+        order.push(relDir);
+        continue;
+      }
+      warnings.push(
+        `warning: multiple attempts map to "${relDir}" in the copied run; kept the one from the newest run. Dedupe attempts or re-select snapshots before copyRun to avoid this.`,
+      );
+      if (isNewerRun(attempt.run, existing.run)) winners.set(relDir, attempt);
+    }
+  }
+
+  // 第二趟:复制工件 + 生成瘦身条目(has* 按目标目录里真的有什么重算)。
+  await mkdir(dest, { recursive: true });
+  const results: EvalResult[] = [];
+  for (const relDir of order) {
+    const attempt = winners.get(relDir)!;
+    const files = await findArtifactFiles(attempt, kinds);
+    if (files.length > 0) {
+      const attemptDest = join(dest, relDir);
+      await mkdir(attemptDest, { recursive: true });
+      await Promise.all(files.map(({ kind, source }) => copyFile(source, join(attemptDest, artifactFileOf(kind)))));
+    }
+    const copied = new Set(files.map((f) => f.kind));
+    results.push(slimForCopy(attempt.result, relDir, copied));
+  }
+
+  const summary = rebuildSummary(selected, sourceRuns, results, dest);
+  await writeFile(join(dest, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
+  return { dir: dest, summary, warnings };
+}
+
+/** 源工件定位:与读取面同一候选顺序(本 run 的 artifactsDir 优先,artifactBase 回退)。 */
+async function findArtifactFiles(
+  attempt: AttemptHandle,
+  kinds: ArtifactKind[],
+): Promise<{ kind: ArtifactKind; source: string }[]> {
+  const candidates: string[] = [];
+  if (attempt.result.artifactsDir) candidates.push(join(attempt.run.dir, attempt.result.artifactsDir));
+  if (attempt.result.artifactBase) candidates.push(join(dirname(attempt.run.dir), attempt.result.artifactBase));
+
+  const found: { kind: ArtifactKind; source: string }[] = [];
+  for (const kind of kinds) {
+    for (const dir of candidates) {
+      const source = join(dir, artifactFileOf(kind));
+      try {
+        if ((await stat(source)).isFile()) {
+          found.push({ kind, source });
+          break;
+        }
+      } catch {
+        // 缺文件跳过:某类数据为空本来就不生成对应 JSON(docs/results-format.md)。
+      }
+    }
+  }
+  return found;
+}
+
+/** 瘦身条目:去掉内联大字段与 view 注入的路径字段,artifactsDir / has* 按目标目录重算。 */
+function slimForCopy(r: EvalResult, relDir: string, copied: Set<ArtifactKind>): EvalResult {
+  const { events, sources, o11y, trace, diff, rawTranscript, artifactBase, artifactAbsBase, ...rest } = r;
+  void events;
+  void sources;
+  void o11y;
+  void trace;
+  void diff;
+  void rawTranscript;
+  void artifactBase;
+  void artifactAbsBase;
+  return {
+    ...rest,
+    artifactsDir: relDir,
+    hasEvents: copied.has("events"),
+    hasTrace: copied.has("trace"),
+    hasSources: copied.has("sources"),
+  };
+}
+
+function rebuildSummary(
+  selected: SnapshotHandle[],
+  sourceRuns: RunHandle[],
+  results: EvalResult[],
+  dest: string,
+): RunSummary {
+  // 版本元数据与 run 级元数据取最新源 run 的(producer 缺失的 legacy 源保持缺失,不冒充)。
+  let newest = sourceRuns[0];
+  for (const run of sourceRuns) if (isNewerRun(run, newest)) newest = run;
+
+  const counts = { passed: 0, failed: 0, skipped: 0, errored: 0 };
+  for (const r of results) counts[r.outcome] += 1;
+
+  return {
+    format: RESULTS_FORMAT,
+    schemaVersion: RESULTS_SCHEMA_VERSION,
+    ...(newest.summary.producer ? { producer: newest.summary.producer } : {}),
+    ...(newest.summary.name !== undefined ? { name: newest.summary.name } : {}),
+    // 顶层 agent/model 沿用 runner 的「第一个配置」姿势;快照各自的 agent 在条目里。
+    agent: selected[0].agent,
+    ...(selected[0].model !== undefined ? { model: selected[0].model } : {}),
+    startedAt: newest.summary.startedAt,
+    completedAt: newest.summary.completedAt,
+    ...counts,
+    // 跨 run 拼装无法还原墙钟时长,这里是选中 attempt 的耗时合计。
+    durationMs: results.reduce((total, r) => total + (r.durationMs ?? 0), 0),
+    ...usageAndCost(results),
+    results,
+    outputDir: dest,
+  };
+}
+
+/** usage / 成本按选中条目重算;口径同 runner 的 summarize(没有任何 usage 就不写)。 */
+function usageAndCost(results: EvalResult[]): Pick<RunSummary, "usage" | "estimatedCostUSD"> {
+  const usages = results.map((r) => r.usage).filter((u): u is Usage => u !== undefined);
+  const cost = results.reduce((total, r) => total + (r.estimatedCostUSD ?? 0), 0);
+  if (usages.length === 0) return { estimatedCostUSD: cost || undefined };
+  const usage: Usage = { inputTokens: 0, outputTokens: 0 };
+  for (const u of usages) {
+    usage.inputTokens += u.inputTokens;
+    usage.outputTokens += u.outputTokens;
+    for (const key of ["cacheReadTokens", "cacheWriteTokens", "requests", "costUSD"] as const) {
+      const value = u[key];
+      if (value !== undefined) usage[key] = (usage[key] ?? 0) + value;
+    }
+  }
+  return { usage, estimatedCostUSD: cost || undefined };
+}
+
+function uniqueRuns(snapshots: SnapshotHandle[]): RunHandle[] {
+  const runs: RunHandle[] = [];
+  for (const snapshot of snapshots) {
+    if (!runs.includes(snapshot.run)) runs.push(snapshot.run);
+  }
+  return runs;
+}

package/src/results/format.ts

@@ -0,0 +1,75 @@
+// Results Format 的布局与版本知识(读取面),规则见 docs/results-format.md。
+//
+// 版本判定与 src/view/loader.ts 的 normalizeSummary 同一口径(view 抛错驱动 CLI 提示,
+// 这里返回分类值驱动 skipped 列表);attempt 目录规则与 src/runner/reporters/artifacts.ts
+// 的 attemptDir 同一规则。按 results-lib 设计,这份知识最终应只住在本库,
+// view / reporter 改吃这里是后续收编步骤 —— 本实验不动它们的代码。
+
+import type { EvalResult, RunSummary } from "../runner/types.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../runner/types.ts";
+import type { ArtifactKind } from "./types.ts";
+
+/** attempt 工件子目录(相对 run 根):<evalId>/<agent>/<model>[/<experimentId>]/a<attempt>。 */
+export function attemptDirOf(r: Pick<EvalResult, "id" | "agent" | "model" | "attempt" | "experimentId">): string {
+  const safe = (s: string) => s.replace(/[^\w.@-]/g, "_");
+  // evalId 里的 / 保留作目录层级,其余危险字符替换。
+  const id = r.id.replace(/[^\w./@-]/g, "_");
+  // experiment 段与 writer(artifacts.ts 的 attemptDir)同一规则:两个实验可以同 agent 同 model、
+  // 只差 flags,少这一段它们的工件会互相覆盖;experimentId 里的 / 不作层级(整段压成 _)。
+  const exp = r.experimentId ? `/${safe(r.experimentId)}` : "";
+  return `${id}/${safe(r.agent)}/${safe(r.model ?? "default")}${exp}/a${r.attempt}`;
+}
+
+/** 工件文件名:种类即文件名。 */
+export function artifactFileOf(kind: ArtifactKind): string {
+  return `${kind}.json`;
+}
+
+/** summary.json 的版本判定结果;openResults 按它分流 ok / skipped / 静默忽略。 */
+export type SummaryClassification =
+  | { kind: "ok"; summary: RunSummary }
+  | { kind: "incompatible"; schemaVersion: number; producerVersion?: string }
+  | { kind: "malformed"; detail: string }
+  | { kind: "not-a-report" };
+
+/**
+ * 版本判定与最小形状校验(docs/results-format.md「版本不匹配时的读取行为」):
+ * - 带 format 信封:format 不是 niceeval.results → 无关 JSON;schemaVersion 与当前不同 →
+ *   不兼容(不解析、不迁移、不降级),缺 schemaVersion 的早期信封按 1 处理。
+ * - 无信封:results[] 与 startedAt 同时具备才按 legacy 照读(未知字段忽略);
+ *   只沾到一个键的多半是别家工具的 summary.json,按规范当无关 JSON 忽略,不进 skipped 制造噪音。
+ */
+export function classifySummary(raw: unknown): SummaryClassification {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { kind: "malformed", detail: "not a JSON object" };
+  }
+  const data = raw as Partial<RunSummary>;
+  if (data.format !== undefined && data.format !== RESULTS_FORMAT) return { kind: "not-a-report" };
+  if (data.format === RESULTS_FORMAT) {
+    const version = data.schemaVersion ?? 1;
+    if (typeof version !== "number") return { kind: "malformed", detail: "schemaVersion is not a number" };
+    if (version !== RESULTS_SCHEMA_VERSION) {
+      return { kind: "incompatible", schemaVersion: version, producerVersion: data.producer?.version };
+    }
+    if (!Array.isArray(data.results) || typeof data.startedAt !== "string") {
+      return { kind: "malformed", detail: "missing results[] or startedAt" };
+    }
+    return { kind: "ok", summary: data as RunSummary };
+  }
+  if (!Array.isArray(data.results) || typeof data.startedAt !== "string") {
+    return { kind: "not-a-report" };
+  }
+  return { kind: "ok", summary: data as RunSummary };
+}
+
+/**
+ * 快照/去重共用的 experiment 身份键:experimentId 缺失时以 "<agent>/<model>" 合成
+ * (无 model 用 "default",与工件目录命名同一口径),synthesized 供调用方决定要不要出 warning。
+ */
+export function experimentKeyOf(r: Pick<EvalResult, "experimentId" | "agent" | "model">): {
+  id: string;
+  synthesized: boolean;
+} {
+  if (r.experimentId) return { id: r.experimentId, synthesized: false };
+  return { id: `${r.agent}/${r.model ?? "default"}`, synthesized: true };
+}

package/src/results/index.ts

@@ -0,0 +1,27 @@
+// niceeval/results —— 实验结果数据的读写库(设计见 docs/results-lib.md)。
+//
+// 本实验先落读取面:openResults / latestPerExperiment / dedupeAttempts / copyRun。
+// TODO(results-lib): 写入面 createRunWriter 落地后,src/runner/reporters/artifacts.ts
+// 变薄壳、src/view/loader.ts 改吃这里的 reader —— 布局知识全宇宙只剩这一份实现。
+
+export { openResults } from "./open.ts";
+export { dedupeAttempts, latestPerExperiment } from "./select.ts";
+export { copyRun, type CopiedRun, type CopyRunOptions } from "./copy.ts";
+export {
+  ARTIFACT_KINDS,
+  type ArtifactKind,
+  type AttemptHandle,
+  type AttemptRef,
+  type ResultsCollection,
+  type RunHandle,
+  type SkippedResultsRun,
+  type SnapshotHandle,
+} from "./types.ts";
+
+// 结果数据类型的家还没搬(类型迁移是设计里单独的一步);先从这里 re-export,
+// 让消费方从一个入口拿全「句柄 + 数据类型 + 格式常量」。
+export { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../runner/types.ts";
+export type { EvalResult, ExperimentRunInfo, RunSummary } from "../runner/types.ts";
+export type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+export type { DiffData } from "../scoring/types.ts";
+export type { SourceArtifact } from "../shared/types.ts";