aeval-framework 0.1.0__tar.gz → 0.3.0__tar.gz

aeval_framework-0.3.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.db
+*.sqlite3
+.coverage
+
+# Node / Next.js (dashboard)
+node_modules/
+.next/
+out/
+*.tsbuildinfo
+
+# Env & OS
+.env
+.env.*
+.DS_Store
+Thumbs.db
+
+# Editor-local state (Qoder)
+.qoder/
+
+# AI tool state
+.claude/
+.codex/
+.meituan-catpaw/
+
+# Run artifacts & scratch notes
+.live-run-output.txt
+testlist.txt
+
+# Personal (never commit)
+docs/eval-harness-interview-prep.md

{aeval_framework-0.1.0 → aeval_framework-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: aeval-framework
-Version: 0.1.0
+Version: 0.3.0
 Summary: Aeval — open-source agent evaluation framework driven by OTel traces (suites, graders, metrics, storage, API, CLI)
 Project-URL: Homepage, https://github.com/QiYuyyds/Aeval
 Project-URL: Repository, https://github.com/QiYuyyds/Aeval
 Project-URL: Documentation, https://github.com/QiYuyyds/Aeval/tree/main/docs
-Project-URL: Changelog, https://github.com/QiYuyyds/Aeval/releases
+Project-URL: Changelog, https://github.com/QiYuyyds/Aeval/blob/main/CHANGELOG.md
 Author: Aeval contributors
 License: MIT
 Keywords: agents,evaluation,llm,otel,testing,tracing

{aeval_framework-0.1.0 → aeval_framework-0.3.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name: aeval-framework (PyPI). Python module: agent_eval, CLI: eval-suite.
 # (`agent-eval` on PyPI belongs to an unrelated project — UK AISI agenteval.)
 name = "aeval-framework"
-version = "0.1.0"
+version = "0.3.0"
 description = "Aeval — open-source agent evaluation framework driven by OTel traces (suites, graders, metrics, storage, API, CLI)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -52,7 +52,7 @@ eval-suite = "agent_eval.cli:main"
 Homepage = "https://github.com/QiYuyyds/Aeval"
 Repository = "https://github.com/QiYuyyds/Aeval"
 Documentation = "https://github.com/QiYuyyds/Aeval/tree/main/docs"
-Changelog = "https://github.com/QiYuyyds/Aeval/releases"
+Changelog = "https://github.com/QiYuyyds/Aeval/blob/main/CHANGELOG.md"
 
 [build-system]
 requires = ["hatchling"]
@@ -60,6 +60,9 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/agent_eval"]
+# src/agent_eval/packs/** (含 starter pack 的 suite.yaml/manifest.json) 作为
+# package data 随 wheel 分发 —— `eval-suite run demo` 的零 setup 首跑依赖它;
+# 仓库 packs/starter/ 与之同源, tests/test_packaging.py 钉住两侧一致。
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{aeval_framework-0.1.0 → aeval_framework-0.3.0}/src/agent_eval/__init__.py

@@ -11,4 +11,4 @@ Usage:
     result = await runner.run_suite(suite)
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

aeval_framework-0.3.0/src/agent_eval/api/app.py

@@ -0,0 +1,218 @@
+"""
+FastAPI application factory for Aeval.
+
+Creates a FastAPI app with all eval routes mounted.
+Can be used standalone or mounted in an existing app.
+
+Usage:
+    # Standalone
+    app = create_app(runner=my_runner)
+
+    # Mounted in existing FastAPI app
+    from fastapi import FastAPI
+    app = FastAPI()
+    eval_app = create_app(runner=my_runner)
+    app.mount("/api/eval", eval_app)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI
+
+from agent_eval.api.routes import datasets, graders, metrics, runs, suites, tasks
+from agent_eval.core.metrics import MIN_ALIGNED_RATINGS_FOR_AGREEMENT
+from agent_eval.core.runner import EvalRunner
+from agent_eval.core.types import (
+    DEFAULT_BOOTSTRAP_ROUNDS,
+    DEFAULT_CONFIDENCE_LEVEL,
+    DEFAULT_INVALID_RATIO_LIMIT,
+    MIN_VALID_TRIALS_FOR_SATURATION,
+    STATISTICS_VERSION,
+)
+from agent_eval.graders import get_grader_catalog
+from agent_eval.trace.mapping import (
+    ATTRIBUTE_MAPPING_VERSION,
+    OTEL_GENAI_SPEC_VERSION,
+    VOCABULARY_OTEL_GENAI,
+    VOCABULARY_SPEC_VERSIONS,
+    known_vocabularies,
+)
+
+# Global runner reference (set by create_app)
+_runner: EvalRunner | None = None
+
+
+def _get_runner() -> EvalRunner | None:
+    """Get the global EvalRunner instance"""
+    return _runner
+
+
+def set_runner(runner: EvalRunner | None) -> None:
+    """Set the global EvalRunner instance.
+
+    Used by the host app to inject the real runner during async startup
+    (e.g. main.py lifespan → eval_integration.config.create_aeval_runner).
+    """
+    global _runner
+    _runner = runner
+
+
+DISTRIBUTION_NAME = "aeval-framework"  # PyPI 发行包名 (Python 模块为 agent_eval)
+
+
+def package_version() -> str:
+    """包版本: 优先取已安装元数据, 源码直跑时回退模块常量。"""
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _metadata_version
+
+    try:
+        return _metadata_version(DISTRIBUTION_NAME)
+    except PackageNotFoundError:
+        from agent_eval import __version__
+
+        return __version__
+
+
+def statistics_defaults() -> dict[str, Any]:
+    """统计口径版本与 D7 数值默认值 (经元信息接口公布, 供调用方判断可比性)。"""
+    return {
+        "version": STATISTICS_VERSION,
+        "confidence_level": DEFAULT_CONFIDENCE_LEVEL,
+        "bootstrap_rounds": DEFAULT_BOOTSTRAP_ROUNDS,
+        "min_valid_trials_for_saturation": MIN_VALID_TRIALS_FOR_SATURATION,
+        "gate_invalid_ratio_limit": DEFAULT_INVALID_RATIO_LIMIT,
+        "min_aligned_ratings_for_agreement": MIN_ALIGNED_RATINGS_FOR_AGREEMENT,
+    }
+
+
+def meta_payload(
+    api_prefix: str = "",
+    endpoints: list[str] | None = None,
+    version: str | None = None,
+) -> dict[str, Any]:
+    """元信息响应体: 版本 + 统计口径 + 能力清单。
+
+    同一大版本内响应结构向后兼容, 但统计口径的数值语义可能变化 —— 口径版本
+    必须显式公布, 调用方才能判断两个 run 是否可直接比较。
+    """
+    # 扩展点发现与 CLI 同源 (core/discovery.discover_extensions):
+    # 两处给出的自定义判据/环境/模拟器名字集合必须一致, 不允许
+    # 「接口看得见、命令行用不上」的分歧 (spec: cli)。
+    from agent_eval.core.discovery import discover_extensions
+
+    try:
+        discovered = discover_extensions().catalog()
+    except Exception:  # noqa: BLE001 — 元数据异常不阻断 /meta
+        discovered = {}
+    discovered_graders = [e["name"] for e in discovered.get("graders", [])]
+    builtin_graders = [g["name"] for g in get_grader_catalog()]
+    # 发现的自定义判据追加在内置之后 (去重); 与 CLI extensions 清单同一份来源
+    graders = sorted(builtin_graders) + sorted(
+        n for n in discovered_graders if n not in builtin_graders
+    )
+    return {
+        "name": "Aeval",
+        "package": DISTRIBUTION_NAME,
+        "version": version or package_version(),
+        "api_prefix": api_prefix,
+        "endpoints": endpoints or ["/suites", "/tasks", "/runs", "/compare", "/graders",
+                                   "/datasets", "/metrics", "/health"],
+        "statistics": statistics_defaults(),
+        "evidence": {
+            "spec_version": OTEL_GENAI_SPEC_VERSION,
+            "mapping_version": ATTRIBUTE_MAPPING_VERSION,
+            # default_mapping(vocabulary=...) 的可填值在这里枚举: 调用方不需要读
+            # 源码猜词汇, 也不需要为了发现一个字符串去 import 内部模块。
+            "vocabularies": {
+                "default": VOCABULARY_OTEL_GENAI,
+                "known": list(known_vocabularies()),
+                "spec_versions": dict(VOCABULARY_SPEC_VERSIONS),
+            },
+            "tool_arguments_captured_by_default": False,
+            "model_content_captured_by_default": False,
+            "capture_is_one_declaration": True,
+        },
+        "capabilities": {
+            "graders": graders,
+            "extensions": discovered,
+            "user_simulation": True,
+            "run_event_injection": True,
+            "judgment_moments": ["at_end", "not_at_end", "any_time", "after_last_event"],
+            "environment_identity_boundary": True,
+            "storage": ["memory", "sqlite"],
+            "trace_providers": ["phoenix (optional, lazily imported)"],
+            "sse": True,
+            "datasets": True,
+            "metrics": True,
+            "validity_verdicts": True,
+            "confidence_intervals": True,
+            "normalized_trace_observations": True,
+            "termination_reasons": True,
+            "cost_axis": True,
+            "evidence_provenance_levels": True,
+            "deferred_grading": True,
+            # ④ agent 指标目录: 证据感知测量上下文 / 诊断-判分角色轴 / κ/α / 门
+            "evidence_aware_metrics": True,
+            "metric_roles": ["diagnostic", "judging"],
+            "inter_rater_agreement": ["cohen_kappa", "krippendorff_alpha"],
+            "reward_basis_gates": True,
+            # 重评分本期只有库层入口 (EvalRunner.regrade_run)。它牵涉同一大版本的
+            # 响应结构兼容承诺, 暴露面另立变更 —— 列出来免得调用方以为 /runs 上能调。
+            "regrade_over_http": False,
+            "regrade_over_cli": False,
+        },
+        "not_exposed": {
+            "regrade": (
+                "证据归档与重评分已落地 (EvalRunner.regrade_run / verdict_drift), "
+                "但 HTTP 与 CLI 入口本期未提供"
+            )
+        },
+    }
+
+
+def create_app(runner: EvalRunner | None = None) -> FastAPI:
+    """
+    Create a FastAPI app with Aeval routes.
+
+    Args:
+        runner: EvalRunner instance. If None, routes will return 503.
+
+    Returns:
+        FastAPI application
+    """
+    app = FastAPI(
+        title="Aeval API",
+        version="0.1.0",
+        description="Agent Evaluation Framework API",
+    )
+
+    # Store runner in app state and global reference
+    global _runner
+    _runner = runner
+    app.state.runner = runner
+
+    # Include routers
+    app.include_router(suites.router, prefix="/suites", tags=["suites"])
+    app.include_router(tasks.router, prefix="/tasks", tags=["tasks"])
+    app.include_router(runs.router, prefix="/runs", tags=["runs"])
+    # compare 挂在 /compare (spec §REST API), 不带 /runs 前缀
+    app.include_router(runs.compare_router, tags=["compare"])
+    app.include_router(graders.router, prefix="/graders", tags=["graders"])
+    # 数据集管理 (change ③: 数据集构建闭环 — CRUD/导入/挖掘/生成/质量/to-suite)
+    app.include_router(datasets.router, prefix="/datasets", tags=["datasets"])
+    # 批量评测 (change ④: 对已有输出直接批量打分 — POST /metrics/batch)
+    app.include_router(metrics.router, prefix="/metrics", tags=["metrics"])
+
+    @app.get("/health")
+    async def health():
+        # 动态读取全局 runner — host app 会在 startup 阶段注入真实 runner
+        return {"status": "ok", "runner_configured": _get_runner() is not None}
+
+    @app.get("/meta")
+    async def meta():
+        """寄宿形态的元信息接口 (挂载前缀由宿主决定, 例如 /api/eval/meta)。"""
+        return meta_payload()
+
+    return app

{aeval_framework-0.1.0 → aeval_framework-0.3.0}/src/agent_eval/api/routes/runs.py

@@ -29,6 +29,9 @@ from pydantic import BaseModel, Field
 from sse_starlette.sse import EventSourceResponse
 
 from agent_eval.api.events import run_event_bus
+from agent_eval.core.comparison import runs_comparable
+from agent_eval.core.metrics import classify_trial, trial_invalid_reason
+from agent_eval.core.types import STATISTICS_VERSION, TrialVerdict
 
 router = APIRouter()
 
@@ -60,6 +63,9 @@ async def list_runs(suite_name: str | None = None, limit: int = 50):
                 "started_at": r.started_at,
                 "completed_at": r.completed_at,
                 "duration_ms": r.duration_ms,
+                "statistics_version": r.statistics_version,
+                "evidence": r.evidence.model_dump() if r.evidence else None,
+                "regrade": _regrade_entry(r),
                 "task_count": len(r.trials),
                 "summary": r.summary.model_dump() if r.summary else None,
             }
@@ -98,7 +104,12 @@ async def create_run(request: CreateRunRequest):
     from agent_eval.core.types import RunResult
 
     await runner.storage.save_run(
-        RunResult(run_id=run_id, suite_name=suite.name, status="pending")
+        RunResult(
+            run_id=run_id,
+            suite_name=suite.name,
+            status="pending",
+            statistics_version=STATISTICS_VERSION,
+        )
     )
 
     async def _run():
@@ -164,6 +175,10 @@ async def get_run(run_id: str):
         "completed_at": run.completed_at,
         "duration_ms": run.duration_ms,
         "error": run.error,
+        "statistics_version": run.statistics_version,
+        "evidence": run.evidence.model_dump() if run.evidence else None,
+        # 本期只开库层重评分入口: 这里如实标能不能重评与原因, 不提供 HTTP 触发
+        "regrade": _regrade_entry(run),
         "trials": {
             task_id: [
                 {
@@ -171,14 +186,44 @@ async def get_run(run_id: str):
                     "trace_id": t.trace_id,
                     "success": t.success,
                     "score": t.avg_score(),
+                    # trial 总分 (权重/策略/乘性门塌缩后的值; None = 该字段落盘前的历史 run)
+                    "synthesized_score": t.synthesized_score,
                     "duration_ms": t.duration_ms,
                     "error": t.error,
+                    "verdict": t.verdict.value,
+                    "invalid_reason": t.invalid_reason.value if t.invalid_reason else None,
+                    "termination_reason": (
+                        t.termination_reason.value if t.termination_reason else None
+                    ),
+                    "metrics": t.metrics,
+                    "evidence_gaps": [gap.model_dump() for gap in t.evidence_gaps],
+                    "unrecognized_attributes": t.unrecognized_attributes,
+                    # 结论的分量: 它依据的最弱一级证据 + 证据是否已归档
+                    "weakest_evidence": (
+                        t.weakest_evidence.value if t.weakest_evidence else None
+                    ),
+                    "evidence_archived": t.evidence_archived,
                     "grader_results": [
                         {
                             "grader_name": gr.grader_name,
                             "score": gr.score,
                             "passed": gr.passed,
                             "explanation": gr.explanation,
+                            "verdict": gr.verdict.value,
+                            "invalid_reason": (
+                                gr.invalid_reason.value if gr.invalid_reason else None
+                            ),
+                            "evidence_levels": [
+                                level.value for level in gr.evidence_levels
+                            ],
+                            "judgment_moment": (
+                                gr.judgment_moment.value if gr.judgment_moment else None
+                            ),
+                            "subject_only": gr.subject_only,
+                            # 门结果: 因子 / 是否乘入总分 / 未生效原因 (spec: graders)
+                            "gate_factor": gr.gate_factor,
+                            "gate_applied": gr.gate_applied,
+                            "gate_reason": gr.gate_reason,
                         }
                         for gr in t.grader_results
                     ],
@@ -191,6 +236,14 @@ async def get_run(run_id: str):
     }
 
 
+def _regrade_entry(run) -> dict[str, Any]:
+    """能不能重评分 + 为什么不能 (与库层 ``regrade_run`` 共用同一份判断)。"""
+    from agent_eval.core.runner import regrade_state
+
+    possible, reason = regrade_state(run)
+    return {"available": possible, "reason": reason, "exposed_over_http": False}
+
+
 @router.delete("/{run_id}")
 async def delete_run(run_id: str):
     """删除运行"""
@@ -204,6 +257,10 @@ async def delete_run(run_id: str):
     if not deleted:
         raise HTTPException(status_code=404, detail=f"Run '{run_id}' not found")
 
+    # 派生物一并清除: 内容寻址的评分缓存可能缓存了该 run 采集到的证据内容
+    runner.evict_run_cache(run_id)
+    _background_tasks.pop(run_id, None)
+
     return {"deleted": True}
 
 
@@ -410,11 +467,13 @@ async def submit_human_score(run_id: str, request: HumanScoreRequest):
             "threshold", threshold
         )
 
-    # 更新已存的 GraderResult
+    # 更新已存的 GraderResult (评分回传 → 离开 pending 通道)
     grader_result.score = request.score
     grader_result.passed = request.score >= threshold
     grader_result.explanation = request.explanation or "人工评分"
     grader_result.confidence = 1.0
+    grader_result.verdict = TrialVerdict.VALID
+    grader_result.invalid_reason = None
     grader_result.details = {
         **grader_result.details,
         "status": "scored",
@@ -425,6 +484,11 @@ async def submit_human_score(run_id: str, request: HumanScoreRequest):
     # 重算 trial 成功状态与 run 汇总 (含该 task 汇总)
     if task is not None:
         trial.success = runner._compute_trial_success(task, trial.grader_results)
+        trial.synthesized_score = runner._trial_weighted_score(task, trial)
+    trial.verdict = classify_trial(trial)
+    trial.invalid_reason = trial_invalid_reason(trial)
+    if run.statistics_version is None:
+        run.statistics_version = STATISTICS_VERSION
     run.summary = runner._compute_summary(run, suite) if suite is not None else run.summary
     await runner.storage.save_run(run)
 
@@ -436,6 +500,7 @@ async def submit_human_score(run_id: str, request: HumanScoreRequest):
         "score": grader_result.score,
         "passed": grader_result.passed,
         "trial_success": trial.success,
+        "trial_verdict": trial.verdict.value,
         "summary": run.summary.model_dump() if run.summary else None,
     }
 
@@ -489,85 +554,174 @@ async def compare_runs(request: CompareRequest):
 
 
 def _build_comparison(run_a, run_b) -> dict[str, Any]:
-    """构建两次运行的对比"""
+    """构建两次运行的对比 (口径版本不同则标注不可比; 区间重叠则不判方向)。
+
+    既有字段 (`a`/`b`/`delta`/`regressions`/`improvements`/`tasks`) 的名称与类型
+    保持不变; 分母为 0 时 `a`/`b`/`delta` 为 null 而非 0.0。
+    """
     summary_a = run_a.summary
     summary_b = run_b.summary
 
-    # 全局指标对比
-    all_k_values = set()
-    if summary_a.pass_at_k:
-        all_k_values.update(summary_a.pass_at_k.keys())
-    if summary_b.pass_at_k:
-        all_k_values.update(summary_b.pass_at_k.keys())
-
-    pass_at_k_comparison = {}
-    for k in sorted(all_k_values):
-        a_val = summary_a.pass_at_k.get(k, 0.0)
-        b_val = summary_b.pass_at_k.get(k, 0.0)
-        pass_at_k_comparison[f"pass_at_{k}"] = {
+    # 可比性前置与 CLI / 基线门同源 (core.comparison.runs_comparable)
+    comparable, not_comparable_reason = runs_comparable(run_a, run_b)
+    version_a = getattr(run_a, "statistics_version", None)
+    version_b = getattr(run_b, "statistics_version", None)
+    evidence_a = getattr(run_a, "evidence", None)
+    evidence_b = getattr(run_b, "evidence", None)
+
+    all_k_values: set[int] = set()
+    for summary in (summary_a, summary_b):
+        for k in (summary.pass_at_k or {}):
+            all_k_values.add(int(k))
+
+    def _entry(
+        a_val: float | None,
+        b_val: float | None,
+        a_ci: tuple[float | None, float | None] | None,
+        b_ci: tuple[float | None, float | None] | None,
+        extrapolated: bool,
+    ) -> dict[str, Any]:
+        overlapping = _intervals_overlap(a_ci, b_ci)
+        return {
             "a": a_val,
             "b": b_val,
-            "delta": round(b_val - a_val, 4),
+            "delta": _delta(a_val, b_val),
+            "a_ci": _ci_list(a_ci),
+            "b_ci": _ci_list(b_ci),
+            "intervals_overlap": overlapping,
+            "significant": (
+                None if overlapping is None else (comparable and not overlapping)
+            ),
+            "extrapolated": extrapolated,
+            "comparable": comparable,
         }
 
+    def _k_map(summary, field: str) -> dict:
+        raw = getattr(summary, field, None) or {}
+        return {int(k): v for k, v in raw.items()}
+
+    pass_at_k_comparison = {}
     pass_power_k_comparison = {}
     for k in sorted(all_k_values):
-        a_val = summary_a.pass_power_k.get(k, 0.0)
-        b_val = summary_b.pass_power_k.get(k, 0.0)
-        pass_power_k_comparison[f"pass_power_{k}"] = {
-            "a": a_val,
-            "b": b_val,
-            "delta": round(b_val - a_val, 4),
-        }
+        est_a = _k_map(summary_a, "estimates").get(k)
+        est_b = _k_map(summary_b, "estimates").get(k)
+        pass_at_k_comparison[f"pass_at_{k}"] = _entry(
+            est_a.value if est_a else None,
+            est_b.value if est_b else None,
+            _est_ci(est_a),
+            _est_ci(est_b),
+            bool(est_a and est_a.extrapolated) or bool(est_b and est_b.extrapolated),
+        )
+
+        pow_a = _k_map(summary_a, "power_estimates").get(k)
+        pow_b = _k_map(summary_b, "power_estimates").get(k)
+        pass_power_k_comparison[f"pass_power_{k}"] = _entry(
+            pow_a.value if pow_a else None,
+            pow_b.value if pow_b else None,
+            _est_ci(pow_a),
+            _est_ci(pow_b),
+            bool(pow_a and pow_a.extrapolated) or bool(pow_b and pow_b.extrapolated),
+        )
 
-    # 逐 task 对比
+    dist_a = getattr(summary_a, "score_distribution", None)
+    dist_b = getattr(summary_b, "score_distribution", None)
+    avg_entry = _entry(
+        summary_a.avg_score,
+        summary_b.avg_score,
+        _dist_ci(dist_a),
+        _dist_ci(dist_b),
+        False,
+    )
+
+    # 逐 task 对比: 只有区间不重叠才判为退化/提升 (D4)
     task_a_map = {ts.task_id: ts for ts in summary_a.task_summaries}
     task_b_map = {ts.task_id: ts for ts in summary_b.task_summaries}
 
     all_task_ids = set(task_a_map.keys()) | set(task_b_map.keys())
-    regressions = []
-    improvements = []
-    task_comparisons = {}
+    regressions: list[dict[str, Any]] = []
+    improvements: list[dict[str, Any]] = []
+    task_comparisons: dict[str, Any] = {}
 
     for task_id in sorted(all_task_ids):
         ts_a = task_a_map.get(task_id)
         ts_b = task_b_map.get(task_id)
+        if not (ts_a and ts_b):
+            continue
+
+        a_score = ts_a.avg_score
+        b_score = ts_b.avg_score
+        delta = _delta(a_score, b_score)
+        overlapping = _intervals_overlap(
+            _dist_ci(ts_a.score_distribution), _dist_ci(ts_b.score_distribution)
+        )
+        significant = (
+            comparable and overlapping is False and delta is not None and abs(delta) > 0.1
+        )
+        task_comparisons[task_id] = {
+            "a": a_score,
+            "b": b_score,
+            "delta": delta,
+            "a_ci": _ci_list(_dist_ci(ts_a.score_distribution)),
+            "b_ci": _ci_list(_dist_ci(ts_b.score_distribution)),
+            "intervals_overlap": overlapping,
+            "significant": (None if overlapping is None else (
+                comparable and overlapping is False
+            )),
+            "comparable": comparable,
+        }
 
-        if ts_a and ts_b:
-            a_score = ts_a.avg_score
-            b_score = ts_b.avg_score
-            delta = round(b_score - a_score, 4)
-
-            task_comparisons[task_id] = {
-                "a": a_score,
-                "b": b_score,
-                "delta": delta,
-            }
-
-            if delta < -0.1:
-                regressions.append({
-                    "task_id": task_id,
-                    "a": a_score,
-                    "b": b_score,
-                    "delta": delta,
-                })
-            elif delta > 0.1:
-                improvements.append({
-                    "task_id": task_id,
-                    "a": a_score,
-                    "b": b_score,
-                    "delta": delta,
-                })
+        if not significant:
+            continue
+        row = {"task_id": task_id, "a": a_score, "b": b_score, "delta": delta}
+        if delta < 0:
+            regressions.append(row)
+        else:
+            improvements.append(row)
 
     return {
         "pass_at_k": pass_at_k_comparison,
         "pass_power_k": pass_power_k_comparison,
-        "avg_score": {
-            "a": summary_a.avg_score,
-            "b": summary_b.avg_score,
-            "delta": round(summary_b.avg_score - summary_a.avg_score, 4),
-        },
+        "avg_score": avg_entry,
         "regressions": regressions,
         "improvements": improvements,
         "tasks": task_comparisons,
+        "statistics_version": {"a": version_a, "b": version_b},
+        "evidence_boundary": {
+            "a": evidence_a.model_dump() if evidence_a else None,
+            "b": evidence_b.model_dump() if evidence_b else None,
+        },
+        "comparable": comparable,
+        "not_comparable_reason": not_comparable_reason,
     }
+
+
+def _delta(a: float | None, b: float | None) -> float | None:
+    if a is None or b is None:
+        return None
+    return round(b - a, 4)
+
+
+def _est_ci(est) -> tuple[float | None, float | None] | None:
+    if est is None or est.p_lower_bound is None or est.p_upper_bound is None:
+        return None
+    return (est.p_lower_bound, est.p_upper_bound)
+
+
+def _dist_ci(dist) -> tuple[float | None, float | None] | None:
+    if dist is None or dist.ci_low is None or dist.ci_high is None:
+        return None
+    return (dist.ci_low, dist.ci_high)
+
+
+def _ci_list(ci: tuple[float | None, float | None] | None) -> list[float] | None:
+    return [ci[0], ci[1]] if ci else None
+
+
+def _intervals_overlap(
+    a: tuple[float | None, float | None] | None,
+    b: tuple[float | None, float | None] | None,
+) -> bool | None:
+    """两侧区间是否重叠 (D4)。任一侧无区间 → None (无法判定)。"""
+    if a is None or b is None:
+        return None
+    return not (a[1] < b[0] or b[1] < a[0])