quantlab-factor-agent 0.1.0__tar.gz → 0.2.0__tar.gz

{quantlab_factor_agent-0.1.0/quantlab_factor_agent.egg-info → quantlab_factor_agent-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantlab-factor-agent
-Version: 0.1.0
+Version: 0.2.0
 Summary: LLM-driven, mechanism-first formulaic factor research on quantlab, evaluated with KunQuant.
 Author: Zhaorong Dai
 License-Expression: MIT AND Apache-2.0
@@ -148,14 +148,56 @@ print(report.markdown())
 
 Point the config's data paths at your own quantlab stores first. A campaign runs for hours,
 mostly waiting on the model, and needs no GPU; `Acceptance` uses CUDA when it is available.
-Watch a run in the browser with `factor-agent-web` ([web frontend](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/web.md)).
+Before a long run, `factor-agent check <config>` reports everything `run()` would refuse
+(a store that does not exist, an unset API key variable, a resume that changed the
+config) in seconds, without writing anything; `--ping` also sends each backend one short
+request.
+
+## Watch a run in the browser
+
+```bash
+factor-agent-web runs/    # then open http://127.0.0.1:8000
+```
+
+The web panel lists your runs and opens each one: whether its accepted factors improve
+your model, a card per factor, every trial on a Lineage graph and the admission map, the
+LLM calls of the round in progress, the memory and the config. It only reads the run
+directory, listens on localhost only, and on a server you reach it through an SSH tunnel.
+See [the web frontend](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/web.md).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ZhaorongDai/quantlab-factor-agent/main/docs/_static/web/trials-lineage.png" alt="The trials page: a round's plan with its Picked parents outlined in blue, the Lineage graph of every trial by round with arrows from parent to child, and the admission map of partial-IC t against the largest correlation with an existing factor" width="100%">
+</p>
+
+## Building on earlier trials
+
+Every trial after the first round either starts a new direction or builds on an earlier
+one, its parent, as a refinement or a mutation. A trial's **Lineage** sums up the trials
+built on it: how many, how many stopped early, which were accepted and how far the best
+got. With `context.lineage` the planner and the proposer read it. With
+`round.picked_parents: k` the code, not the planner, chooses the parents of k slots each
+round, the **Picked parents**: it ranks the evaluated trials by quality, fertility and
+novelty, each shared over the **Trial graph** of trials related by generation, code
+structure and correlation, so a trial whose relatives did well rises with them. The
+`trial_graph` section sets how much is shared and how the graph is built. Both are off by
+default. The web panel's
+"why these parents" shows, for each round, how propagation moved each trial's utilities
+and rank:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ZhaorongDai/quantlab-factor-agent/main/docs/_static/web/propagation.png" alt="The propagation view: per utility a trial's own value, its neighbours' average with the heaviest neighbours listed, and its value after propagation; beside it the rank ladder, where the trial rises from rank 15 to rank 10" width="100%">
+</p>
+
+See [building on earlier trials](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/concepts.md#building-on-earlier-trials)
+and [the campaign config](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/campaign.md#settings-with-defaults).
 
 ## Documentation
 
 - [How the agent mines factors](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/mechanism.md): the search, the judges, the learning loop and what the models may see, in one diagram
 - [First campaign](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/getting-started/quickstart.md): run one and read its outcome
 - [Concepts](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/concepts.md): roles, factor sets, segments, what "accepted" means
-- [The campaign config](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/campaign.md): every section, stopping and resuming
+- [The campaign config](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/campaign.md): every section, checking a config, stopping and resuming
+- [The web frontend](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/web.md): every page of the panel, and how to reach it on a server
 - [The vocabulary](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/vocabulary.md) and [prompts](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/prompts.md): what candidates may read and write, and what the models are told
 - [LLM backends](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/llm-backends.md): providers, the LLM log, replay, cost
 - [Gate, review and evaluation](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/evaluation.md) and [acceptance](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/acceptance.md): how a factor is judged

{quantlab_factor_agent-0.1.0 → quantlab_factor_agent-0.2.0}/README.md

@@ -113,14 +113,56 @@ print(report.markdown())
 
 Point the config's data paths at your own quantlab stores first. A campaign runs for hours,
 mostly waiting on the model, and needs no GPU; `Acceptance` uses CUDA when it is available.
-Watch a run in the browser with `factor-agent-web` ([web frontend](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/web.md)).
+Before a long run, `factor-agent check <config>` reports everything `run()` would refuse
+(a store that does not exist, an unset API key variable, a resume that changed the
+config) in seconds, without writing anything; `--ping` also sends each backend one short
+request.
+
+## Watch a run in the browser
+
+```bash
+factor-agent-web runs/    # then open http://127.0.0.1:8000
+```
+
+The web panel lists your runs and opens each one: whether its accepted factors improve
+your model, a card per factor, every trial on a Lineage graph and the admission map, the
+LLM calls of the round in progress, the memory and the config. It only reads the run
+directory, listens on localhost only, and on a server you reach it through an SSH tunnel.
+See [the web frontend](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/web.md).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ZhaorongDai/quantlab-factor-agent/main/docs/_static/web/trials-lineage.png" alt="The trials page: a round's plan with its Picked parents outlined in blue, the Lineage graph of every trial by round with arrows from parent to child, and the admission map of partial-IC t against the largest correlation with an existing factor" width="100%">
+</p>
+
+## Building on earlier trials
+
+Every trial after the first round either starts a new direction or builds on an earlier
+one, its parent, as a refinement or a mutation. A trial's **Lineage** sums up the trials
+built on it: how many, how many stopped early, which were accepted and how far the best
+got. With `context.lineage` the planner and the proposer read it. With
+`round.picked_parents: k` the code, not the planner, chooses the parents of k slots each
+round, the **Picked parents**: it ranks the evaluated trials by quality, fertility and
+novelty, each shared over the **Trial graph** of trials related by generation, code
+structure and correlation, so a trial whose relatives did well rises with them. The
+`trial_graph` section sets how much is shared and how the graph is built. Both are off by
+default. The web panel's
+"why these parents" shows, for each round, how propagation moved each trial's utilities
+and rank:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ZhaorongDai/quantlab-factor-agent/main/docs/_static/web/propagation.png" alt="The propagation view: per utility a trial's own value, its neighbours' average with the heaviest neighbours listed, and its value after propagation; beside it the rank ladder, where the trial rises from rank 15 to rank 10" width="100%">
+</p>
+
+See [building on earlier trials](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/concepts.md#building-on-earlier-trials)
+and [the campaign config](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/campaign.md#settings-with-defaults).
 
 ## Documentation
 
 - [How the agent mines factors](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/mechanism.md): the search, the judges, the learning loop and what the models may see, in one diagram
 - [First campaign](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/getting-started/quickstart.md): run one and read its outcome
 - [Concepts](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/concepts.md): roles, factor sets, segments, what "accepted" means
-- [The campaign config](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/campaign.md): every section, stopping and resuming
+- [The campaign config](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/campaign.md): every section, checking a config, stopping and resuming
+- [The web frontend](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/web.md): every page of the panel, and how to reach it on a server
 - [The vocabulary](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/vocabulary.md) and [prompts](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/prompts.md): what candidates may read and write, and what the models are told
 - [LLM backends](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/llm-backends.md): providers, the LLM log, replay, cost
 - [Gate, review and evaluation](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/evaluation.md) and [acceptance](https://github.com/ZhaorongDai/quantlab-factor-agent/blob/main/docs/user-guide/acceptance.md): how a factor is judged

{quantlab_factor_agent-0.1.0 → quantlab_factor_agent-0.2.0}/factor_agent/__init__.py

@@ -2,7 +2,7 @@
 
 from factor_agent import _expression_fold, _max_drawdown
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 _expression_fold.patch()
 _max_drawdown.patch()

{quantlab_factor_agent-0.1.0 → quantlab_factor_agent-0.2.0}/factor_agent/_admission.py

@@ -56,6 +56,11 @@ def direction(ic_mean: float) -> int:
     return int(np.sign(ic_mean)) if math.isfinite(ic_mean) else 0
 
 
+def directional_t(metrics: dict) -> float:
+    """An evaluated trial's residual (partial IC) Newey-West t in its direction, from its record's ``metrics``."""
+    return direction(metrics["ic_mean"]) * metrics["partial_ic_t"]
+
+
 def monotonicity(decile_returns, sign: int) -> float:
     """The Spearman correlation of the decile number with the decile returns, signed by ``sign``."""
     returns = np.asarray(decile_returns, dtype=float)

{quantlab_factor_agent-0.1.0 → quantlab_factor_agent-0.2.0}/factor_agent/_feedback.py

@@ -5,7 +5,8 @@ Newey-West t, its residual (partial) IC, what the pool explains of it and the
 pool factors most correlated with it, the order of its deciles' returns (as
 ranks), the nearest existing factor and the correlation with it, the nearest
 known factor and its sampled correlation, the rejection reasons, and each
-accepted factor's marginal weight and residual IC in the accepted pool. It
+accepted factor's marginal weight and residual IC in the accepted pool, and,
+when given, each accepted factor's and each parent's Lineage (``_lineage``). It
 never shows a return, a date, or advice to change windows or parameters. The first round
 has no history; it sees the data, the seed directions and the existing
 factor families (the reference set's, then the known factors', marked as
@@ -17,12 +18,16 @@ research direction names the trial it builds on (``parent``).
 
 import math
 import re
+from typing import TYPE_CHECKING
 
-from factor_agent._admission import direction, reason_kind
+from factor_agent._admission import direction, directional_t, reason_kind
 from factor_agent.evaluator import Contribution
 from factor_agent.ledger import TrialRecord
 from factor_agent.zoo import owner
 
+if TYPE_CHECKING:  # _lineage imports ``signed`` from here, so its Lineage is imported for the annotations only
+    from factor_agent._lineage import Lineage
+
 _DECIMAL = re.compile(r"[-+]?\d+\.\d+")
 _TRIAL_ID = re.compile(r"T(\d+)-(\d+)")
 
@@ -103,8 +108,8 @@ def history(
         if statistics and r.evaluated:
             m = r.metrics
             line += (
-                f"; training IC {_num(m['ic_mean'], 4)} (t {_num(m['ic_t'], 2)}), "
-                f"residual IC {_num(m['partial_ic_mean'], 4)} (t {_num(m['partial_ic_t'], 2)})"
+                f"; training IC {signed(m['ic_mean'], 4)} (t {signed(m['ic_t'], 2)}), "
+                f"residual IC {signed(m['partial_ic_mean'], 4)} (t {signed(m['partial_ic_t'], 2)})"
             )
             share = m.get("pool_share", float("nan"))
             if share is not None and math.isfinite(share) and share > 0:
@@ -162,7 +167,7 @@ def theme_groups(names: list[str], matrix, threshold: float) -> list[list[str]]:
     opens a group of its own otherwise. The groups are in the order they
     were opened, each in the order its trials were tried.
     """
-    order = sorted(range(len(names)), key=lambda k: _trial_order(names[k]))
+    order = sorted(range(len(names)), key=lambda k: trial_order(names[k]))
     group_of: dict[int, int] = {}
     groups: list[list[str]] = []
     for position, j in enumerate(order):
@@ -177,7 +182,7 @@ def theme_groups(names: list[str], matrix, threshold: float) -> list[list[str]]:
     return groups
 
 
-def _trial_order(trial: str) -> tuple[int, int]:
+def trial_order(trial: str) -> tuple[int, int]:
     """The round and the slot of a trial id (``trial_id``)."""
     number, slot = _TRIAL_ID.fullmatch(trial).groups()
     return int(number), int(slot)
@@ -217,7 +222,7 @@ def themes(
         first = records[0]
         accepted = [t for t in group if by_id[t].status == "accepted"]
         best_t, best_id = max(
-            ((direction(r.metrics["ic_mean"]) * r.metrics["partial_ic_t"], t) for t, r in zip(group, records)
+            ((directional_t(r.metrics), t) for t, r in zip(group, records)
              if math.isfinite(r.metrics["partial_ic_t"])),
             default=(float("nan"), ""),
         )
@@ -230,7 +235,7 @@ def themes(
             f"({', '.join(group)}), {len(accepted)} accepted{' (' + ', '.join(accepted) + ')' if accepted else ''}"
         )
         if best_id:
-            line += f"; largest residual t in its direction {_num(best_t, 2)} ({best_id})"
+            line += f"; largest residual t in its direction {signed(best_t, 2)} ({best_id})"
         line += f"; last tried in round {max(r.round for r in records)}"
         if refused:
             line += "; refused: " + ", ".join(f"{label} {count}" for label, count in refused.items())
@@ -267,8 +272,11 @@ def last_round(trials: list[tuple[str, TrialRecord]], earlier: list[tuple[str, T
     return "\n".join(blocks)
 
 
-def parent(trial: str, r: TrialRecord, earlier: list[tuple[str, TrialRecord]] = ()) -> str:
-    """The trial a research direction builds on, as its proposer reads it: what it computed, its code, statistics and reasons."""
+def parent(trial: str, r: TrialRecord, earlier: list[tuple[str, TrialRecord]] = (), lineage: "Lineage | None" = None) -> str:
+    """The trial a research direction builds on, as its proposer reads it: what it computed, its code, statistics and reasons.
+
+    With its ``lineage`` the block ends with how the trials built on it did.
+    """
     code = "\n".join("     " + line for line in r.candidate.get("code", "").splitlines())
     lines = [
         f"{trial}, round {r.round}, {r.candidate.get('mechanism_type', '?')}: {r.candidate.get('description', '')}",
@@ -276,7 +284,7 @@ def parent(trial: str, r: TrialRecord, earlier: list[tuple[str, TrialRecord]] =
         f"   outcome: {outcome(r)}",
         "   code:", code,
     ]
-    return "\n".join(lines + _statistics(r, earlier))
+    return "\n".join(lines + _statistics(r, earlier) + ([f"   {lineage.text()}"] if lineage is not None else []))
 
 
 def _statistics(r: TrialRecord, earlier: list[tuple[str, TrialRecord]] = ()) -> list[str]:
@@ -288,17 +296,17 @@ def _statistics(r: TrialRecord, earlier: list[tuple[str, TrialRecord]] = ()) ->
     if r.evaluated:
         m = r.metrics
         nearest = (
-            f"nearest existing factor {m['nearest']}, correlation {_num(m['nearest_correlation'], 2)}"
+            f"nearest existing factor {m['nearest']}, correlation {signed(m['nearest_correlation'], 2)}"
             if m["nearest"] else "no existing factor to compare with"
         )
         if m["nearest_known"]:
             nearest += (
                 f"; nearest known factor {m['nearest_known']}, "
-                f"sampled correlation {_num(m['nearest_known_correlation'], 2)}"
+                f"sampled correlation {signed(m['nearest_known_correlation'], 2)}"
             )
         lines.append(
-            f"   training IC {_num(m['ic_mean'], 4)} (Newey-West t {_num(m['ic_t'], 2)}); "
-            f"residual IC {_num(m['partial_ic_mean'], 4)} (Newey-West t {_num(m['partial_ic_t'], 2)}); {nearest}"
+            f"   training IC {signed(m['ic_mean'], 4)} (Newey-West t {signed(m['ic_t'], 2)}); "
+            f"residual IC {signed(m['partial_ic_mean'], 4)} (Newey-West t {signed(m['partial_ic_t'], 2)}); {nearest}"
         )
         overlap = _overlap(m, {accepted_label(e): t for t, e in earlier if e.status == "accepted"})
         if overlap:
@@ -324,8 +332,13 @@ def accepted(records: list[TrialRecord]) -> str:
     )
 
 
-def best(trials: list[tuple[str, TrialRecord]], contributions: dict[str, Contribution]) -> str:
-    """The accepted factors (of ``named`` trials): id, name, mechanism, code, and marginal weight and residual IC in the accepted pool."""
+def best(
+    trials: list[tuple[str, TrialRecord]], contributions: dict[str, Contribution], lineage: "dict[str, Lineage] | None" = None,
+) -> str:
+    """The accepted factors (of ``named`` trials): id, name, mechanism, code, and marginal weight and residual IC in the accepted pool.
+
+    With ``lineage`` (by trial id, ``_lineage.lineages``) each also carries its Lineage.
+    """
     blocks = []
     for trial, r in trials:
         if r.status != "accepted":
@@ -339,8 +352,10 @@ def best(trials: list[tuple[str, TrialRecord]], contributions: dict[str, Contrib
         ]
         if part is not None:
             lines.append(
-                f"  in the accepted pool: marginal weight {_num(part.weight, 3)}, residual IC {_num(part.residual_ic, 4)}"
+                f"  in the accepted pool: marginal weight {signed(part.weight, 3)}, residual IC {signed(part.residual_ic, 4)}"
             )
+        if lineage and trial in lineage:
+            lines.append(f"  {lineage[trial].text()}")
         blocks.append("\n".join(lines))
     return "\n".join(blocks)
 
@@ -370,7 +385,7 @@ def _overlap(metrics: dict, ids: dict[str, str]) -> str:
     share, overlaps = metrics.get("pool_share"), metrics.get("overlaps") or []
     if share is None or not math.isfinite(share) or not overlaps:
         return ""
-    named = ", ".join(f"{ids.get(name, name)} {_num(correlation, 2)}" for name, correlation in overlaps)
+    named = ", ".join(f"{ids.get(name, name)} {signed(correlation, 2)}" for name, correlation in overlaps)
     return (
         f"   {max(share, 0):.0%} of its daily cross-section is explained by the reference set and the accepted "
         f"factors (the part the residual IC leaves out); most correlated: {named}"
@@ -386,7 +401,7 @@ def _direction(r: TrialRecord, by_id: dict[str, TrialRecord] | None = None) -> s
     earlier = (by_id or {}).get(d["parent"])
     if earlier is None or not earlier.evaluated:
         return f"{text} of {d['parent']}"
-    return f"{text} of {d['parent']} (whose residual t was {_num(earlier.metrics['partial_ic_t'], 2)})"
+    return f"{text} of {d['parent']} (whose residual t was {signed(earlier.metrics['partial_ic_t'], 2)})"
 
 
 def outcome(r: TrialRecord) -> str:
@@ -395,5 +410,6 @@ def outcome(r: TrialRecord) -> str:
 
 
 
-def _num(value: float, digits: int) -> str:
+def signed(value: float, digits: int) -> str:
+    """``value`` with its sign and ``digits`` decimals, or ``n/a`` when it is not a number."""
     return f"{value:+.{digits}f}" if math.isfinite(value) else "n/a"

quantlab_factor_agent-0.2.0/factor_agent/_lineage.py

@@ -0,0 +1,105 @@
+"""Each trial's Lineage: the trials that built on it, and how they did.
+
+A trial's children are the trials whose direction names it as ``parent``
+(direct children only). Its Lineage counts them by action (refinement or
+mutation), those that stopped before evaluation (refused by the parser,
+the Gate or the reviewer, or not compiled) and those accepted, and keeps
+the best evaluated child with its residual t in its direction, beside the
+trial's own. The prompts carry it as one line (``Lineage.text``); the
+fertility is the same counts as one number, for choosing parents.
+
+A child's outcome is 0 when it stopped before evaluation and otherwise the
+amount its residual t in its direction exceeds the admission threshold it
+was judged against (``_admission.t_threshold`` at the evaluated-trial
+count after its round: admission judges every candidate of a round at that
+count, whatever its place in the round), floored at 0. The fertility is the
+mean of the ``fertile_children`` (``context.fertile_children``, 3 by
+default) best outcomes, padded with zeros, so a parent is rewarded for
+children that pass, not for many attempts.
+"""
+
+import math
+from dataclasses import dataclass
+
+from factor_agent._admission import directional_t, t_threshold
+from factor_agent._feedback import signed
+from factor_agent.config import AdmissionConfig
+from factor_agent.ledger import TrialRecord
+
+@dataclass(frozen=True)
+class Lineage:
+    """The trials built on one trial; see the module docstring."""
+
+    attempts: int = 0
+    refinements: int = 0
+    mutations: int = 0
+    #: Children that stopped before evaluation.
+    unevaluated: int = 0
+    #: The accepted children's ids, in the order they were tried.
+    accepted: tuple[str, ...] = ()
+    #: The evaluated child with the largest residual t in its direction, "" when none was evaluated.
+    best_child: str = ""
+    best_child_t: float = float("nan")
+    #: The trial's own residual t in its direction, NaN when it was not evaluated.
+    own_t: float = float("nan")
+    fertility: float = 0.0
+
+    def text(self) -> str:
+        """The line the planner's accepted factors and the proposer's parent block carry."""
+        if not self.attempts:
+            return "lineage: no trial has built on it yet"
+        line = (
+            f"lineage: {_count(self.attempts, 'trial')} built on it ({_count(self.refinements, 'refinement')}, "
+            f"{_count(self.mutations, 'mutation')}), {self.unevaluated} stopped before evaluation, "
+            + (f"{len(self.accepted)} accepted ({', '.join(self.accepted)})" if self.accepted else "none accepted")
+        )
+        if not self.best_child:
+            return line + "; no child was evaluated"
+        return (
+            f"{line}; best evaluated child {self.best_child}, residual t in its direction {signed(self.best_child_t, 2)} "
+            f"against this trial's {signed(self.own_t, 2)}"
+        )
+
+
+def lineages(
+    trials: list[tuple[str, TrialRecord]], admission: AdmissionConfig, fertile_children: int,
+) -> dict[str, Lineage]:
+    """The Lineage of every trial of ``trials`` (``_feedback.named``, in the ledger's order), by id.
+
+    ``fertile_children`` is the count of best child outcomes the fertility is the mean of.
+    """
+    evaluated_through: dict[int, int] = {}
+    for _, r in trials:
+        evaluated_through[r.round] = evaluated_through.get(r.round, 0) + r.evaluated
+    count = 0
+    for number in sorted(evaluated_through):
+        count += evaluated_through[number]
+        evaluated_through[number] = count
+    children: dict[str, list[tuple[str, TrialRecord]]] = {}
+    for trial, r in trials:
+        parent = (r.direction or {}).get("parent")
+        if parent:
+            children.setdefault(parent, []).append((trial, r))
+    result = {}
+    for trial, r in trials:
+        built = children.get(trial, [])
+        actions = [(c.direction or {}).get("action") for _, c in built]
+        scored = [(child, directional_t(c.metrics), c) for child, c in built if c.evaluated]
+        best = max(((t, child) for child, t, _ in scored if math.isfinite(t)), default=(float("nan"), ""))
+        outcomes = sorted(
+            (max(t - t_threshold(admission, evaluated_through[c.round]), 0.0) if math.isfinite(t) else 0.0
+             for _, t, c in scored),
+            reverse=True,
+        )
+        result[trial] = Lineage(
+            attempts=len(built), refinements=actions.count("refinement"), mutations=actions.count("mutation"),
+            unevaluated=len(built) - len(scored), accepted=tuple(child for child, c in built if c.status == "accepted"),
+            best_child=best[1], best_child_t=best[0], own_t=directional_t(r.metrics) if r.evaluated else float("nan"),
+            fertility=sum(outcomes[:fertile_children]) / fertile_children,
+        )
+    return result
+
+
+def _count(n: int, noun: str) -> str:
+    """``n`` of ``noun``, the noun in the plural unless ``n`` is 1."""
+    return f"{n} {noun}" + ("" if n == 1 else "s")