niceeval 0.6.2 → 0.7.0

package/dist/report/compute.d.ts

@@ -1,99 +1,112 @@
-import type { AttemptListItem, AxisInput, DeltaData, DimensionInput, EvalListItem, ExperimentListItem, GroupSummaryData, LineData, MatrixData, Metric, OverviewData, ScatterData, ScoreboardData, TableData } from "./types.ts";
-import type { EvalResult } from "../types.ts";
-import { type SnapshotsInput } from "./aggregate.ts";
-export interface TableDataOptions<M extends readonly Metric[]> {
-    /** 行维度(内置 / 自定义 / flag())。 */
+import type { AttemptListItem, DeltaData, DeltaPair, DimensionInput, EntityListDataOptions, EvalListItem, ExperimentComparisonData, ExperimentListItem, FlagPairs, LineData, MatrixData, Metric, NumericAxis, ReportInput, ScatterData, ScopeSummaryData, ScoreboardData, TableData } from "./types.ts";
+import type { JsonValue } from "../types.ts";
+export interface MetricTableOptions {
+    /** 行维度(内置 / 自定义 / flag() / runConfig())。 */
     rows: DimensionInput;
-    /** 每列一个指标;列键 = metric.name 的字面量,拼错编译不过。 */
-    columns: M;
-    /** 构建时排序,方向随 better(higher 降序,「好」的一头在上);缺数据行沉底。两面同口径,预排即终排。 */
-    sort?: Metric;
-    /** eval id 前缀过滤,同 CLI 位置参数语义。 */
-    evals?: string | string[];
-}
-/** 一次 attempt 的有界结果摘要：error → skipReason → 一条主失败断言 + 其余失败计数。 */
-export declare function reasonFor(result: EvalResult): string | undefined;
-export declare function tableData<const M extends readonly Metric[]>(input: SnapshotsInput, opts: TableDataOptions<M>): Promise<TableData<M[number]["name"]>>;
-export interface AttemptListDataOptions {
+    /** 每列一个指标;非空元组,元素是静态 import 的 Metric 实例。 */
+    columns: readonly [Metric, ...Metric[]];
     /**
-     * 展示层遮蔽:error 的 message/cause/stack、diagnostic 的 message/data、断言 detail 与
-     * evidence 经这个钩子;experimentId、evalId、locator、error/diagnostic code 与 lifecycle
-     * operation 等身份和分类字段不经它。只作用于这次计算产出的组件数据,不改盘上 artifact。
+     * 初始行序:必须是 columns 中同一个 Metric 实例且声明了 better,方向随 better
+     * (「好」的一头在上),缺数据行沉底;省略时按行 key 字典序。
      */
-    redact?: (text: string) => string;
+    sort?: Metric;
+    /** eval id 前缀过滤,同 CLI 位置参数语义;在聚合之前收窄题集。 */
+    evals?: string | readonly string[];
 }
-/** `AttemptList.data(selection)`:每个 Attempt 一项,顺序取自 Selection 展平顺序(不重排)。 */
-export declare function attemptListData(input: SnapshotsInput, opts?: AttemptListDataOptions): Promise<AttemptListItem[]>;
-/** `EvalList.data(selection)`:每个 `experimentId + evalId` 一项,按 evalId 再按 experimentId 升序。 */
-export declare function evalListData(input: SnapshotsInput): Promise<EvalListItem[]>;
-/** `ExperimentList.data(selection)`:每个 experiment 一项,按 experimentId 升序;展开到每道 Eval。 */
-export declare function experimentListData(input: SnapshotsInput): Promise<ExperimentListItem[]>;
-export interface MatrixDataOptions {
+export declare function metricTableData(input: ReportInput, options: MetricTableOptions): Promise<TableData>;
+export interface MetricMatrixOptions {
     rows: DimensionInput;
     columns: DimensionInput;
     cell: Metric;
     /** eval id 前缀过滤,同 CLI 位置参数语义。 */
-    evals?: string | string[];
+    evals?: string | readonly string[];
 }
-export declare function matrixData(input: SnapshotsInput, opts: MatrixDataOptions): Promise<MatrixData>;
-export interface ScoreboardDataOptions {
-    /** 给谁打分(被打分的维度);维度槽与 MetricTable.data 统一叫 rows。 */
+export declare function metricMatrixData(input: ReportInput, options: MetricMatrixOptions): Promise<MatrixData>;
+/** `attemptListData(input)`:每个 Attempt 一项,顺序取自 Scope 展平顺序(不重排)。 */
+export declare function attemptListData(input: ReportInput, options?: EntityListDataOptions): Promise<AttemptListItem[]>;
+/** `evalListData(input)`:每个 `experimentId + evalId` 一项,按 evalId 再按 experimentId 升序。 */
+export declare function evalListData(input: ReportInput, options?: EntityListDataOptions): Promise<EvalListItem[]>;
+/**
+ * `experimentListData(input)`:每个 experiment 一项,展开到每道 Eval;初始按端到端成功率
+ * 从高到低(缺数据沉底,同分按 id)。一行只有一套 agent / model / flags 是输入约束:
+ * 宿主注入的 current() Scope 保证每个 experiment 只由可比性配置一致的快照拼成;作者自选
+ * Snapshot[] 时若同一 experiment 混入不一致的可比性配置,按完整用户反馈失败并指引——
+ * 看跨配置演化用 snapshot 维度或 MetricLine,不把两套配置拼成一行冒充单一配置。
+ */
+export declare function experimentListData(input: ReportInput, options?: EntityListDataOptions): Promise<ExperimentListItem[]>;
+/**
+ * `scopeSummaryData(input)`:范围摘要——快照时间窗、experiment / eval / attempt 数、
+ * 两级判定计票、端到端成功率与总成本(docs/feature/reports/library/summaries.md)。
+ * data 恒携带两级计票;成功率来自官方两级指标引擎,不从任一计票重算。
+ */
+export declare function scopeSummaryData(input: ReportInput): Promise<ScopeSummaryData>;
+/** 完整父路径是组键;没有父路径的 experiment 不能互相比,自己形成单例组。 */
+export declare function experimentComparisonGroupKey(experimentId: string): string;
+/**
+ * `experimentComparisonData(input)`:先把 input 按可比组分区(experiment id 的完整父路径),
+ * 再为每组分别计算 ScopeSummary、成本 × 端到端成功率散点和 ExperimentList——分区发生在任何
+ * 指标计算之前,组外 attempt 不可能污染该组的坐标尺度、series、成功率、成本、排序或缺数据计数。
+ */
+export declare function experimentComparisonData(input: ReportInput): Promise<ExperimentComparisonData>;
+export interface ScoreboardOptions {
     rows: DimensionInput;
-    /** 按什么分科;默认 "evalGroup"(考试里的「科目」)。 */
-    subjects?: DimensionInput;
-    /** eval id 前缀 → 每题分值;未列默认 1;前缀重叠时最长的生效。 */
-    weights?: Record<string, number>;
-    /** 折算满分;默认 100。 */
+    /** 固定题集;eval id 必须唯一。元素引用运行时数据,类型放宽为普通数组,空数组在计算时报错。 */
+    questions: readonly string[];
+    /** 分科函数;默认与 evalGroup 维度同一条规则:取 eval id 的完整父路径,无 `/` 取完整 id。 */
+    subject?: (evalId: string) => string;
+    /** 权重按 eval id 前缀匹配,多个命中时最长前缀生效;默认 1。 */
+    weights?: Readonly<Record<string, number>>;
     fullMarks?: number;
-    /** 每题得分指标;缺省即 examScore,可换自定义(如「答对但超预算扣分」)。 */
     score?: Metric;
-    /** 选中范围:eval id 前缀过滤;题集(分母)只遍历这个范围。 */
-    evals?: string | string[];
 }
 /**
- * 逐题分值制,分母对所有被打分者恒定:
- *   题分值 = 命中的权重(默认 1)   题得分 = score 指标的题级值(perEval 折叠后)
- *   总分   = fullMarks × Σ(题得分 × 题分值) / Σ(题分值)   Σ 遍历选中范围内全部题
- * 没跑到的题挣 0 分但留在分母里,missing 如实报 —— 这是显式的考试契约,不是「null ≠ 0」的例外。
+ * 固定题集分母:未跑题按 0 分计入 `notRun`,跑了但指标为 null 的题按 0 分计入 `unscorable`,
+ * 两个计数不合并——成绩单能回答「这 0 分是没去考还是考了判不了」。组件不从已观测 attempt
+ * 的并集猜分母;Scope 中题集之外的 eval 被忽略并计入 `ignoredEvals`。
  */
-export declare function scoreboardData(input: SnapshotsInput, opts: ScoreboardDataOptions): Promise<ScoreboardData>;
-export interface ScatterDataOptions {
+export declare function scoreboardData(input: ReportInput, options: ScoreboardOptions): Promise<ScoreboardData>;
+export interface MetricScatterOptions {
     /** 点维度:每个点 = 该组 attempt 的聚合。 */
     points: DimensionInput;
-    /** 可选:同系列的点连成线;省略 = 纯散点。 */
+    /** 可选:只决定颜色和分组,默认不连线。 */
     series?: DimensionInput;
     x: Metric;
     y: Metric;
+    /** eval id 前缀过滤,同 CLI 位置参数语义。 */
+    evals?: string | readonly string[];
 }
-export declare function scatterData(input: SnapshotsInput, opts: ScatterDataOptions): Promise<ScatterData>;
-export interface LineDataOptions {
-    /** x 轴:experiment 声明的 flag 或顶层运行配置 config()(要求数值),不解析 experiment 命名。 */
-    x: AxisInput;
-    y: Metric;
-    /** 可选:每个系列一条线(flag / config 或普通维度);省略 = 单系列。 */
+export declare function metricScatterData(input: ReportInput, options: MetricScatterOptions): Promise<ScatterData>;
+export interface MetricLineOptions {
+    /** x 轴:NumericAxis(numericFlag() / numericRunConfig() 或自定义 of),不解析 experiment 命名。 */
+    x: NumericAxis;
     series?: DimensionInput;
+    y: Metric;
+    /** eval id 前缀过滤,同 CLI 位置参数语义。 */
+    evals?: string | readonly string[];
 }
-/** 每个点 = 一个 experiment 的聚合;同系列的点按 x 排序连线(排序在组件面,数据保持分组序)。 */
-export declare function lineData(input: SnapshotsInput, opts: LineDataOptions): Promise<LineData>;
-/** Selection 的 warnings 随行进 OverviewData,RunOverview 直接渲染 —— 诚实不靠使用者记得接线。 */
-export declare function overviewData(input: SnapshotsInput): Promise<OverviewData>;
 /**
- * 一组 experiment 的摘要:experiment/eval/attempt 数量、eval 级折叠计票、通过率(旧
- * `GroupSelector` 卡片口径,见 summarizeItems)、总成本(null-safe 求和)、最后运行时间
- * (组内快照 startedAt 最大值)。`input` 就是调用方已经收窄好的组 Selection(如自定义报告
- * 按 experiment 组前缀 filter 出来的那份)——本函数不再自己分组。
+ * 点身份 = (series, x):落进同一桶的全部 attempt 先在各自 experiment × eval 内 perEval 聚合,
+ * 再 acrossEvals 跨题折成该点唯一的 y——聚合顺序是 (series, x, experiment, eval),同一桶里有
+ * 多个 experiment 时它们合成一个点,不画垂直来回线。前提是 x 在同一 experiment × eval 内恒定:
+ * 自定义 NumericAxis.of() 对同一 experiment × eval 的不同 attempt 返回不同值时按完整用户反馈失败。
+ * x 为 null 的 attempt 不伪造 x 值,归入该 series 的未绘制行,组件报告未绘制数量。
  */
-export declare function groupSummaryData(input: SnapshotsInput): Promise<GroupSummaryData>;
-export interface DeltaPair {
-    /** 基线侧:experiment id,或快照键 "<experimentId> @ <startedAt>"(时间轴对比用手挑的快照数组)。 */
-    a: string;
-    /** 对比侧,同上。 */
-    b: string;
-    label?: string;
-}
-export interface DeltaDataOptions<M extends readonly Metric[]> {
-    /** 每行一对:B 相对 A。 */
-    pairs: DeltaPair[];
-    metrics: M;
+export declare function metricLineData(input: ReportInput, options: MetricLineOptions): Promise<LineData>;
+/**
+ * 按 flag 派生 A/B 对(docs/feature/reports/library/metric-views.md「DeltaTable」):
+ * 配对域 = 同可比组 + 删除该 flag 后可比性配置深相等;a 取 baseline(缺省 = 未声明该 flag),
+ * b 侧该 flag 的每个其它取值各成一对;label 自动 `<a 末段> · <flag>=<显示键>`。
+ */
+export declare function pairsByFlag(name: string, options?: {
+    baseline?: JsonValue;
+}): FlagPairs;
+export interface DeltaTableOptions {
+    /** 显式维度,必填——"baseline" 不会被猜成 experiment、agent、flag 或 snapshot 中的某一种。 */
+    by: DimensionInput;
+    /** 字面 pair 数组(自定义 label),或 pairsByFlag() 的派生声明;空数组在计算时报错。 */
+    pairs: readonly DeltaPair[] | FlagPairs;
+    metrics: readonly [Metric, ...Metric[]];
+    /** eval id 前缀过滤,同 CLI 位置参数语义。 */
+    evals?: string | readonly string[];
 }
-export declare function deltaData<const M extends readonly Metric[]>(input: SnapshotsInput, opts: DeltaDataOptions<M>): Promise<DeltaData<M[number]["name"]>>;
+export declare function deltaTableData(input: ReportInput, options: DeltaTableOptions): Promise<DeltaData>;