quantlab-factor-agent 0.1.0__py3-none-any.whl

factor_agent/snapshot.py

@@ -0,0 +1,219 @@
+"""The RunSnapshot: the files a run searched with and the code it ran, kept in its run directory.
+
+A run's search space is what its files say (``SearchFiles``): the field
+files and the operator file and the replaced prompt templates. On a first
+start ``open`` copies each file into ``<run_dir>/snapshot/<name>`` and records
+its hash and the code versions (the commits of this package and of
+quantlab) in ``<run_dir>/snapshot.json``. On a resume a file whose name or
+content differs from the snapshot is an error, since a new search space
+needs a new run directory; a code version that differs only warns, so a
+bug-fix resume is allowed but visible, and every code version a run was
+opened with is kept in order.
+
+The run reads the snapshot's copies (``search_files``), not the files it was given,
+and ``read`` opens a run's snapshot without recording anything, for
+Acceptance and for a replay of the run.
+"""
+
+import hashlib
+import json
+import shutil
+import warnings
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+#: The code versions compared on a resume (``segments.code_version`` holds them and quantlab's version).
+COMPARED_VERSIONS = ("factor_agent", "quantlab")
+
+
+class SnapshotMismatch(ValueError):
+    """A resume was given files that differ from the run's snapshot."""
+
+
+class CodeVersionChanged(UserWarning):
+    """A resume runs other code than the run was last opened with."""
+
+
+@dataclass(frozen=True)
+class SearchFiles:
+    """The files a run searches with: the field files, the operator file and the replaced templates.
+
+    ``prompts`` maps a template's name to the file that replaces it. In a
+    snapshot a field file is named ``fields/<file name>``, the operator file
+    ``operators/<file name>`` and a replaced template
+    ``prompts/<template>/<file name>`` (``names``, ``from_names``).
+    """
+
+    fields: tuple
+    operators: str | Path
+    prompts: Mapping[str, str | Path] = field(default_factory=dict)
+
+    def __post_init__(self):
+        object.__setattr__(self, "fields", tuple(self.fields))
+
+    def names(self) -> dict[str, str | Path]:
+        """Every file by its name in a snapshot, field files first, then the operator file and the templates.
+
+        Raises
+        ------
+        ValueError
+            If two field files have the same file name.
+        """
+        files = {f"fields/{Path(path).name}": path for path in self.fields}
+        if len(files) != len(self.fields):
+            raise ValueError(f"run snapshot: the field files {[str(f) for f in self.fields]} repeat a file name")
+        templates = {f"prompts/{name}/{Path(path).name}": path for name, path in self.prompts.items()}
+        return {**files, f"operators/{Path(self.operators).name}": self.operators, **templates}
+
+    @classmethod
+    def from_names(cls, files: Mapping[str, str | Path]) -> "SearchFiles":
+        """The files of a snapshot's ``files`` (name to path), as ``names`` names them."""
+        [operators] = [path for name, path in files.items() if name.startswith("operators/")]
+        return cls(
+            fields=tuple(path for name, path in files.items() if name.startswith("fields/")),
+            operators=operators,
+            prompts={name.split("/")[1]: path for name, path in files.items() if name.startswith("prompts/")},
+        )
+
+
+class RunSnapshot:
+    """The snapshot of a run directory; build it with ``open`` or ``read``.
+
+    ``files`` maps each name to its copy, in the order the run was first
+    given them; ``versions`` lists the code versions of every opening.
+    """
+
+    def __init__(self, run_dir: Path, manifest: dict):
+        self.run_dir = run_dir
+        self.files = {name: run_dir / "snapshot" / name for name in manifest["files"]}
+        self.versions: list[dict] = manifest["versions"]
+        self.settings: dict = manifest.get("settings", {})
+
+    @classmethod
+    def open(
+        cls, run_dir: str | Path, search: SearchFiles, versions: Mapping[str, str], settings: Mapping | None = None,
+    ) -> "RunSnapshot":
+        """Open ``run_dir`` with the files of ``search``, the code ``versions`` it runs on and its ``settings``.
+
+        A first start copies the files, under their ``SearchFiles.names``, and
+        records ``settings`` (by section, the config settings the search
+        depends on besides the files, such as ``{"context": {"recent_rounds": 5}}``
+        and, with an intraday family, ``{"intraday": {"dataset": ...}}``); a resume
+        checks the files against the copies and the settings against the
+        recorded ones. Either way ``versions`` is appended to the recorded versions.
+
+        Raises
+        ------
+        SnapshotMismatch
+            On a resume, naming every file added, removed or changed and every setting changed since the first start.
+        ValueError
+            If two field files have the same file name.
+
+        Warns
+        -----
+        CodeVersionChanged
+            On a resume whose ``versions`` differ from the last recorded ones.
+        """
+        run_dir = Path(run_dir)
+        files = search.names()
+        manifest_path = run_dir / "snapshot.json"
+        hashes = {name: _hash(Path(path)) for name, path in files.items()}
+        if manifest_path.exists():
+            manifest = json.loads(manifest_path.read_text())
+            _check(run_dir, manifest["files"], hashes)
+            _check_settings(run_dir, manifest.get("settings", {}), dict(settings or {}))
+            _warn(manifest["versions"][-1], versions)
+        else:
+            manifest = {"files": hashes, "settings": dict(settings or {}), "versions": []}
+            for name, path in files.items():
+                copy = run_dir / "snapshot" / name
+                copy.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copyfile(path, copy)
+        manifest["versions"].append({**versions, "opened_at": datetime.now(timezone.utc).isoformat(timespec="seconds")})
+        tmp = manifest_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(manifest, indent=2) + "\n")
+        tmp.replace(manifest_path)
+        return cls(run_dir, manifest)
+
+    @classmethod
+    def read(cls, run_dir: str | Path) -> "RunSnapshot":
+        """The snapshot of ``run_dir`` as it is, recording nothing.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the run directory has no snapshot.
+        """
+        run_dir = Path(run_dir)
+        manifest_path = run_dir / "snapshot.json"
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"run snapshot: {run_dir} has no snapshot ({manifest_path})")
+        return cls(run_dir, json.loads(manifest_path.read_text()))
+
+    @staticmethod
+    def exists(run_dir: str | Path) -> bool:
+        """Whether ``run_dir`` has a snapshot."""
+        return (Path(run_dir) / "snapshot.json").exists()
+
+    def path(self, name: str) -> Path:
+        """The snapshot's copy of the file ``name``.
+
+        Raises
+        ------
+        KeyError
+            If the snapshot holds no file of that name.
+        """
+        if name not in self.files:
+            raise KeyError(f"run snapshot of {self.run_dir}: no file {name!r}; it holds {list(self.files)}")
+        return self.files[name]
+
+    @property
+    def search_files(self) -> SearchFiles:
+        """The snapshot's copies, as the files the run searches with."""
+        return SearchFiles.from_names(self.files)
+
+
+def _hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _check(run_dir: Path, recorded: dict, given: dict) -> None:
+    """Raise ``SnapshotMismatch`` naming every file of ``given`` that is not the one ``recorded``."""
+    problems = [f"{name} was added" for name in given if name not in recorded]
+    problems += [f"{name} was removed" for name in recorded if name not in given]
+    problems += [f"{name} changed" for name in given if name in recorded and given[name] != recorded[name]]
+    if problems:
+        raise SnapshotMismatch(
+            f"run snapshot of {run_dir}: the run's files differ from the ones it started with: "
+            f"{'; '.join(problems)}. A changed search space needs a new run directory."
+        )
+
+
+def _check_settings(run_dir: Path, recorded: dict, given: dict) -> None:
+    """Raise ``SnapshotMismatch`` naming every setting of ``given`` that is not the one ``recorded``."""
+    before, now = _flat(recorded), _flat(given)
+    changed = [
+        f"{name} was {before.get(name, 'not recorded')}, now {now.get(name, 'not given')}"
+        for name in sorted(before.keys() | now.keys()) if before.get(name) != now.get(name)
+    ]
+    if changed:
+        raise SnapshotMismatch(
+            f"run snapshot of {run_dir}: the run's settings differ from the ones it started with: "
+            f"{'; '.join(changed)}. A changed search space needs a new run directory."
+        )
+
+
+def _flat(settings: dict) -> dict:
+    """``settings`` by section as one mapping from ``"section.key"`` to the value."""
+    return {f"{section}.{key}": value for section, values in settings.items() for key, value in values.items()}
+
+
+def _warn(last: dict, versions: Mapping[str, str]) -> None:
+    changed = [f"{key} {last.get(key)} -> {versions.get(key)}" for key in COMPARED_VERSIONS if last.get(key) != versions.get(key)]
+    if changed:
+        warnings.warn(
+            f"run snapshot: the run resumes on other code than it was last opened with: {'; '.join(changed)}",
+            CodeVersionChanged, stacklevel=3,
+        )

