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

factor_agent/web/_health.py

@@ -0,0 +1,207 @@
+"""What a run is doing now: whether it stopped, its phase, its process, its calls and tokens, the time it has left.
+
+A resumed run keeps the stop of its previous open in its state file until
+it stops again. With events, a stop counts only when a stop event follows
+the latest start or resume. Without, it counts only when the state file
+was written after the run's latest open and no LLM call ended after it.
+The process that opened the run last is looked for only on the host it
+ran on; on another host it is unknown, never gone.
+"""
+
+import socket
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import psutil
+
+from factor_agent import events
+from factor_agent.web._files import Replayed, call_files, utc
+
+
+@dataclass(frozen=True)
+class Stop:
+    """Why a run stopped, as the campaign recorded it: ``by`` is the stop condition, ``reason`` its sentence."""
+
+    by: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Tokens:
+    """Tokens of LLM calls as the providers report them; a count no reply reported is ``None``.
+
+    ``cache_hits`` are input tokens the provider read from its cache, and
+    ``reasoning`` output tokens the model spent reasoning.
+    """
+
+    input: int | None
+    output: int | None
+    cache_hits: int | None
+    reasoning: int | None
+
+
+@dataclass(frozen=True)
+class RoundTokens:
+    """The tokens of a round's calls."""
+
+    round: int
+    tokens: Tokens
+
+
+@dataclass(frozen=True)
+class Health:
+    """What a run is doing now, as its events file and its process tell.
+
+    ``phase`` is ``"planning"`` (a round is written, or the run was just
+    opened, and no call of the next round has been sent), ``"asking"`` (the
+    LLM is being asked for the round in progress) or ``"evaluating"`` (the
+    Evaluator scores the round's candidates); ``None`` when the run has
+    stopped or crashed, or has no events file. ``round`` is the round in
+    progress and ``max_rounds`` the round limit, ``None`` when the run has
+    stopped or the limit is unknown. ``process`` is ``"running"`` or
+    ``"gone"`` when the campaign's process is checked on this host, and
+    ``"unknown"`` when the campaign ran on another host or the run has no
+    events file; ``crashed`` is true when the process is gone and the run
+    recorded no stop. ``last_call`` is when the latest LLM call came back
+    (UTC). ``stalled`` is true when the run looks stuck: no call was sent
+    or came back for ``STALL_ASKING`` while asking. An evaluation never
+    looks stuck: its length follows the data (an intraday round's takes
+    hours), so no limit tells a slow one from a stuck one. ``calls`` counts the calls of the round in
+    progress by role, since the run was last opened; a run without an
+    events file has only these counts, from its call files. ``tokens`` are
+    the tokens of every call of the run, a round a resume dropped
+    included, and ``round_tokens`` the same by round; ``None`` and empty
+    without an events file. ``time_left`` estimates the seconds until the
+    round or trial limit stops the run, from the mean length of its last
+    ``RECENT_ROUNDS`` rounds; ``None`` while no round was timed, and once
+    the run has stopped or crashed.
+    """
+
+    phase: str | None
+    round: int | None
+    max_rounds: int | None
+    process: str
+    crashed: bool
+    last_call: datetime | None
+    stalled: bool
+    calls: dict[str, int]
+    time_left: float | None
+    tokens: Tokens | None
+    round_tokens: tuple[RoundTokens, ...]
+
+
+#: The events of each phase of a round: the first a phase starts with, the later ones it goes on with.
+_PHASES = {
+    events.Start: "planning", events.Resume: "planning", events.RoundEnd: "planning",
+    events.CallStart: "asking", events.CallEnd: "asking", events.Plan: "asking", events.GateOutcome: "asking",
+    events.ReviewVerdict: "asking",
+    events.EvaluationStart: "evaluating", events.AdmissionOutcome: "evaluating",
+}
+
+#: How long a run asking the LLM may go without a call sent or back before it looks stuck.
+STALL_ASKING = timedelta(minutes=15)
+
+#: How many of the latest timed rounds the time left is estimated from.
+RECENT_ROUNDS = 3
+
+
+def stop(run_dir: Path, state: dict, opened_at: str | None, replayed: Replayed) -> Stop | None:
+    """The state's stop, unless it was recorded before the latest open (see the module's notes)."""
+    if not state.get("stop"):
+        return None
+    if replayed.opened is not None:
+        if not any(isinstance(event, events.Stopped) for event in replayed.current):
+            return None
+        return Stop(by=state["stop"]["by"], reason=state["stop"]["reason"])
+    written = (run_dir / "state.json").stat().st_mtime_ns
+    if opened_at and written < datetime.fromisoformat(opened_at).timestamp() * 1e9:
+        return None
+    if any(p.stat().st_mtime_ns > written for p in call_files(run_dir)):
+        return None
+    return Stop(by=state["stop"]["by"], reason=state["stop"]["reason"])
+
+
+def health(
+    run_dir: Path, state: dict, rounds: int, trials: int, stopped: bool, replayed: Replayed, now: datetime,
+) -> Health:
+    """The health of a run with ``rounds`` rounds and ``trials`` trials written, ``stopped`` or not, at ``now``."""
+    opened = replayed.opened
+    process = process_state(opened)
+    crashed = not stopped and process == "gone"
+    phase = None
+    if opened is not None and not stopped and not crashed:
+        phase = _PHASES.get(type(replayed.current[-1]))
+    running = None if stopped else rounds + 1
+    ends = [e for e in replayed.all if isinstance(e, events.CallEnd) and e.error is None]
+    if opened is None:
+        files = sorted(call_files(run_dir))
+        last_call = utc(max(p.stat().st_mtime for p in files)) if files else None
+        roles = [] if running is None else [p.stem.partition("-")[2] for p in files[state.get("calls", 0):]]
+    else:
+        last_call = ends[-1].time if ends else None
+        roles = [e.role for e in replayed.current if isinstance(e, events.CallEnd) and e.file and e.round == running]
+    by_round = {}
+    for end in ends:
+        by_round.setdefault(end.round, []).append(end)
+    return Health(
+        phase=phase, round=running, max_rounds=opened.max_rounds if opened else None, process=process,
+        crashed=crashed, last_call=last_call, stalled=_stalled(phase, replayed, now),
+        calls={role: roles.count(role) for role in dict.fromkeys(roles)},
+        time_left=None if running is None or crashed else _time_left(rounds, trials, replayed, now),
+        tokens=_tokens(ends) if opened else None,
+        round_tokens=tuple(RoundTokens(number, _tokens(calls)) for number, calls in sorted(by_round.items())),
+    )
+
+
+def _time_left(rounds: int, trials: int, replayed: Replayed, now: datetime) -> float | None:
+    """The seconds the rounds the limits still allow would take at the recent rounds' pace, the round begun included.
+
+    A round is timed from the end of the round before, or the opening of
+    the run when it was the first after it, to its own end.
+    """
+    opened = replayed.opened
+    if opened is None:
+        return None
+    lengths, since = [], None
+    for event in replayed.all:
+        if isinstance(event, (events.Start, events.RoundEnd)):
+            if isinstance(event, events.RoundEnd) and since is not None:
+                lengths.append((event.time - since).total_seconds())
+            since = event.time
+    if not lengths:
+        return None
+    left = min(opened.max_rounds - rounds, (opened.max_trials - trials) // max(opened.candidates, 1))
+    pace = sum(lengths[-RECENT_ROUNDS:]) / len(lengths[-RECENT_ROUNDS:])
+    return max(0.0, pace * left - (now - since).total_seconds())
+
+
+def _tokens(ends: list[events.CallEnd]) -> Tokens:
+    """The tokens of the calls that ``ends`` end, each count ``None`` when no call reported it."""
+    def total(key):
+        counts = [getattr(end, key) for end in ends if getattr(end, key) is not None]
+        return sum(counts) if counts else None
+    return Tokens(total("input_tokens"), total("output_tokens"), total("cache_hits"), total("reasoning"))
+
+
+def _stalled(phase: str | None, replayed: Replayed, now: datetime) -> bool:
+    """Whether a run asking has had no call sent or back for ``STALL_ASKING``."""
+    if phase != "asking":
+        return False
+    # The opening counts as the first sign of life, a failed call's end as one too.
+    activity = [e.time for e in replayed.current if isinstance(e, (events.Start, events.CallStart, events.CallEnd))]
+    return now - activity[-1] > STALL_ASKING
+
+
+def process_state(opened: events.Start | None) -> str:
+    """Whether the process that opened the run last still runs, when it ran on this host."""
+    if opened is None or opened.host != socket.gethostname():
+        return "unknown"
+    try:
+        started = psutil.Process(opened.pid).create_time()
+    except psutil.NoSuchProcess:
+        return "gone"
+    except psutil.Error:
+        return "unknown"
+    # A process started after the run was opened has only been given the same id.
+    return "running" if started <= opened.time.timestamp() + 1 else "gone"

factor_agent/web/_ic.py

@@ -0,0 +1,27 @@
+"""A trial's daily IC, as the campaign keeps it in ``ic/round_NN.json`` for each evaluated trial."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from factor_agent.web._files import read_json
+
+
+@dataclass(frozen=True)
+class TrialIC:
+    """An evaluated trial's daily rank IC and partial IC on each day of the label, ``None`` where unscored.
+
+    The values are raw, as the Evaluator computed them; the page turns them to the factor's direction.
+    """
+
+    days: tuple[str, ...]
+    ic: tuple[float | None, ...]
+    partial_ic: tuple[float | None, ...]
+
+
+def read_ic(run_dir: str | Path, round: int, slot: int) -> TrialIC | None:
+    """The daily IC of trial ``slot`` (from 0) of ``round``; ``None`` when it was not evaluated or the run kept none."""
+    kept = read_json(Path(run_dir) / "ic" / f"round_{round:02d}.json")
+    series = (kept or {}).get("slots", {}).get(str(slot))
+    if series is None:
+        return None
+    return TrialIC(tuple(kept["days"]), tuple(series["ic"]), tuple(series["partial_ic"]))

factor_agent/web/_ledger.py

@@ -0,0 +1,293 @@
+"""The trials of a run's written rounds, the collisions their refusals name, and the limits admission judged them by."""
+
+import json
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+from factor_agent import events
+from factor_agent.web._files import Replayed, loads, read_json
+
+
+@dataclass(frozen=True)
+class Collision:
+    """A trial's refusal for being too like an existing factor: a reference, known or accepted one.
+
+    ``label`` names the factor as the Gate and the Evaluator do; ``name`` is
+    how a page names it, as ``Neighbour.name``. ``kind`` is ``"code"`` (the
+    Gate found a rewrite, the same graph with other parameters, or a too
+    large shared subtree) or ``"ranking"`` (admission found a correlation
+    above the limit). ``accepted_round`` is the round that accepted the
+    factor, ``None`` for one of the user's own factors; ``known`` is true
+    for a known factor, false for a reference or accepted one.
+    """
+
+    label: str
+    name: str
+    kind: str
+    accepted_round: int | None
+    known: bool
+
+
+@dataclass(frozen=True)
+class Trial:
+    """One trial of a written round, as the ledger holds it, with NaN read as ``None``.
+
+    ``slot`` is the trial's place in its round, from 0, in the order of the
+    round's research directions. ``status``, ``stage``, ``reasons``,
+    ``candidate``, ``direction``, ``attempts``, ``stats`` and ``metrics`` are
+    the trial record's (``factor_agent.ledger.TrialRecord``); ``metrics`` is
+    ``None`` for a trial the Evaluator never scored. ``collisions`` holds
+    every collision of the trial's versions, each factor and kind once.
+    ``intraday`` is true when the graph the Gate built holds a session
+    aggregation, false for a daily graph and a trial the Gate built none for.
+    """
+
+    round: int
+    slot: int
+    status: str
+    stage: str
+    reasons: tuple[str, ...]
+    candidate: dict
+    direction: dict | None
+    attempts: tuple[dict, ...]
+    stats: dict | None
+    metrics: dict | None
+    collisions: tuple[Collision, ...] = ()
+    intraday: bool = False
+
+
+@dataclass(frozen=True)
+class Neighbour:
+    """The factor closest to an accepted one in ranking, and their correlation.
+
+    ``label`` names it as the Evaluator does. ``name`` is how a page names
+    it: a factor accepted earlier in the run as ``"round N: "`` and the first
+    words of its description, any other by its label. ``accepted_round`` is
+    N for a factor accepted in the run, ``None`` for a reference or known
+    factor. ``correlation`` is the raw cross-sectional correlation, which
+    admission compares in absolute value with its limit.
+    """
+
+    label: str
+    name: str
+    accepted_round: int | None
+    correlation: float | None
+
+
+def _records(ledger: Path, rounds: int):
+    """The ledger's records of the first ``rounds`` rounds; later rounds and a line a crash cut short are skipped."""
+    try:
+        lines = ledger.read_text().splitlines()
+    except FileNotFoundError:
+        return
+    for line in lines:
+        try:
+            record = loads(line)
+        except json.JSONDecodeError:
+            continue
+        if record["round"] <= rounds:
+            yield record
+
+
+def statuses(ledger: Path, rounds: int) -> list[str]:
+    """The status of every trial of the first ``rounds`` rounds, in ledger order: what a run's summary counts."""
+    return [record["status"] for record in _records(ledger, rounds)]
+
+
+def read_trials(ledger: Path, rounds: int, aggregations: frozenset[str] = frozenset()) -> tuple[Trial, ...]:
+    """The trials of the first ``rounds`` rounds, each given its slot in its round.
+
+    ``aggregations`` are the names the run's graphs record its session
+    aggregations under (``aggregations``): a trial whose graph holds one is intraday.
+    """
+    trials, slots = [], {}
+    for record in _records(ledger, rounds):
+        slot = slots[record["round"]] = slots.get(record["round"], -1) + 1
+        trials.append(Trial(
+            round=record["round"], slot=slot, status=record["status"], stage=record["stage"],
+            reasons=tuple(record["reasons"]), candidate=record["candidate"], direction=record.get("direction"),
+            attempts=tuple(record.get("attempts") or ()), stats=record.get("stats"), metrics=record.get("metrics"),
+            collisions=_trial_collisions(record),
+            intraday=any(node[0] in aggregations for node in record.get("graph") or ()),
+        ))
+    return tuple(trials)
+
+
+def aggregations(run_dir: Path) -> frozenset[str]:
+    """The names the run's operator file registers its session aggregations under; none for a daily run.
+
+    Only a run whose snapshot records an intraday dataset has an intraday
+    family, and only it may use an aggregation. An operator is one when its
+    class, from the modules an aggregation may come from, is a
+    ``SessionAggregation``; a class of another module is not imported.
+    """
+    manifest = read_json(run_dir / "snapshot.json") or {}
+    if "intraday" not in (manifest.get("settings") or {}):
+        return frozenset()
+    operators = next((name for name in manifest.get("files") or {} if name.startswith("operators/")), None)
+    try:
+        return _aggregations((run_dir / "snapshot" / operators).read_text()) if operators else frozenset()
+    except OSError:
+        return frozenset()
+
+
+@lru_cache(maxsize=16)
+def _aggregations(text: str) -> frozenset[str]:
+    """The aggregations of the operator file ``text``, by their names; see ``aggregations``."""
+    # Imported here, so a daily run's view never imports the operator classes.
+    from factor_agent.aggregations import SessionAggregation
+    from factor_agent.gate.vocabulary import FRAMEWORK_MODULES, resolve
+
+    try:
+        entries = (yaml.safe_load(text) or {}).get("operators") or []
+    except (yaml.YAMLError, AttributeError):
+        return frozenset()
+    found = set()
+    for entry in entries:
+        path = entry.get("class") if isinstance(entry, dict) else None
+        if not isinstance(path, str) or not any(path.startswith(root + ".") for root in FRAMEWORK_MODULES):
+            continue
+        try:
+            cls = resolve(path, FRAMEWORK_MODULES)
+        except (ImportError, AttributeError):
+            continue
+        if isinstance(cls, type) and issubclass(cls, SessionAggregation):
+            found.add(entry.get("name"))
+    return frozenset(found)
+
+
+#: The partial-IC t threshold an admission refusal quotes.
+THRESHOLD = re.compile(r"is below the threshold ([\d.]+) at \d+ evaluated trial")
+
+#: The correlation limit an admission refusal quotes.
+_LIMIT = re.compile(r"^cross-sectional correlation .* is above ([\d.]+) in absolute value$", re.DOTALL)
+
+
+def correlation_limit(trials: tuple[Trial, ...], replayed: Replayed) -> float | None:
+    """The correlation limit the run was last opened with, else the latest refusal quoting it, else ``None``."""
+    if replayed.opened is not None:
+        return replayed.opened.max_correlation
+    quoted = [found.group(1) for trial in trials for reason in trial.reasons if (found := _LIMIT.match(reason))]
+    return float(quoted[-1]) if quoted else None
+
+
+def thresholds(trials: tuple[Trial, ...], replayed: Replayed) -> dict[int, tuple[float | None, str | None]]:
+    """Each round's threshold and where it comes from: ``"admission"``, ``"refusals"`` or ``"carried_over"``.
+
+    A round's admission events give it; without them its refusals quote it;
+    when neither does it is the round before's, carried over. The admission
+    events of a round a resume dropped come before those of the round run
+    again under the same number, so the later ones count. A round before
+    any threshold has ``(None, None)``.
+    """
+    given = {}
+    for trial in trials:
+        for reason in trial.reasons:
+            if found := THRESHOLD.search(reason):
+                given[trial.round] = (float(found.group(1)), "refusals")
+    for event in replayed.all:
+        if isinstance(event, events.AdmissionOutcome) and event.threshold is not None:
+            given[event.round] = (event.threshold, "admission")
+    found, last = {}, None
+    for number in sorted({trial.round for trial in trials}):
+        if number in given:
+            found[number] = last = given[number]
+        else:
+            found[number] = (None, None) if last is None else (last[0], "carried_over")
+    return found
+
+
+#: An accepted factor's label: its description and the round that accepted it.
+_ACCEPTED = re.compile(r"^(.*) \(accepted in round (\d+)\)$", re.DOTALL)
+
+#: How many words of an earlier accepted factor's description name it.
+_FIRST_WORDS = 6
+
+
+def neighbour(label: str | None, correlation: float | None) -> Neighbour | None:
+    """The nearest factor the Evaluator recorded, ``None`` when there was none to compare with."""
+    if not label:
+        return None
+    if accepted := _ACCEPTED.match(label):
+        words = accepted.group(1).split()
+        first = " ".join(words[:_FIRST_WORDS]) + ("…" if len(words) > _FIRST_WORDS else "")
+        number = int(accepted.group(2))
+        return Neighbour(label=label, name=f"round {number}: {first}", accepted_round=number, correlation=correlation)
+    return Neighbour(label=label, name=label, accepted_round=None, correlation=correlation)
+
+
+#: The refusals that name the factors a candidate collided with, by kind; group 1 holds the names.
+_COLLISIONS = (
+    ("code", re.compile(r"^the factor rewrites (.+?(?:\)| more)): ", re.DOTALL)),
+    ("code", re.compile(r"^the factor is (.+?) with other windows or parameter values only; ", re.DOTALL)),
+    ("code", re.compile(r"^the factor shares a \d+-node subtree with (.+?), more than the limit of \d+: ", re.DOTALL)),
+    ("ranking", re.compile(
+        r"^cross-sectional correlation [-+]?[\d.]+ with (.+?)(?:, sampled on [^,]*,)? is above [\d.]+ in absolute value$",
+        re.DOTALL)),
+)
+
+#: One label in the Gate's list of them: a reference, known or accepted factor's label ends in its parentheses.
+_LABEL = re.compile(r"(.+?) \((accepted in round \d+|[\w.]+(?:, a known factor)?)\)(?:, |(?: and \d+ more)?$)", re.DOTALL)
+
+
+def _collisions(reason: str) -> list[Collision]:
+    """The collisions a refusal names, none for any other refusal."""
+    for kind, pattern in _COLLISIONS:
+        if found := pattern.match(reason):
+            names = found.group(1)
+            labels = [names] if kind == "ranking" else [f"{m[1]} ({m[2]})" for m in _LABEL.finditer(names)]
+            return [_collision(label, kind) for label in labels]
+    return []
+
+
+def _collision(label: str, kind: str) -> Collision:
+    """The collision of ``kind`` with the factor ``label`` names."""
+    named = neighbour(label, None)
+    return Collision(label=label, name=named.name, kind=kind, accepted_round=named.accepted_round,
+                     known=label.endswith(", a known factor)"))
+
+
+def _trial_collisions(record: dict) -> tuple[Collision, ...]:
+    """Every collision of a trial's versions, each factor and kind once."""
+    reasons = [r for attempt in record.get("attempts") or () for r in attempt.get("reasons") or ()]
+    found = {}
+    for reason in reasons + list(record["reasons"]):
+        for collision in _collisions(reason):
+            found.setdefault((collision.label, collision.kind), collision)
+    return tuple(found.values())
+
+
+def in_direction(metrics: dict) -> tuple[int, dict[str, float | None]]:
+    """A scored trial's direction, +1 or -1 by the sign of its training IC, and its ICs and t in that direction."""
+    sign = 1 if (metrics.get("ic_mean") or 0) > 0 else -1
+    return sign, {key: None if metrics.get(key) is None else sign * metrics[key]
+                  for key in ("ic_mean", "ic_t", "partial_ic_mean", "partial_ic_t")}
+
+
+def _ranks(values: list[float]) -> list[float]:
+    """Each value's rank from 1, ties given their mean rank."""
+    order = sorted(range(len(values)), key=values.__getitem__)
+    ranks = [0.0] * len(values)
+    start = 0
+    while start < len(order):
+        end = start
+        while end + 1 < len(order) and values[order[end + 1]] == values[order[start]]:
+            end += 1
+        for i in order[start:end + 1]:
+            ranks[i] = (start + end) / 2 + 1
+        start = end + 1
+    return ranks
+
+
+def monotonicity(deciles: tuple[float | None, ...], sign: int) -> float | None:
+    """The Spearman correlation of the decile number with the decile returns, signed by ``sign``, as admission's."""
+    if len(deciles) < 2 or any(r is None for r in deciles) or len(set(deciles)) == 1:
+        return None
+    ranks, n = _ranks(list(deciles)), len(deciles)
+    mean = (n + 1) / 2
+    spread = sum((r - mean) ** 2 for r in ranks) * sum((i + 1 - mean) ** 2 for i in range(n))
+    return sign * sum((r - mean) * (i + 1 - mean) for i, r in enumerate(ranks)) / spread ** 0.5

factor_agent/web/_memory.py

@@ -0,0 +1,42 @@
+"""The memory's versions, as the distiller wrote them in ``memory/round_NN.md``, each compared with the one before."""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from factor_agent.web._files import LineChange, line_changes
+
+
+#: One line of a memory version compared with the version before it; see ``LineChange``.
+MemoryLine = LineChange
+
+
+@dataclass(frozen=True)
+class MemoryVersion:
+    """One version of the memory the distiller wrote.
+
+    ``round`` is the round after which it was written. ``changes`` holds the
+    lines of this version and of the one before, in order, each marked kept,
+    added or removed; it is ``None`` for the run's first version.
+    """
+
+    round: int
+    text: str
+    changes: tuple[MemoryLine, ...] | None
+
+
+def memory(folder: Path) -> tuple[MemoryVersion, ...]:
+    """The memory's versions, the earliest first, each but the first compared with the one before.
+
+    ``round_NN.md`` is written before round ``NN``, so after round ``NN - 1``.
+    """
+    files = {}
+    for path in folder.glob("round_*.md"):
+        if match := re.fullmatch(r"round_(\d+)\.md", path.name):
+            files[int(match[1]) - 1] = path.read_text().rstrip("\n")
+    versions, before = [], None
+    for number, text in sorted(files.items()):
+        versions.append(MemoryVersion(round=number, text=text, changes=None if before is None else line_changes(before, text)))
+        before = text
+    return tuple(versions)
+

factor_agent/web/_results.py

@@ -0,0 +1,77 @@
+"""The results page's accepted factors, each with the facts that say how far to trust it."""
+
+from dataclasses import dataclass
+
+from factor_agent.web._files import Replayed
+from factor_agent.web._ledger import Neighbour, Trial, in_direction, monotonicity, neighbour, thresholds
+
+
+@dataclass(frozen=True)
+class Factor:
+    """An accepted factor, written up with the facts that say how far to trust it.
+
+    ``label`` is the name the Evaluator and Acceptance give it,
+    ``"<description> (accepted in round N)"``. ``round``, ``slot`` and
+    ``mechanism_type`` place it in the run; ``hypothesis``, ``description``
+    and ``code`` are its candidate's. ``factor_direction`` is +1 when a
+    higher value went with a higher training return, -1 when with a lower
+    one. ``ic_mean``, ``ic_t``, ``partial_ic_mean`` and ``partial_ic_t`` are
+    the training IC and the partial IC and their Newey-West t, in the
+    factor's direction, as admission judged them; ``metrics`` holds every
+    statistic as the ledger records it, the raw values among them.
+    ``threshold`` is its round's t threshold and ``threshold_source`` where
+    it comes from: ``"admission"`` (the admission events of its round),
+    ``"refusals"`` (what its round's refusals quote, for a run without
+    events) or ``"carried_over"`` (neither gives it, so it is an earlier
+    round's); both are ``None`` while nothing gives a threshold.
+    ``decile_returns`` and ``coverage`` are the Evaluator's. ``intraday``
+    is its trial's (``Trial.intraday``): its graph holds a session aggregation.
+    """
+
+    label: str
+    round: int
+    slot: int
+    mechanism_type: str | None
+    hypothesis: str
+    description: str
+    code: str
+    factor_direction: int
+    ic_mean: float | None
+    ic_t: float | None
+    partial_ic_mean: float | None
+    partial_ic_t: float | None
+    threshold: float | None
+    threshold_source: str | None
+    monotonicity: float | None
+    nearest: Neighbour | None
+    nearest_known: Neighbour | None
+    decile_returns: tuple[float | None, ...]
+    coverage: float | None
+    metrics: dict
+    intraday: bool = False
+
+
+def factors(trials: tuple[Trial, ...], replayed: Replayed) -> tuple[Factor, ...]:
+    """The accepted factors, in the order they were accepted."""
+    by_round = thresholds(trials, replayed)
+    found = []
+    for trial in trials:
+        if trial.status != "accepted":
+            continue
+        metrics, candidate = trial.metrics, trial.candidate
+        sign, oriented = in_direction(metrics)
+        deciles = tuple(metrics.get("decile_returns") or ())
+        threshold, source = by_round[trial.round]
+        found.append(Factor(
+            label=f"{candidate['description']} (accepted in round {trial.round})",
+            round=trial.round, slot=trial.slot, mechanism_type=(trial.direction or {}).get("mechanism_type"),
+            hypothesis=candidate.get("hypothesis", ""), description=candidate["description"], code=candidate["code"],
+            factor_direction=sign, ic_mean=oriented["ic_mean"], ic_t=oriented["ic_t"],
+            partial_ic_mean=oriented["partial_ic_mean"], partial_ic_t=oriented["partial_ic_t"],
+            threshold=threshold, threshold_source=source, monotonicity=monotonicity(deciles, sign),
+            nearest=neighbour(metrics.get("nearest"), metrics.get("nearest_correlation")),
+            nearest_known=neighbour(metrics.get("nearest_known"), metrics.get("nearest_known_correlation")),
+            decile_returns=deciles, coverage=metrics.get("coverage"), metrics=metrics,
+            intraday=trial.intraday,
+        ))
+    return tuple(found)