loopmath 0.2.0__tar.gz → 0.2.1__tar.gz

{loopmath-0.2.0 → loopmath-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopmath
-Version: 0.2.0
+Version: 0.2.1
 Summary: Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs
 Author: QKV Labs
 License-Expression: MIT

{loopmath-0.2.0 → loopmath-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.2.0"
+version = "0.2.1"
 description = "Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs"
 readme = "README.md"
 license = "MIT"

{loopmath-0.2.0 → loopmath-0.2.1}/src/loopmath/__init__.py

@@ -5,4 +5,4 @@ The command line (`loopmath`, or its alias `loop`) is the interface; see the
 README and `loopmath --help`.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{loopmath-0.2.0 → loopmath-0.2.1}/src/loopmath/belief/design.py

@@ -35,6 +35,11 @@ HEURISTIC_COST_WEIGHT = 0.7  # spec 04 section 2 and D27: allocated (heuristic)
 USER_SOURCES = ("live", "backlog", "history", "user", "orchestrator", "onboard", "habit", "")
 HORIZON_NODES = ("horizon:timebox", "horizon:log2h")  # fixed terms of a timeboxed run (spec 04 section 1)
 RQ1_EXT = "dev.loopmath.rq1"  # loopmath-exp's ext key; its horizon_s is the fallback for older RQ1 runs
+# 0.2.1 (F5, spec 04 section 1): in the cost and tokens rows of a timeboxed task the terms a timebox caps (effort
+# and shape) enter at this value, not 1. Set from the RQ1 2 h runs: open-ended effort terms gave max over low x2.64
+# (solo luna) and x2.23 (solo sol) against x1.34 and x1.27 observed; ln 1.34 / ln 2.64 = ln 1.27 / ln 2.23 = 0.30.
+TIMEBOX_EFFORT_COST = 0.3
+TIMEBOX_LEVELS = ("effort:", "family_effort:", "topology:", "position:")
 
 
 def other_design(meta: dict) -> str | None:
@@ -304,17 +309,36 @@ def structure(config: Configuration) -> Structure:
 
 # ---------------------------------------------------------------- rows
 
+def effort_weight(task: Task, timebox_effort: float | None = None) -> float:
+    """The value of the timebox-capped terms (TIMEBOX_LEVELS) in a cost or tokens row of `task`: `timebox_effort`
+    (default TIMEBOX_EFFORT_COST) when the task has a horizon, else 1 (spec 04 section 1, effort and shape under
+    a timebox)."""
+    if task_horizon(task) is None:
+        return 1.0
+    return float(TIMEBOX_EFFORT_COST if timebox_effort is None else timebox_effort)
+
+
+@lru_cache(maxsize=65536)
+def _effort_scaled(terms: tuple[Term, ...], weight: float) -> tuple[Term, ...]:
+    return tuple((n, p, v * weight) if n.startswith(TIMEBOX_LEVELS) else (n, p, v) for n, p, v in terms)
+
+
 def cost_rest(st: Structure, piece: str, k: int, setting: Setting | None = None, *,
-              source: str | None = None) -> tuple[Term, ...]:
+              source: str | None = None, effort: float = 1.0) -> tuple[Term, ...]:
     """Cost and tokens rows without the task part: setting, role, topology, position, round, control,
     and with a `source` the position x source node `psrc:<shape>#<pos>|<source>` and the family x source
-    node `fsrc:<family>|<source>` (spec 04 section 1)."""
+    node `fsrc:<family>|<source>` (spec 04 section 1). `effort` is the value of the terms a timebox caps, the
+    effort and shape (topology, position) terms (`effort_weight`: below 1 under a timebox); the role, psrc and
+    fsrc terms stay at 1."""
     s = setting or st.settings[piece]
     h, m, e = _s(s)
     shape = st.shape or st.workflow_id
     position = f"{shape}#{st.pieces.index(piece)}"
-    terms = (setting_terms(h, m, e) + role_terms(st.roles[piece], m)
-             + ((f"topology:{shape}", None, 1.0), (f"position:{position}", f"topology:{shape}", 1.0)))
+    st_terms = setting_terms(h, m, e)
+    shape_terms = ((f"topology:{shape}", None, 1.0), (f"position:{position}", f"topology:{shape}", 1.0))
+    if effort != 1.0:
+        st_terms, shape_terms = _effort_scaled(st_terms, float(effort)), _effort_scaled(shape_terms, float(effort))
+    terms = st_terms + role_terms(st.roles[piece], m) + shape_terms
     if source is not None:
         fam = model_path(m)[1]
         terms += ((f"psrc:{position}|{source}", f"position:{position}", 1.0),
@@ -345,7 +369,8 @@ def run_rest(st: Structure) -> tuple[Term, ...]:
 
 def cost_row(task: Task, source: str, st: Structure, piece: str, k: int,
              setting: Setting | None = None, features: FeatureSet | None = None) -> list[Term]:
-    return task_terms(task, source, features) + list(cost_rest(st, piece, k, setting, source=source))
+    return task_terms(task, source, features) + list(cost_rest(st, piece, k, setting, source=source,
+                                                               effort=effort_weight(task)))
 
 
 def gate_row(task: Task, source: str, st: Structure, gate: GateInfo, k: int,

{loopmath-0.2.0 → loopmath-0.2.1}/src/loopmath/belief/fit.py

@@ -29,6 +29,7 @@ import numpy as np
 from scipy import sparse
 
 from ..taskmodel import FeatureConfigError, FeatureSet
+from . import design as design_rows
 from . import priors as prior_data
 from .design import (DESIGN_VERSION, Term, Unusable, cost_row, gate_row, parse_run, run_row, structure,
                      task_features, task_terms)
@@ -362,9 +363,27 @@ def _support(hr: HeadRows, X: sparse.csr_matrix, node_ids: list[str]) -> dict[st
 
 
 def seed_for(fit_id: str, head: str) -> int:
+    """A head's seed from the fit's `seed_key` (its fit id before 0.2.1)."""
     return int.from_bytes(hashlib.sha256(f"{fit_id}/{head}".encode()).digest()[:4], "little")
 
 
+def input_key(heads_rows: dict[str, HeadRows], specs: list, settings: dict) -> str:
+    """The fit's `seed_key` (spec 04 section 3): the sha256 of the design version, the settings that change the
+    posterior, the prior factors and every head's rows (terms, response, weight, run, source), each head's rows
+    sorted, so the same data and settings seed the same draws whatever the store's reading order."""
+    h = hashlib.sha256()
+    h.update(repr((DESIGN_VERSION, design_rows.TIMEBOX_EFFORT_COST, design_rows.TIMEBOX_LEVELS,
+                   sorted(settings.items()))).encode())
+    for spec in specs:
+        h.update(repr((spec.head, spec.terms, spec.mean, spec.var)).encode())
+    for name in sorted(heads_rows):
+        hr = heads_rows[name]
+        h.update(f"\n{name}:{len(hr.rows)}".encode())
+        for line in sorted(repr((t, y, w, r, src)) for t, y, w, r, src in zip(hr.rows, hr.y, hr.w, hr.runs, hr.sources)):
+            h.update(line.encode())
+    return h.hexdigest()
+
+
 def fit_head(hr: HeadRows, forest: Forest, factor_specs: list, *, eb: bool = True) -> dict:
     """Fit one head; returns arrays and metadata for the state files."""
     extra = [(n, p) for spec in factor_specs for n, p, _ in spec.terms]
@@ -502,6 +521,8 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
         specs = []
         if not no_prior and "benchmark" not in without:
             specs = prior_data.benchmark_factors(benchmarks, weight=weight)
+        seed_key = input_key(heads_rows, specs, {"no_prior": no_prior, "without": sorted(without), "eb": eb,
+                                                  "benchmark_prior_weight": weight})
         forest = Forest()
         fitted = {}
         for name, hr in heads_rows.items():
@@ -546,6 +567,8 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
         _atomic_json(partial / "design.json", design)
         meta = {
             "fit": fit_id, "created_at": now.isoformat(timespec="seconds"), "code_version": _code_version(),
+            "seed_key": seed_key, "timebox_effort": design_rows.TIMEBOX_EFFORT_COST,
+            "timebox_terms": list(design_rows.TIMEBOX_LEVELS),
             "options": {"no_prior": no_prior, "without": list(without), "full": full, "eb": eb,
                         "benchmark_prior_weight": weight},
             "runs_by_source": runs_by_source,
@@ -562,7 +585,7 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
                              "center": h["center"], "scale": h["scale"], "baseline": h["baseline"],
                              "iterations": h["fit"].iterations, "optimizer": h["fit"].info,
                              "log_evidence": _finite(h["fit"].log_evidence), "factors": h["factors"],
-                             "seed": seed_for(fit_id, name)}
+                             "seed": seed_for(seed_key, name)}
                       for name, h in fitted.items()},
             "scores": score_info,
             "draws": N_DRAWS,