factor_agent/web/__init__.py

@@ -0,0 +1,7 @@
+"""The web frontend: a read-only view of the run directories under a folder, served on localhost.
+
+``run_view`` reads run directories (``list_runs``, ``RunView.read``) and needs
+nothing beyond the campaign's own dependencies; ``app`` serves what it reads
+as JSON routes and the page, and needs the ``web`` extra (FastAPI and uvicorn).
+The frontend never writes to a run directory.
+"""

factor_agent/web/_acceptance.py

@@ -0,0 +1,145 @@
+"""What Acceptance has said of a run: its reports ``acceptance/<segment>[_<digest>].json`` and the hold-out lock's opens.
+
+A report that records opens of the hold-out is a hold-out report. A report
+written before the contribution table or the selection flag existed reads
+with ``None`` for them: nothing it lacks is made up.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from factor_agent.web._files import read_json, utc
+
+
+@dataclass(frozen=True)
+class Contribution:
+    """One accepted factor's contribution to the model in one mode, from an Acceptance report's contribution table.
+
+    ``factor`` is the factor's label. ``mode`` is ``"drop_one"`` (the whole
+    selection against the selection without it) or ``"add_one"`` (the
+    baseline with only it against the baseline). ``difference`` holds, per
+    compared statistic, with the factor minus without it, seed-averaged;
+    ``agreeing`` the seeds whose own difference has the sign of that mean.
+    """
+
+    factor: str
+    mode: str
+    difference: dict[str, float | None]
+    agreeing: dict[str, int]
+
+
+@dataclass(frozen=True)
+class Comparison:
+    """One Acceptance report: the user's model with and without accepted factors, on validation or the hold-out.
+
+    ``name`` is the report's file name without ``.json`` (``validation``, or
+    ``validation_<digest>`` for a selection). ``holdout`` is true for a
+    report on the hold-out. ``factors`` holds the labels of the factors
+    added to the model. ``selection`` is true for a selection of fewer than
+    every accepted factor, ``None`` for a report written before the flag.
+    ``baseline`` and ``with_accepted`` hold each compared statistic averaged
+    over ``seeds``, ``difference`` the second minus the first. ``verdict``
+    is ``"improves"`` when the rank IC and the top-k excess return both
+    rise with the factors, ``"does_not_improve"`` when neither does,
+    ``"mixed"`` otherwise, ``None`` when either is undefined. ``forced`` is
+    true for a hold-out opened again past its lock. ``contribution`` is the
+    report's contribution table, the largest rank IC difference first:
+    empty when no contribution was asked for, ``None`` for a report written
+    before the table. ``written`` is the report file's time (UTC).
+    """
+
+    name: str
+    segment: str
+    holdout: bool
+    factors: tuple[str, ...]
+    selection: bool | None
+    seeds: tuple[int, ...]
+    top_k: int | None
+    train_window: tuple[str, ...]
+    test_window: tuple[str, ...]
+    baseline: dict[str, float | None]
+    with_accepted: dict[str, float | None]
+    difference: dict[str, float | None]
+    verdict: str | None
+    forced: bool
+    contribution: tuple[Contribution, ...] | None
+    code_version: str
+    written: datetime
+
+
+@dataclass(frozen=True)
+class HoldoutOpen:
+    """One open of the hold-out, as the hold-out lock records it: ``forced`` for every open after the first."""
+
+    opened_at: str
+    code_version: str
+    forced: bool
+
+
+@dataclass(frozen=True)
+class AcceptanceReports:
+    """What Acceptance has said of a run's accepted factors.
+
+    ``validation`` is the validation report on every accepted factor, or
+    when there is none the latest validation report of a selection;
+    ``holdout`` is the report of the latest open of the hold-out. Either is
+    ``None`` while Acceptance has not written it. ``reports`` holds every
+    report, the earliest written first; ``holdout_opens`` every open the
+    hold-out lock records, which may include an open that wrote no report.
+    """
+
+    validation: Comparison | None
+    holdout: Comparison | None
+    reports: tuple[Comparison, ...]
+    holdout_opens: tuple[HoldoutOpen, ...]
+
+
+def _verdict(difference: dict) -> str | None:
+    """Whether the rank IC and the top-k excess return both rose, neither did, or one did."""
+    rank_ic, excess = difference.get("rank_ic"), difference.get("top_k_excess")
+    if rank_ic is None or excess is None:
+        return None
+    if rank_ic > 0 and excess > 0:
+        return "improves"
+    return "does_not_improve" if rank_ic <= 0 and excess <= 0 else "mixed"
+
+
+def _comparison(path: Path) -> Comparison | None:
+    """The report at ``path``, ``None`` when it is not an Acceptance report."""
+    report = read_json(path)
+    if not isinstance(report, dict) or "difference" not in report:
+        return None
+    mean, difference = report.get("mean") or {}, report["difference"]
+    table = report.get("contribution")
+    return Comparison(
+        name=path.stem, segment=report.get("segment", path.stem), holdout=bool(report.get("holdout_opens")),
+        factors=tuple(report.get("accepted") or ()), selection=report.get("selection"),
+        seeds=tuple(report.get("seeds") or ()), top_k=report.get("top_k"),
+        train_window=tuple(report.get("train_window") or ()), test_window=tuple(report.get("test_window") or ()),
+        baseline=mean.get("baseline") or {}, with_accepted=mean.get("with_accepted") or {}, difference=difference,
+        verdict=_verdict(difference), forced=bool(report.get("forced")),
+        contribution=None if table is None else tuple(
+            Contribution(factor=row["factor"], mode=row["mode"], difference=row["difference"], agreeing=row["agreeing"])
+            for row in table
+        ),
+        code_version=(report.get("code_version") or {}).get("factor_agent") or "unknown",
+        written=utc(path.stat().st_mtime),
+    )
+
+
+def acceptance(run_dir: Path) -> AcceptanceReports:
+    """The Acceptance reports, the earliest written first, and the hold-out lock's opens."""
+    found = [(path.stat().st_mtime_ns, path) for path in (run_dir / "acceptance").glob("*.json")]
+    reports = tuple(c for _, path in sorted(found) if (c := _comparison(path)))
+    validations = [c for c in reports if not c.holdout]
+    validation = next((c for c in validations if c.name == c.segment), validations[-1] if validations else None)
+    holdouts = [c for c in reports if c.holdout]
+    lock = read_json(run_dir / "holdout.lock") or {}
+    opens = tuple(
+        HoldoutOpen(opened_at=o["opened_at"], code_version=(o.get("code_version") or {}).get("factor_agent") or "unknown",
+                    forced=bool(o.get("forced")))
+        for o in lock.get("opens") or ()
+    )
+    return AcceptanceReports(validation=validation, holdout=holdouts[-1] if holdouts else None, reports=reports,
+                             holdout_opens=opens)

