refactor(tracking): extract run-report writers into aet.tracking.reports

The four write_* serializers (run_record / summary_metrics / eval_report / metrics.json) move from
EvalRunLogger into free functions in tracking/reports.py; the facade methods delegate. This reduces
the facade's size and — more importantly — makes the report *shapes* testable in isolation
(tests/test_reports.py). No behavior change: identical JSON output. Preferred over a mixin split,
which wouldn't reduce the facade's real coupling to its backend state.

Author: copparihollmann

AGENTS.md

@@ -58,10 +58,8 @@ Data flow: `transcript.jsonl → import_transcript → RunTrajectory → (emit_t
 5. New public API is reachable from the docs (`mkdocs build --strict` stays green — it fails on a
    broken/renamed reference, which is the anti-drift backstop).
 
-## Known follow-ups
-- `tracking/run_logger.py` (~1150 LOC, one **cohesive** `EvalRunLogger` facade). Big but single-
-  responsibility, so it is not a blocker. A mixin split is **not** recommended — mixins don't reduce
-  the real coupling (every method needs the facade's `self._local/_mlflow/_otel` state) and add MRO
-  indirection. If trimming: extract the pure report-**writers** (`write_summary_metrics`,
-  `write_eval_report`, `write_metrics_structured`, `write_run_record`) into a `tracking/reports.py`
-  of free functions — low-risk, reduces size *and* coupling.
+## Notes
+- `tracking/run_logger.py` is one **cohesive** `EvalRunLogger` facade — big but single-responsibility.
+  Its pure serialization now lives in `tracking/reports.py` (free functions the facade delegates to).
+  A further mixin split is **not** recommended: mixins don't reduce the real coupling (every method
+  needs the facade's `self._local/_mlflow/_otel` state) and only add MRO indirection.

CHANGELOG.md

@@ -115,6 +115,9 @@ All notable changes to `aet` are recorded here.
 - **CLI de-godded**: `cli/main.py` (1379 LOC) split into a thin argparse table + `cli/_common.py` +
   `cli/commands/{lifecycle,reporting,trajectory}.py`. No behavior change.
 - **Logging**: tracking warnings emit via `logging` (silent by default) instead of raw `print`.
+- **Report writers extracted**: the run-report serialization (`run_record.json`,
+  `summary_metrics.json`, `eval_report.json`, `metrics.json`) moved from `EvalRunLogger` into
+  free functions in `tracking/reports.py` (the facade delegates) — testable in isolation.
 
 ### Docs
 - Rewritten `README.md` (the real record→plot / sandboxed-run surface), a root `AGENTS.md`

src/aet/tracking/reports.py

@@ -0,0 +1,74 @@
+"""Run-report writers — pure serialization, no backend/logger state.
+
+These build the canonical JSON products of a run (`run_record.json`, `metrics/summary_metrics.json`,
+`eval_report.json`, `metrics.json`) from plain values + a target directory. Kept as free functions
+(not `EvalRunLogger` methods) so the report *shape* is testable and reusable in isolation, and the
+logger facade stays a thin delegator. See :class:`aet.tracking.run_logger.EvalRunLogger`'s
+``write_*`` methods.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _now() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def _dump(path: Path, obj: dict) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(obj, indent=2, default=str))
+    return path
+
+
+def write_run_record(run_path: Path, *, run_id: str, project: str, suite: str, target,
+                     method: str, seed: int, mode: str, extra: dict | None = None) -> Path:
+    """`run_record.json` at the run root — identity + provenance of the run."""
+    record = {
+        "schema_version": "1.1", "run_id": run_id, "project": project, "suite": suite,
+        "target": target, "method": method, "seed": seed, "tracking_mode": mode,
+        "created_at": _now(),
+    }
+    if extra:
+        record.update(extra)
+    return _dump(run_path / "run_record.json", record)
+
+
+def write_summary_metrics(run_path: Path, *, run_id: str, project: str, suite: str, method: str,
+                          seed: int, target, extra: dict | None = None) -> Path:
+    """`metrics/summary_metrics.json` — the headline metrics for `aet runs`/`compare`."""
+    summary = {
+        "run_id": run_id, "project": project, "suite": suite, "method": method, "seed": seed,
+        "target": target, "recorded_at": _now(),
+    }
+    if extra:
+        summary.update(extra)
+    return _dump(run_path / "metrics" / "summary_metrics.json", summary)
+
+
+def write_eval_report(run_path: Path, *, run_id: str, tests: list[dict],
+                      contracts: list[dict] | None = None, assertions: list[dict] | None = None,
+                      coverage: list[dict] | None = None, extra: dict | None = None) -> Path:
+    """`eval_report.json` — per-test / per-contract / per-assertion / coverage results."""
+    report = {
+        "schema_version": "1.0", "run_id": run_id, "generated_at": _now(),
+        "tests": tests, "contracts": contracts or [], "assertions": assertions or [],
+        "coverage": coverage or [],
+    }
+    if extra:
+        report.update(extra)
+    return _dump(run_path / "eval_report.json", report)
+
+
+def write_metrics_structured(run_path: Path, *, run_id: str, cost: dict, quality: dict,
+                             process: dict, extra: dict | None = None) -> Path:
+    """`metrics.json` — the structured cost / quality / process breakdown."""
+    metrics = {
+        "schema_version": "1.0", "run_id": run_id, "generated_at": _now(),
+        "cost": cost, "quality": quality, "process": process,
+    }
+    if extra:
+        metrics.update(extra)
+    return _dump(run_path / "metrics.json", metrics)

src/aet/tracking/run_logger.py

@@ -6,6 +6,7 @@
 from pathlib import Path
 from typing import Any
 
+from aet.tracking import reports
 from aet.tracking.types import TrackingConfig, TRACKING_MODES
 from aet.tracking.local_backend import LocalBackend
 from aet.tracking.mlflow_backend import MLflowBackend
@@ -1007,48 +1008,18 @@ def log_human_override(
     # Utility writers
 
     def write_run_record(self, extra: dict | None = None) -> Path:
-        """Write run_record.json to the run_path root. Returns the path."""
-        from datetime import datetime, timezone
-        run_path = self._config.run_path
-        run_path.mkdir(parents=True, exist_ok=True)
-        record: dict = {
-            "schema_version": "1.1",
-            "run_id": self._config.run_id,
-            "project": self._config.project,
-            "suite": self._config.suite,
-            "target": self._config.target,
-            "method": self._config.method,
-            "seed": self._config.seed,
-            "tracking_mode": self._config.mode,
-            "created_at": datetime.now(tz=timezone.utc).isoformat(),
-        }
-        if extra:
-            record.update(extra)
-        import json
-        path = run_path / "run_record.json"
-        path.write_text(json.dumps(record, indent=2, default=str))
-        return path
+        """Write `run_record.json` at the run root (see :mod:`aet.tracking.reports`)."""
+        c = self._config
+        return reports.write_run_record(
+            c.run_path, run_id=c.run_id, project=c.project, suite=c.suite, target=c.target,
+            method=c.method, seed=c.seed, mode=c.mode, extra=extra)
 
     def write_summary_metrics(self, extra: dict | None = None) -> Path:
-        """Write metrics/summary_metrics.json. Returns the path."""
-        from datetime import datetime, timezone
-        import json
-        metrics_dir = self._config.run_path / "metrics"
-        metrics_dir.mkdir(parents=True, exist_ok=True)
-        summary: dict = {
-            "run_id": self._config.run_id,
-            "project": self._config.project,
-            "suite": self._config.suite,
-            "method": self._config.method,
-            "seed": self._config.seed,
-            "target": self._config.target,
-            "recorded_at": datetime.now(tz=timezone.utc).isoformat(),
-        }
-        if extra:
-            summary.update(extra)
-        path = metrics_dir / "summary_metrics.json"
-        path.write_text(json.dumps(summary, indent=2, default=str))
-        return path
+        """Write `metrics/summary_metrics.json` (see :mod:`aet.tracking.reports`)."""
+        c = self._config
+        return reports.write_summary_metrics(
+            c.run_path, run_id=c.run_id, project=c.project, suite=c.suite, method=c.method,
+            seed=c.seed, target=c.target, extra=extra)
 
     def write_eval_report(
         self,
@@ -1058,25 +1029,10 @@ def write_eval_report(
         coverage: list[dict] | None = None,
         extra: dict | None = None,
     ) -> Path:
-        """Write eval_report.json: per-test, per-contract, per-assertion, coverage."""
-        from datetime import datetime, timezone
-        run_path = self._config.run_path
-        run_path.mkdir(parents=True, exist_ok=True)
-        import json
-        report: dict = {
-            "schema_version": "1.0",
-            "run_id": self._config.run_id,
-            "generated_at": datetime.now(tz=timezone.utc).isoformat(),
-            "tests": tests,
-            "contracts": contracts or [],
-            "assertions": assertions or [],
-            "coverage": coverage or [],
-        }
-        if extra:
-            report.update(extra)
-        path = run_path / "eval_report.json"
-        path.write_text(json.dumps(report, indent=2, default=str))
-        return path
+        """Write `eval_report.json` (see :mod:`aet.tracking.reports`)."""
+        return reports.write_eval_report(
+            self._config.run_path, run_id=self._config.run_id, tests=tests, contracts=contracts,
+            assertions=assertions, coverage=coverage, extra=extra)
 
     def write_metrics_structured(
         self,
@@ -1085,24 +1041,10 @@ def write_metrics_structured(
         process: dict,
         extra: dict | None = None,
     ) -> Path:
-        """Write metrics.json with cost/quality/process structure per spec."""
-        from datetime import datetime, timezone
-        run_path = self._config.run_path
-        run_path.mkdir(parents=True, exist_ok=True)
-        import json
-        metrics: dict = {
-            "schema_version": "1.0",
-            "run_id": self._config.run_id,
-            "generated_at": datetime.now(tz=timezone.utc).isoformat(),
-            "cost": cost,
-            "quality": quality,
-            "process": process,
-        }
-        if extra:
-            metrics.update(extra)
-        path = run_path / "metrics.json"
-        path.write_text(json.dumps(metrics, indent=2, default=str))
-        return path
+        """Write structured `metrics.json` (see :mod:`aet.tracking.reports`)."""
+        return reports.write_metrics_structured(
+            self._config.run_path, run_id=self._config.run_id, cost=cost, quality=quality,
+            process=process, extra=extra)
 
     # ------------------------------------------------------------------
     def finish(self, status: str, message: str | None = None) -> None:

tests/test_reports.py

@@ -0,0 +1,34 @@
+"""Run-report writers (aet.tracking.reports) — the report shapes, tested in isolation."""
+import json
+
+from aet.tracking import reports
+
+
+def test_run_record_shape(tmp_path):
+    p = reports.write_run_record(tmp_path, run_id="r1", project="proj", suite="s", target="t",
+                                 method="m", seed=3, mode="local", extra={"repo_sha": "abc"})
+    assert p == tmp_path / "run_record.json"
+    d = json.loads(p.read_text())
+    assert d["run_id"] == "r1" and d["seed"] == 3 and d["tracking_mode"] == "local"
+    assert d["repo_sha"] == "abc" and "created_at" in d
+
+
+def test_summary_metrics_goes_under_metrics(tmp_path):
+    p = reports.write_summary_metrics(tmp_path, run_id="r1", project="p", suite="s", method="m",
+                                      seed=0, target="t", extra={"hw.functional_pass": 1})
+    assert p == tmp_path / "metrics" / "summary_metrics.json"
+    assert json.loads(p.read_text())["hw.functional_pass"] == 1
+
+
+def test_eval_report_defaults_empty_lists(tmp_path):
+    p = reports.write_eval_report(tmp_path, run_id="r1", tests=[{"test": "t", "passed": True}])
+    d = json.loads(p.read_text())
+    assert d["tests"][0]["passed"] is True
+    assert d["contracts"] == [] and d["assertions"] == [] and d["coverage"] == []
+
+
+def test_metrics_structured_sections(tmp_path):
+    p = reports.write_metrics_structured(tmp_path, run_id="r1", cost={"usd": 1.0},
+                                         quality={"pass": True}, process={"iters": 2})
+    d = json.loads(p.read_text())
+    assert d["cost"]["usd"] == 1.0 and d["quality"]["pass"] is True and d["process"]["iters"] == 2