{loopmath-0.2.0 → loopmath-0.2.1}/src/loopmath/belief/lookahead.py

@@ -165,7 +165,7 @@ def _prepare(state: FitState, task: Task, configs: list[Configuration], rule: Ac
     tt = state.task_terms(task)
     cost_rows, coef, owner_r, owner_c, run_rows, plans = [], [], [], [], [], []
     for ci, (cfg, (_, d)) in enumerate(zip(configs, out)):
-        plan = state._plan(cfg)
+        plan = state._plan(cfg, state.effort_for(task))
         plans.append(plan)
         st = plan["st"]
         reach = d["reach"]  # E[r(k)] with the unseen task effect on the gates integrated out
@@ -193,7 +193,7 @@ def _prepare(state: FitState, task: Task, configs: list[Configuration], rule: Ac
 def _explore_cost_obs(state: FitState, task: Task, config: Configuration) -> tuple[list[tuple], int]:
     """Composite observation: the mean of the round-1 cost rows of the configuration's pieces,
     and the number of pieces (the observation's noise variance is sigma^2 / n)."""
-    plan = state._plan(config)
+    plan = state._plan(config, state.effort_for(task))
     st = plan["st"]
     tt = state.task_terms(task)
     acc: dict[str, list] = {}
@@ -385,7 +385,7 @@ def _condition_head(head: HeadState, terms: Sequence[tuple], tau2: float) -> Hea
     draws = mean[:, None] + U @ Z
     meta = dict(head.meta) or {"engine": head.engine, "kind": head.kind, "sigma": head.sigma}
     out = HeadState(head.name, meta, head.nodes + new_nodes, None, head.fit_id, mean=mean, U=U, draws=draws,
-                    unit=Z)
+                    unit=Z, seed_key=head.seed_key)
     out.fitted = head.fitted
     out.phi = dict(head.phi)
     return out

{loopmath-0.2.0 → loopmath-0.2.1}/src/loopmath/belief/state.py

@@ -152,7 +152,7 @@ class HeadState:
     `loader(part)` returns a stored array or None when the fit did not store it."""
 
     def __init__(self, name: str, meta: dict, nodes: Sequence[str], loader: Callable[[str], np.ndarray] | None,
-                 fit_id: str, *, mean=None, U=None, draws=None, unit=None):
+                 fit_id: str, *, mean=None, U=None, draws=None, unit=None, seed_key: str | None = None):
         base = BASE_HEADS.get(name, ("gaussian", "score"))
         self.name = name
         self.engine = meta.get("engine") or base[0]
@@ -165,6 +165,7 @@ class HeadState:
         self.seed = int(meta.get("seed", 0))
         self.meta = meta
         self.fit_id = fit_id
+        self.seed_key = seed_key or fit_id  # spec 04 section 3: the fit's input hash; the fit id before 0.2.1
         self.nodes = list(nodes)
         self.index = {n: j for j, n in enumerate(self.nodes)}
         self._loader = loader
@@ -252,7 +253,7 @@ class HeadState:
         """Standard normal draws of an unseen node, fixed by the fit, the head and the node id."""
         z = self._virtual.get(node)
         if z is None:
-            z = np.random.default_rng(_seed(self.fit_id, self.name, node)).standard_normal(N_DRAWS)
+            z = np.random.default_rng(_seed(self.seed_key, self.name, node)).standard_normal(N_DRAWS)
             self._virtual[node] = z
         return z
 
@@ -332,16 +333,21 @@ class FitState:
         self._design = design
         self._npz = None
         self._cache: dict = {}
-        self.sim_seed = _seed(self.fit_id, "simulate")
+        # spec 04 section 3: every draw is seeded from the fit's input hash, so identical fits give identical
+        # output; fits before 0.2.1 have no `seed_key` and keep their fit id
+        self.seed_key: str = self.meta.get("seed_key") or self.fit_id
+        self.sim_seed = _seed(self.seed_key, "simulate")
+        # spec 04 section 1: the value of the timebox-capped terms (effort, shape) in a timeboxed task's cost rows
+        self.timebox_effort = float(self.meta.get("timebox_effort", 1.0))
         if heads is None:
             heads = {}
             for name, hmeta in (self.meta.get("heads") or {}).items():
                 key = name.replace(":", "@")
                 ids = [str(x) for x in self._array(f"{key}__ids")]
-                heads[name] = HeadState(name, hmeta, ids, self._loader(key), self.fit_id)
+                heads[name] = HeadState(name, hmeta, ids, self._loader(key), self.fit_id, seed_key=self.seed_key)
         for name in BASE_HEADS:
             if name not in heads:
-                heads[name] = HeadState(name, {}, [], None, self.fit_id)
+                heads[name] = HeadState(name, {}, [], None, self.fit_id, seed_key=self.seed_key)
         self.heads = heads
         # the fit's feature declarations (the built-ins for fits before 0.2), so predictions read
         # features the way the fit did
@@ -397,13 +403,22 @@ class FitState:
     def _row(self, head: HeadState, rest: tuple) -> Row:
         return self._cached(head, [rest])[0]
 
-    def _plan(self, config: Configuration) -> dict:
+    def effort_for(self, task: Task) -> float:
+        """The value of the timebox-capped terms (effort and shape, `design.TIMEBOX_LEVELS`) in the task's cost
+        rows: the fit's `timebox_effort` when the task's resolved horizon (given, else recorded) is a timebox the
+        fit uses (it has timeboxed runs), else 1 (spec 04 section 1)."""
+        if self.timebox_effort == 1.0:
+            return 1.0
+        return self.timebox_effort if self.resolve_task(task)[1]["horizon"]["used"] else 1.0
+
+    def _plan(self, config: Configuration, effort: float = 1.0) -> dict:
+        """The configuration's rows without the task part; `effort` from `effort_for(task)`."""
         st = structure(config)
         cost = {}
         for piece in st.pieces:
             rounds = st.k_max if st.piece_loop.get(piece) is not None else 1
             for k in range(1, rounds + 1):
-                cost[(piece, k)] = cost_rest(st, piece, k, source=PREDICT_SOURCE)
+                cost[(piece, k)] = cost_rest(st, piece, k, source=PREDICT_SOURCE, effort=effort)
         gate = {}
         for gi, g in enumerate(st.gates):
             for k in range(1, (st.k_max if st.gate_loop.get(gi) is not None else 1) + 1):
@@ -790,7 +805,8 @@ class FitState:
 
     def _predict_many(self, task: Task, configs: Sequence[Configuration], rule: AcceptanceRule | None,
                       rescue_usd: float | None) -> list[tuple[Prediction, dict]]:
-        plans = [self._plan(c) for c in configs]
+        effort = self.effort_for(task)
+        plans = [self._plan(c, effort) for c in configs]
         tparts = self._task_parts(task)
         self._warm(plans)
         return [self._predict(task, p, tparts, rule, rescue_usd) for p in plans]

loopmath-0.2.1/src/loopmath/builder/__init__.py

@@ -0,0 +1 @@
+"""`loopmath builder`: the workflow builder (P8), a local page over the fitted model (spec 02, `builder`)."""

loopmath-0.2.1/src/loopmath/builder/cli.py

@@ -0,0 +1,34 @@
+"""The `loopmath builder` parser, added by `cli_registry.register` (spec 02, `builder`).
+
+It takes the task and rule flags of `recommend`, from the registry's own helpers, and imports nothing
+heavy: the handler is `builder.server:serve`, loaded only when the command runs.
+"""
+
+from __future__ import annotations
+
+
+def add(sub) -> None:
+    from ..cli_registry import FIT_HELP, _common, _lazy, _task_args
+
+    p = sub.add_parser("builder", help="build your own workflow on a local page and see its estimates change",
+                       description="Serves the workflow builder on 127.0.0.1: pick a shape, change models, efforts, "
+                                   "widths and pieces, and see the estimated numbers for the task, the same ones "
+                                   "recommend gives. Ctrl+C stops it.")
+    _task_args(p)
+    rule = p.add_mutually_exclusive_group()
+    rule.add_argument("--rule", default=None, metavar="RULE", help="a named acceptance rule from config")
+    rule.add_argument("--target", default=None, metavar="NAME>=X", help="score-target rule, quoted: e.g. 'heldout_perf>=2400'")
+    p.add_argument("--goal", default=None, choices=["default", "p50", "p70", "p80", "p90", "p95", "p99"],
+                   help="the pick to aim for, as for recommend (default: config goal)")
+    p.add_argument("--usual", default=None, metavar="CFG", help="a configuration id to treat as the usual one, as for recommend")
+    p.add_argument("--workflow", action="append", default=[], metavar="FILE.toml", help="also consider this workflow (repeatable)")
+    p.add_argument("--models", default=None, metavar="M,M,...", help="restrict candidate models")
+    p.add_argument("--fit", default=None, metavar="ID", help=FIT_HELP)
+    p.add_argument("--rec", default=None, metavar="REC", help="start from a saved recommendation: its task, rule and fit "
+                   "(task flags given as well override its task)")
+    p.add_argument("--start", default=None, metavar="CFG", help="open this configuration first: a cfg_ id from the "
+                   "recommendation, an earlier one or your runs")
+    p.add_argument("--port", type=int, default=0, metavar="N", help="port on 127.0.0.1 (default 0: a free port)")
+    p.add_argument("--no-open", action="store_true", help="print the URL without opening the browser")
+    _common(p, json_flag=False)
+    p.set_defaults(func=_lazy("loopmath.builder.server:serve"))

loopmath-0.2.1/src/loopmath/builder/context.py

@@ -0,0 +1,240 @@
+"""The builder's session: the fit and the recommendation it answers from, and `GET /api/context`.
+
+At start `build_session` reads the task and rule as `recommend` does, loads the fit once and runs the
+recommend engine once, with the same helpers in the same order as `recommend.commands.recommend`, so every
+number the page shows is the one `recommend` gives. The session keeps the belief, the task as the belief
+sees it, the rule and the recommendation in memory; `predict.py` answers edited configurations from them.
+Nothing is written to the store.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import re
+import sys
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..output import EXIT_NOT_FOUND, EXIT_OK, fail, home as home_dir
+from ..recommend import commands as C
+from ..recommend import engine, storeread
+from ..recommend.engine import Recommendation
+from ..recommend.storeread import Conf
+from ..types import AcceptanceRule, Configuration, Task
+
+SCHEMA = "loopmath.builder.context/1"
+TOP_CANDIDATES = 60  # the page's candidates: the first 60 by cost per accepted result, plus recorded ones
+KEEP_ORIGINS = ("usual", "user", "recorded")
+MADE_UP_TASK_ID = re.compile(r"^tsk_[0-9A-HJKMNP-TV-Z]{26}$")  # `storeread.ulid()`: an id no user gave
+TASK_KEYS = ("type", "repo", "title", "subtype", "org", "features", "base_commit")
+
+
+@dataclass
+class Session:
+    belief: Any
+    task: Task  # the task as the belief sees it (recommend's `asked`); predictions use this one
+    rule: AcceptanceRule
+    rec: Recommendation  # `rec.task` is the task as shown
+    fit: dict[str, Any]
+    rec_id: str | None = None  # `--rec`
+    start: Configuration | None = None  # `--start`
+    lock: threading.Lock = field(default_factory=threading.Lock)  # the belief caches rows; one predict at a time
+    cache: OrderedDict = field(default_factory=OrderedDict)  # config id -> predict answer
+    context: dict[str, Any] | None = None
+    models: dict[str, int] | None = None  # `known_models`, read once
+
+
+# ---------------------------------------------------------------- start
+def rec_task(stored: dict[str, Any], args: argparse.Namespace) -> tuple[Task, bool]:
+    """A stored recommendation's task, with the task flags given on top. Its id counts as the user's only
+    when it is not one `recommend` made up, so the belief sees the same question."""
+    t = stored.get("task") if isinstance(stored.get("task"), dict) else {}
+    d = {k: t[k] for k in TASK_KEYS if t.get(k) is not None}
+    tid = str(t.get("id") or "")
+    given = bool(tid) and not MADE_UP_TASK_ID.match(tid)
+    if given:
+        d["id"] = tid
+    return C.task_from_dict(d, overrides=args), given
+
+
+def asked_task(task: Task, id_given: bool, belief: Any, rule: AcceptanceRule, configs: list) -> Task:
+    """The task as `recommend` asks the belief: the user's when they named it, else `commands.question_task`
+    keyed as `recommend` keys it, by `commands.question_key(belief)` once `recommend` has it (0.2.1 lane
+    21F: the fit's input seed key, so identical fits agree), else by the fit id as in 0.2.0."""
+    if id_given:
+        return task
+    key_of = getattr(C, "question_key", None)
+    return C.question_task(task, key_of(belief) if callable(key_of) else belief.fit_id, rule, configs)
+
+
+def build_session(args: argparse.Namespace) -> tuple[Session | None, int]:
+    """The session, or None and the exit code after the message `recommend` would print."""
+    home = home_dir(getattr(args, "home", None))
+    now = storeread.now_local()
+    stored = None
+    try:
+        if getattr(args, "rec", None):
+            stored = storeread.load_rec(home, args.rec)
+            if stored is None:
+                raise C.NotFound(f"recommendation {args.rec} not found in {home / 'recs'}")
+            task, id_given = rec_task(stored, args)
+            ref = stored.get("reference") or {}
+            if not getattr(args, "usual", None) and ref.get("from") == "flag":
+                args.usual = (ref.get("config") or {}).get("id")
+            goal = (stored.get("goal") or {}).get("choice")
+            if not getattr(args, "goal", None) and isinstance(goal, str) and goal.startswith("p"):
+                args.goal = goal
+        else:
+            task, id_given = C.task_from_args(args)
+        conf = Conf.load(home)
+        if stored is not None and not (getattr(args, "rule", None) or getattr(args, "target", None)) \
+                and isinstance(stored.get("rule"), dict):
+            rule = AcceptanceRule.from_dict(stored["rule"])
+        else:
+            rule = C.rule_from_args(args, conf)
+        spend, cap = C.budget(home, conf)
+        settings = C.settings_from(conf, args, spend, cap)
+        models = C.model_list(getattr(args, "models", None))
+    except C.NotFound as exc:
+        return None, fail(str(exc), EXIT_NOT_FOUND)
+    except ValueError as exc:
+        return None, fail(str(exc))
+    fit_id = getattr(args, "fit", None)
+    if stored is not None and not fit_id:  # the recommendation's own fit while it is kept, else the latest
+        fit_id = (stored.get("fit") or {}).get("id")
+        if fit_id and not (home / "fits" / str(fit_id)).is_dir():
+            print(f"warning: {args.rec} was made with fit {fit_id}, which is no longer kept; using the latest fit",
+                  file=sys.stderr)
+            fit_id = None
+    belief, code = C.load_belief(home, fit_id)
+    if belief is None:
+        return None, code
+    try:  # `recommend.commands.recommend`, step for step
+        usual, usual_from = C.resolve_usual(home, conf, task, getattr(args, "usual", None), models)
+        recorded = [c for c, _ in storeread.recorded_configs(home, task.type, task.repo)[0]]
+        if usual_from == "default" and recorded:
+            asked = asked_task(task, id_given, belief, rule, recorded)
+            best = C.reference_for(belief, asked, rule, recorded, models)
+            if best is not None:
+                usual, usual_from = best, "recorded"
+        user = [C.workflow_file_config(p, usual) for p in getattr(args, "workflow", None) or []]
+        configs = C.candidate_configs(task, usual, conf, models, user + C.store_user_configs(home, usual), recorded)
+        asked = asked_task(task, id_given, belief, rule, [usual, *(c for c, _ in configs)])
+        rec = engine.recommend(belief, asked, rule, usual=usual, usual_from=usual_from, configs=configs,
+                               settings=settings, diff=C.diff_fn(), keep=[*(u.id for u in user),
+                                                                        *(r.id for r in recorded)])
+        rec.task = task
+        start = None
+        if getattr(args, "start", None):
+            found = rec.by_id(args.start)
+            start = found.config if found is not None else storeread.find_config(home, args.start)
+            if start is None:
+                raise C.NotFound(f"configuration {args.start} not found in this recommendation, earlier "
+                                 f"recommendations or stored runs")
+    except C.NotFound as exc:
+        return None, fail(str(exc), EXIT_NOT_FOUND)
+    except ValueError as exc:
+        return None, fail(str(exc))
+    fit = {**C.fit_info(belief, now), "runs": int(getattr(belief, "n_runs", 0) or 0)}
+    return Session(belief, asked, rule, rec, fit, rec_id=getattr(args, "rec", None), start=start), EXIT_OK
+
+
+# ---------------------------------------------------------------- catalog
+def fit_models(belief: Any) -> dict[str, int]:
+    """Models the fit has a node for, with the most runs any head has behind that node."""
+    design = getattr(belief, "design", None)
+    support = (design.get("support") if isinstance(design, dict) else None) or {}
+    out: dict[str, int] = {}
+    for head in support.values():
+        for node, val in (head or {}).items():
+            if isinstance(node, str) and node.startswith("model:"):
+                n = int(val[0]) if isinstance(val, (list, tuple)) and val else 0
+                out[node[len("model:"):]] = max(out.get(node[len("model:"):], 0), n)
+    return out
+
+
+def rec_configs(rec: Recommendation) -> list[Configuration]:
+    return [rec.usual.config, *(c.config for c in rec.candidates)]
+
+
+def known_models(session: Session) -> dict[str, int]:
+    """Model id -> runs behind it: the fit's models and any a candidate uses (0 runs when the fit has no node)."""
+    if session.models is None:
+        out = fit_models(session.belief)
+        for cfg in rec_configs(session.rec):
+            for s in cfg.settings.values():
+                out.setdefault(s.model, 0)
+        session.models = out
+    return session.models
+
+
+def catalog(session: Session) -> dict[str, Any]:
+    from ..workflows.format import KNOWN_ROLES, catalog as shapes
+    from ..workflows.models import DEFAULT_EFFORTS, efforts_for, family_of, harness_for, sort_efforts
+
+    seen = [s for cfg in rec_configs(session.rec) for s in cfg.settings.values()]
+    harnesses = list(dict.fromkeys([*DEFAULT_EFFORTS, *(s.harness for s in seen)]))
+    models = sorted(known_models(session).items(), key=lambda kv: (-kv[1], kv[0]))
+    by_harness = {h: list(efforts_for(h)) for h in harnesses}
+    efforts = sort_efforts([e for v in by_harness.values() for e in v] + [s.effort for s in seen])
+    return {
+        "harnesses": harnesses,
+        "models": [{"id": m, "family": family_of(m), "harness": harness_for(m), "runs_behind": n}
+                   for m, n in models],
+        "efforts": list(efforts),
+        "efforts_by_harness": by_harness,
+        "roles": list(KNOWN_ROLES),
+        "shapes": [{"id": wf.id, "title": wf.title,
+                    "pieces": [{"id": p.id, "role": p.role, "width": p.width} for p in wf.pieces],
+                    "edges": [list(e) for e in wf.edges],
+                    "gates": [g.to_dict() for g in wf.control.gates],
+                    "workflow": wf.to_dict()} for wf in shapes().values()],
+    }
+
+
+# ---------------------------------------------------------------- the context
+def candidate_entry(rec: Recommendation, c: Any) -> dict[str, Any]:
+    return {"config": c.config.to_dict(), "label": rec.label(c.config), "numbers": rec.numbers(c.prediction),
+            "origin": c.origin, **rec.search_fields(c.config.id)}
+
+
+def context_payload(session: Session) -> dict[str, Any]:
+    """`GET /api/context` (spec 02, `builder`), built once per session."""
+    if session.context is not None:
+        return session.context
+    rec = session.rec
+    core = rec.payload()
+    choices = []
+    for ch in core["choices"]:
+        c = rec.by_id(ch["config"])
+        choices.append({**ch, "configuration": c.config.to_dict() if c is not None else None})
+    reference = {k: v for k, v in core["reference"].items() if k != "prediction"}
+    top = rec.candidates[:TOP_CANDIDATES]
+    ids = {c.config.id for c in top}
+    wanted = {rec.usual.config.id, *(ch["config"] for ch in core["choices"])}
+    top += [c for c in rec.candidates[TOP_CANDIDATES:]
+            if c.config.id not in ids and (c.origin in KEEP_ORIGINS or c.config.id in wanted)]
+    session.context = {
+        "schema": SCHEMA,
+        "task": C.task_block(rec.task, session.belief),
+        "rule": core["rule"],
+        "fit": session.fit,
+        "rec": session.rec_id,
+        "rescue": core["rescue"],
+        "reference": reference,
+        "choices": choices,
+        "candidates": [candidate_entry(rec, c) for c in top],
+        "catalog": catalog(session),
+        "start": session.start.to_dict() if session.start is not None else None,
+    }
+    return session.context
+
+
+def with_numbers(rec: Recommendation, **by_id: dict[str, Any]) -> Recommendation:
+    """The recommendation with more medians (and bands) by config id, so `numbers()` formats a new prediction
+    exactly as it formats a candidate's."""
+    changes = {k: {**getattr(rec, k), **v} for k, v in by_id.items() if v and hasattr(rec, k)}
+    return dataclasses.replace(rec, **changes) if changes else rec