factor_agent/web/_config.py

@@ -0,0 +1,51 @@
+"""The files a run was set up with: the config of each opening and the snapshot's files."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from factor_agent.web._files import LineChange, line_changes, read_json
+
+
+@dataclass(frozen=True)
+class ConfigCopy:
+    """The config text the run's ``opening``-th start or resume was given, opened at ``opened_at`` (ISO, UTC).
+
+    ``changes`` holds its lines and those of the opening before, in order,
+    each marked kept, added or removed; ``None`` for the earliest config kept.
+    """
+
+    opening: int
+    opened_at: str | None
+    text: str
+    changes: tuple[LineChange, ...] | None = None
+
+
+@dataclass(frozen=True)
+class SnapshotFile:
+    """A file of the run's snapshot by its name there (``fields/<file>``, ``operators/<file>``, ``prompts/<file>``)."""
+
+    name: str
+    text: str
+
+
+@dataclass(frozen=True)
+class RunFiles:
+    """The configs of a run, the latest opening first, empty for a run written before configs were kept, and its snapshot's files."""
+
+    configs: tuple[ConfigCopy, ...]
+    snapshot: tuple[SnapshotFile, ...]
+
+
+def read_files(run_dir: str | Path) -> RunFiles:
+    """The files ``run_dir`` was set up with, as its config page shows them."""
+    run_dir = Path(run_dir)
+    manifest = read_json(run_dir / "snapshot.json") or {}
+    versions = manifest.get("versions") or []
+    texts = {int(p.stem.removeprefix("open-")): p.read_text() for p in (run_dir / "config").glob("open-*.yaml")}
+    configs, before = [], None
+    for opening, text in sorted(texts.items()):
+        opened_at = versions[opening - 1].get("opened_at") if opening <= len(versions) else None
+        configs.append(ConfigCopy(opening, opened_at, text, None if before is None else line_changes(before, text)))
+        before = text
+    snapshot = tuple(SnapshotFile(name, (run_dir / "snapshot" / name).read_text()) for name in manifest.get("files", {}))
+    return RunFiles(tuple(sorted(configs, key=lambda c: c.opening, reverse=True)), snapshot)

factor_agent/web/_diagnosis.py

@@ -0,0 +1,110 @@
+"""The diagnosis: at most three findings in a run's trials, each with what to do about it.
+
+The rules and their thresholds are fixed here. Each finding counts trials,
+not attempts: a trial is counted once whichever of its versions met the
+problem.
+"""
+
+from dataclasses import dataclass
+
+from factor_agent.web._ledger import THRESHOLD, Trial, neighbour
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One finding of a run's diagnosis: a thing seen in its trials and what to do about it.
+
+    ``rule`` names the rule that found it: ``"unreadable_replies"``,
+    ``"known_collisions"`` (one of the user's known factors),
+    ``"accepted_collisions"`` (factors the run accepted), ``"coverage_refusals"``,
+    ``"graph_build_failures"`` or ``"below_threshold"``. ``trials`` counts the
+    trials it concerns. ``seen`` and ``do`` are sentences for the page.
+    """
+
+    rule: str
+    trials: int
+    seen: str
+    do: str
+
+
+#: Findings shown at most.
+_FINDINGS = 3
+
+#: The share of trials above which unreadable replies, coverage refusals and graph build failures are findings.
+_UNREADABLE_SHARE, _COVERAGE_SHARE, _BUILD_SHARE = 0.20, 0.15, 0.15
+
+#: The number of trials above which collisions with one known factor, or with accepted ones, are a finding.
+_COLLIDING_TRIALS = 5
+
+
+def _refusals(trial: Trial) -> list[tuple[str, str]]:
+    """Every (stage, reason) the trial's versions were refused with, its final refusal among them."""
+    found = [(attempt.get("stage", ""), r) for attempt in trial.attempts for r in attempt.get("reasons") or ()]
+    return found + [(trial.stage, r) for r in trial.reasons]
+
+
+def _share(count: int, total: int) -> str:
+    """``count`` of ``total`` trials, with the percentage."""
+    return f"{count} of {total} trials ({count / total:.0%})"
+
+
+def diagnosis(trials: tuple[Trial, ...]) -> tuple[Finding, ...]:
+    """The findings of the rules that hold, the most trials first, at most three.
+
+    Collisions with a reference factor are no finding: the reference pool is
+    there to be compared with, while a known factor the run keeps rewriting
+    is one the user may not mean to name, and an accepted one shows the
+    novelty checks at work.
+    """
+    n = len(trials)
+    if not n:
+        return ()
+    findings = []
+    unreadable = sum(any(stage == "parse" for stage, _ in _refusals(t)) for t in trials)
+    if unreadable > _UNREADABLE_SHARE * n:
+        findings.append(Finding(
+            "unreadable_replies", unreadable,
+            f"Unreadable LLM replies: {_share(unreadable, n)}.",
+            "Change the model or raise its output limit."))
+    known, accepted = {}, {}
+    for trial in trials:
+        for collision in {c.label: c for c in trial.collisions}.values():
+            if collision.known:
+                known.setdefault(collision.label, []).append(trial)
+            elif collision.accepted_round is not None:
+                accepted.setdefault(collision.label, []).append(trial)
+    if known:
+        label, colliding = max(known.items(), key=lambda item: len(item[1]))
+        if len(colliding) > _COLLIDING_TRIALS:
+            findings.append(Finding(
+                "known_collisions", len(colliding),
+                f"Collided with your known factor {label}: {_share(len(colliding), n)}.",
+                "Steer the research directions away from it, or check your known factors."))
+    merged = {id(t) for colliding in accepted.values() for t in colliding}
+    if len(merged) > _COLLIDING_TRIALS:
+        names = ", ".join(f"{neighbour(label, None).name} ({len(colliding)})"
+                          for label, colliding in sorted(accepted.items(), key=lambda item: -len(item[1])))
+        findings.append(Finding(
+            "accepted_collisions", len(merged),
+            f"Collided with factors the run accepted: {_share(len(merged), n)} ({names}).",
+            "Expected: the novelty checks at work. If it persists, change the research directions."))
+    coverage = sum(any(stage == "admission" and r.startswith("coverage ") for stage, r in _refusals(t)) for t in trials)
+    if coverage > _COVERAGE_SHARE * n:
+        findings.append(Finding(
+            "coverage_refusals", coverage,
+            f"Too few members covered: {_share(coverage, n)}.",
+            "Check your data's fields and dates."))
+    builds = sum(any(r.startswith(("graph build failed", "graph build crashed")) for _, r in _refusals(t)) for t in trials)
+    if builds > _BUILD_SHARE * n:
+        findings.append(Finding(
+            "graph_build_failures", builds,
+            f"Code failed to build: {_share(builds, n)}.",
+            "Check the operator file, or try another model."))
+    evaluated = [t for t in trials if t.metrics is not None]
+    below = sum(any(THRESHOLD.search(r) for r in t.reasons) for t in evaluated)
+    if not any(t.status == "accepted" for t in trials) and below > len(evaluated) / 2:
+        findings.append(Finding(
+            "below_threshold", below,
+            f"Nothing accepted: {below} of {len(evaluated)} evaluated trials below the t threshold.",
+            "The statistical bar, not an error: run more rounds or change the research directions."))
+    return tuple(sorted(findings, key=lambda f: -f.trials)[:_FINDINGS])

factor_agent/web/_files.py

@@ -0,0 +1,78 @@
+"""The run directory's files as every part of the reader opens them, and its events replayed once."""
+
+import difflib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from factor_agent import events
+
+
+@dataclass(frozen=True)
+class LineChange:
+    """One line of a text compared with the text before it.
+
+    ``change`` is ``"kept"``, ``"added"`` (not in the text before) or
+    ``"removed"`` (in the text before, not in this one).
+    """
+
+    change: str
+    line: str
+
+
+def line_changes(before: str, after: str) -> tuple[LineChange, ...]:
+    """The lines of ``before`` and ``after`` in order, each marked kept, added or removed."""
+    old, new = before.splitlines(), after.splitlines()
+    lines = []
+    for tag, i1, i2, j1, j2 in difflib.SequenceMatcher(a=old, b=new, autojunk=False).get_opcodes():
+        if tag == "equal":
+            lines += [LineChange("kept", line) for line in new[j1:j2]]
+            continue
+        lines += [LineChange("removed", line) for line in old[i1:i2]]
+        lines += [LineChange("added", line) for line in new[j1:j2]]
+    return tuple(lines)
+
+
+def loads(text: str):
+    """JSON text read with NaN as ``None``: the ledger and the Acceptance reports write NaN where a value is undefined."""
+    return json.loads(text, parse_constant=lambda _: None)
+
+
+def read_json(path: Path):
+    """The JSON file at ``path``, ``None`` when there is none."""
+    try:
+        return loads(path.read_text())
+    except FileNotFoundError:
+        return None
+
+
+def utc(seconds: float) -> datetime:
+    """The UTC time of a file time."""
+    return datetime.fromtimestamp(seconds, timezone.utc)
+
+
+def call_files(run_dir: Path) -> list[Path]:
+    """The run's call files, in no order."""
+    return list((run_dir / "llm_log").glob("*.json"))
+
+
+def written(run_dir: Path) -> list[Path]:
+    """The run's files that change while it runs."""
+    files = [run_dir / name for name in ("snapshot.json", "state.json", "ledger.jsonl", events.FILE)]
+    return [p for p in files if p.exists()] + call_files(run_dir)
+
+
+class Replayed:
+    """A run's events, and those since its latest opening (``current``), the opening first."""
+
+    def __init__(self, replayed: list[events.Event]):
+        self.all = replayed
+        openings = [i for i, event in enumerate(replayed) if isinstance(event, events.Start)]
+        self.current = replayed[openings[-1]:] if openings else []
+        self.opened: events.Start | None = self.current[0] if self.current else None
+
+    @classmethod
+    def read(cls, run_dir: Path) -> "Replayed":
+        """The events of the run in ``run_dir``; none when it has no events file."""
+        return cls(events.read(run_dir / events.FILE))