loopmath 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopmath
-Version: 0.2.0
+Version: 0.2.2
 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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.2.0"
+version = "0.2.2"
 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.2}/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.2"

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

@@ -13,7 +13,7 @@ A term is `(node_id, parent_id, value)`. Rows:
 from __future__ import annotations
 
 import math
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from datetime import datetime
 from functools import lru_cache
@@ -25,6 +25,7 @@ from ..types import (
     Workflow,
 )
 from .forest import canonical_model_id, canonical_role, model_path
+from .pricing import price_term
 
 Term = tuple[str, "str | None", float]
 
@@ -35,6 +36,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,22 +310,45 @@ 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,
+              prices: Mapping[str, float] | None = None) -> 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. `prices` is a fit's price offsets (`FitState.price_offsets`, spec 04 section 2): the
+    model's `price:offset` term goes last. The cost head has that node and the tokens head does not, so a
+    prediction's shared row prices only its cost."""
     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),
                   (f"fsrc:{fam}|{source}", f"family:{fam}", 1.0))
-    return terms + tuple(round_terms(k)) + tuple(_control_terms(st.k_max, st.widths[piece]))
+    return (terms + tuple(round_terms(k)) + tuple(_control_terms(st.k_max, st.widths[piece]))
+            + price_term(prices, m))
 
 
 def gate_rest(st: Structure, gate: GateInfo, k: int) -> tuple[Term, ...]:
@@ -345,7 +374,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,
@@ -396,6 +426,7 @@ class AttemptObs:
     weight: float
     setting: Setting
     repriced: bool = True  # False: the recorded dollars, not the current tariff
+    streams: tuple[float, ...] = ()  # input, cache read, cache write, output tokens (pricing.STREAMS order)
 
 
 @dataclass
@@ -433,8 +464,10 @@ def source_label(doc: dict) -> str:
     ext = run.get("ext") or {}
     share = ext.get("dev.loopmath.share")
     if isinstance(share, dict):
-        org = share.get("org") or share.get("org_hash") or (run.get("task") or {}).get("org") or "shared"
-        return f"shared:{org}"
+        # the importer writes `source` and `task.org` as `shared:<org_hash>` already: never prefix twice
+        org = (share.get("source") or share.get("org") or share.get("org_hash") or (run.get("task") or {}).get("org")
+               or "shared")
+        return "shared:" + str(org).removeprefix("shared:")
     src = (run.get("task") or {}).get("source")
     kind = src.get("kind") if isinstance(src, dict) else src
     kind = str(kind or "").strip().lower()
@@ -736,7 +769,9 @@ def parse_run(doc: dict, *, now: datetime | None = None, rule: AcceptanceRule |
         if weight <= 0 or ((usd is None or usd <= 0) and not tokens):
             dropped["attempt without usable cost"] = dropped.get("attempt without usable cost", 0) + 1
             continue
-        attempts.append(AttemptObs(piece, k, usd if usd and usd > 0 else None, tokens, weight, setting, repriced))
+        streams = tuple(_ocp_fields(cost)[name] for name in _OCP_TOKEN_FIELDS)
+        attempts.append(AttemptObs(piece, k, usd if usd and usd > 0 else None, tokens, weight, setting, repriced,
+                                   streams))
 
     gates = _gate_observations(doc, st, by_piece_round)
     use_rule = rule or rule_from_doc(doc)

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

@@ -29,12 +29,14 @@ 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)
 from .features import FeatureTally, add_horizon, drop_features, horizon_nodes, horizon_specs
 from .block import leaf_split
 from .forest import Forest, default_scale, fixed_sd, scale_group
+from .pricing import PRICE_NODE, PRICE_PRIOR_SD, STREAMS, fit_offsets, price_term
 from .gaussian import N_DRAWS, Factors, GaussianHead, HeadFit, LogisticHead, Prior
 from .state import SCORE_CLAMP, inverse_transform, transform  # noqa: F401  (re-exported)
 
@@ -162,6 +164,7 @@ class HeadRows:
     sources: list[str] = field(default_factory=list)
     types: list[str] = field(default_factory=list)
     not_repriced: int = 0  # cost rows on recorded dollars, not the current tariff
+    prices: dict = field(default_factory=dict)  # cost head: the fit's price offsets (pricing.fit_offsets)
 
     def add(self, terms, y, w, run, source, ttype):
         self.rows.append(terms)
@@ -212,6 +215,8 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
     stored: set[str] = set()  # run ids of the user's store, whose copy wins
     overlap: Counter = Counter()
     labels: Counter = Counter()
+    model_runs: dict[str, set[str]] = defaultdict(set)  # the price offset's inputs (spec 04 section 2)
+    model_streams: dict[str, list[float]] = defaultdict(lambda: [0.0] * len(STREAMS))
     for item in docs:
         origin, doc = item if isinstance(item, tuple) else (None, item)
         if origin is not None and _excluded(origin, without):
@@ -257,6 +262,10 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
             if a.usd:
                 heads["cost"].add(terms, math.log(a.usd), a.weight, pr.run_id, pr.source, ttype)
                 heads["cost"].not_repriced += not a.repriced
+                model_runs[a.setting.model].add(pr.run_id)
+                acc = model_streams[a.setting.model]
+                for i, v in enumerate(a.streams):
+                    acc[i] += v
             if a.tokens:
                 heads["tokens"].add(terms, math.log(a.tokens), a.weight, pr.run_id, pr.source, ttype)
         for gi, k, passed in pr.gates:
@@ -288,10 +297,34 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
     coding = tally.horizon_coding()  # the horizon terms need every run's horizon first (spec 04 section 1)
     for hr in heads.values():
         hr.rows = add_horizon(drop_features(hr.rows, tally.nodes), hr.runs, tally.run_horizon, coding)
+    add_prices(heads["cost"], {m: len(r) for m, r in model_runs.items()}, model_streams)
     return (heads, score_info, dict(dropped), dict(runs_by_source), {c: dict(n) for c, n in config_support.items()},
             dict(checks), dict(overlap), dict(labels), tally)
 
 
+def add_prices(hr: HeadRows, runs: dict[str, int], streams: dict[str, list[float]]) -> None:
+    """The price offset (spec 04 section 2): the fit's offsets from its runs and token mix under the current price
+    table, and each cost row with its model's `price:offset` term (`pricing.price_term`, as at prediction)."""
+    hr.prices = fit_offsets(runs, streams, design_rows._price_table())
+    offsets = hr.prices["models"]
+    if not offsets:
+        return
+    rows = []
+    for row in hr.rows:
+        model = next((n[len("model:"):] for n, _, _ in row if n.startswith("model:")), None)
+        term = price_term(offsets, model) if model else ()
+        rows.append(row + list(term) if term else row)
+    hr.rows = rows
+
+
+def price_spec(hr: HeadRows) -> list:
+    """The prior that holds `price:offset` at 1, on the cost head of a fit with offsets, --no-prior included."""
+    if not hr.prices.get("models"):
+        return []
+    return [prior_data.FactorSpec("cost", [(PRICE_NODE, None, 1.0)], 1.0, PRICE_PRIOR_SD ** 2,
+                                  f"{PRICE_NODE} held at 1, prior N(1, {PRICE_PRIOR_SD}^2)")]
+
+
 # ---------------------------------------------------------------- matrices and priors
 
 def build_matrix(rows: list[list[Term]], forest: Forest, extra_nodes: Iterable[tuple[str, str | None]] = ()):
@@ -362,9 +395,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 +553,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():
@@ -511,6 +564,8 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
             nodes = horizon_nodes(hr.rows)
             if nodes:  # the horizon priors, --no-prior included (spec 04 section 1)
                 head_specs += horizon_specs(name, hr.kind, nodes)
+            if name == "cost":  # the price offset (spec 04 section 2)
+                head_specs += price_spec(hr)
             fitted[name] = fit_head(hr, forest, head_specs, eb=eb)
         fit_id = new_fit_id(fits, now)
         partial = fits / f"{fit_id}.partial"
@@ -546,6 +601,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,13 +619,14 @@ 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,
             "design_version": DESIGN_VERSION,
             "features": {**tally.report, **({"error": features_error} if features_error else {})},
             "horizons": tally.horizon_report(),
+            "price_offsets": heads_rows["cost"].prices,
         }
         if full:
             meta["full"] = _full_check(fitted)

{loopmath-0.2.0 → loopmath-0.2.2}/src/loopmath/belief/forest.py

@@ -55,6 +55,7 @@ FIXED_SD: dict[str, tuple[float, float, float]] = {
     "round": (2.0, 2.0, 2.0),
     "control": (1.0, 1.0, 1.0),
     "horizon": (10.0, 10.0, 10.0),  # wide: the informative prior is a FactorSpec in fit() (spec 04 section 1)
+    "price": (10.0, 10.0, 10.0),  # wide: fit() holds `price:offset` at 1 by a FactorSpec (spec 04 section 2)
 }
 
 HYPER_SD = 0.7  # sd of the log-normal hyperprior on each phi, around the defaults above

{loopmath-0.2.0 → loopmath-0.2.2}/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.2/src/loopmath/belief/pricing.py

@@ -0,0 +1,142 @@
+"""The price offset on the cost head (spec 04 section 2, 0.2.2, lane 22C).
+
+A model's run cost moves with its list price. Every cost row of a model version `m` (not the tokens, gate,
+success or score rows) carries the fixed term `price:offset` with the value
+
+    o_m = s_m * log(P_m / R_m),   s_m = n0 / (n0 + n_m),
+
+and the node's coefficient is held at 1 by a tight prior, so the term is a fixed offset on the log cost scale,
+the same at fit and at prediction:
+
+- `P_m` is m's blended list price ($/Mtok, the current price table) under the token mix (the shares of input,
+  cache read, cache write and output tokens) of the cost rows of m's family in the fit.
+- `R_m` is the run-weighted geometric mean of the blended prices, under the same mix, of the family's models
+  with cost rows. A family with no cost rows anchors on its provider the same way (the provider's mix and
+  models). No anchor, or no price for m, gives no term.
+- `n_m` is m's runs with a cost row in the fit; `PRICE_OFFSET_RUNS` is n0: the price counts like n0 of the
+  model's own runs, and its share of the prediction shrinks as they accumulate.
+
+`fit_offsets` computes the offset of every model with cost rows and of every model in the price table once per
+fit; `meta.json` `price_offsets` stores them, and prediction and the workflow search read them from there.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping
+
+from .forest import canonical_model_id, model_path
+
+PRICE_NODE = "price:offset"
+PRICE_LEVEL = "price"
+# n0: the list price counts like this many of the model's own runs (as one benchmark result counts like
+# BENCHMARK_PRIOR_WEIGHT = 5 runs). A heuristic, to tune when stores have new versions with a few runs.
+PRICE_OFFSET_RUNS = 5.0
+PRICE_PRIOR_SD = 1e-3  # the coefficient's prior N(1, sd^2): a fixed offset, not a learned elasticity
+STREAMS = ("input", "cache_read", "cache_write", "output")  # price table rate keys, in the order of `streams`
+
+
+def mix_of(totals: Iterable[float]) -> tuple[float, ...] | None:
+    """Token shares per stream (STREAMS order), or None without tokens."""
+    t = [max(0.0, float(x)) for x in totals]
+    s = sum(t)
+    return tuple(x / s for x in t) if s > 0 else None
+
+
+def blended(rate: Mapping[str, float] | None, mix: tuple[float, ...] | None) -> float | None:
+    """$/Mtok under `mix`, or None when the model has no rate, no mix, or a blended price of 0 (free)."""
+    if rate is None or mix is None:
+        return None
+    p = sum(share * float(rate.get(stream) or 0.0) for share, stream in zip(mix, STREAMS))
+    return p if p > 0 else None
+
+
+def shrink(runs: float, n0: float = PRICE_OFFSET_RUNS) -> float:
+    return n0 / (n0 + max(0.0, float(runs)))
+
+
+def _add(acc: dict[str, list[float]], key: str, values: Iterable[float]) -> None:
+    cur = acc.setdefault(key, [0.0] * len(STREAMS))
+    for i, v in enumerate(values):
+        cur[i] += float(v)
+
+
+def fit_offsets(runs: Mapping[str, int], streams: Mapping[str, Iterable[float]], table, *,
+                n0: float = PRICE_OFFSET_RUNS) -> dict:
+    """The fit's `price_offsets`: {n0, models: {model: offset}, detail, anchors}.
+
+    `runs`: model (canonical id) to its runs with a cost row; `streams`: model to its token totals over those
+    rows (STREAMS order); `table`: a price.PriceTable, or None (no offsets). Offsets of 0 are left out of
+    `models`; `detail` says for each priced model which anchor it used, or why it has none."""
+    out: dict = {"n0": n0, "models": {}, "detail": {}, "anchors": {}}
+    if table is None:
+        return out
+    fam_tok: dict[str, list[float]] = {}
+    prov_tok: dict[str, list[float]] = {}
+    fam_models: dict[str, dict[str, int]] = {}
+    prov_models: dict[str, dict[str, int]] = {}
+    for model, n in sorted(runs.items()):
+        if n <= 0:
+            continue
+        prov, fam, _ = model_path(model)
+        fam_models.setdefault(fam, {})[model] = int(n)
+        prov_models.setdefault(prov, {})[model] = int(n)
+        values = list(streams.get(model) or [0.0] * len(STREAMS))
+        _add(fam_tok, fam, values)
+        _add(prov_tok, prov, values)
+    candidates = set(runs) | {canonical_model_id(k) for k in table.rates}
+    anchors: dict[str, dict | None] = {}
+
+    def anchor(key: str, members: dict[str, int], tokens: list[float] | None) -> dict | None:
+        if key in anchors:
+            return anchors[key]
+        mix = mix_of(tokens or [])
+        priced = {m: (n, blended(table.rate(m), mix)) for m, n in members.items()}
+        priced = {m: (n, p) for m, (n, p) in priced.items() if p is not None}
+        found = None
+        if mix is not None and priced:
+            total = sum(n for n, _ in priced.values())
+            log_ref = sum(n * math.log(p) for n, p in priced.values()) / total
+            found = {"mix": mix, "log_ref": log_ref,
+                     "reference_usd_per_mtok": round(math.exp(log_ref), 6),
+                     "models": {m: n for m, (n, _) in sorted(priced.items())},
+                     "todo": sorted(m for m in priced if table.is_todo(m))}
+        anchors[key] = found
+        return found
+
+    for model in sorted(candidates):
+        prov, fam, _ = model_path(model)
+        a, key = None, None
+        if fam in fam_models:
+            key = f"family:{fam}"
+            a = anchor(key, fam_models[fam], fam_tok.get(fam))
+        if a is None and prov in prov_models and fam not in fam_models:
+            key = f"provider:{prov}"
+            a = anchor(key, prov_models[prov], prov_tok.get(prov))
+        if a is None:
+            out["detail"][model] = {"runs": int(runs.get(model, 0)), "note": "no anchor with runs and prices"}
+            continue
+        p = blended(table.rate(model), a["mix"])
+        if p is None:
+            out["detail"][model] = {"runs": int(runs.get(model, 0)), "anchor": key, "note": "no price"}
+            continue
+        n = int(runs.get(model, 0))
+        s = shrink(n, n0)
+        offset = s * (math.log(p) - a["log_ref"])
+        out["detail"][model] = {"runs": n, "anchor": key, "usd_per_mtok": round(p, 6), "shrink": round(s, 6),
+                                "log_ratio": round(math.log(p) - a["log_ref"], 6), "offset": round(offset, 6),
+                                **({"todo": True} if table.is_todo(model) else {})}
+        if offset != 0.0:
+            out["models"][model] = offset
+    out["anchors"] = {k: {**{kk: vv for kk, vv in v.items() if kk != "log_ref"}, "mix": [round(x, 6) for x in v["mix"]]}
+                      for k, v in sorted(anchors.items()) if v}
+    return out
+
+
+def price_term(offsets: Mapping[str, float] | None, model: str) -> tuple[tuple[str, None, float], ...]:
+    """The cost row's price term for `model` (a canonical id) under a fit's offsets: none for an offset of 0 or
+    a fit without offsets."""
+    if not offsets:
+        return ()
+    o = offsets.get(model)
+    return ((PRICE_NODE, None, float(o)),) if o else ()

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

@@ -67,7 +67,7 @@ MIN_SCORE_SWITCH = 5  # spec 04 section 2: g = p_reach once the score head has 5
 BASE_HEADS = {"cost": ("gaussian", "cost"), "tokens": ("gaussian", "cost"), "gate": ("logistic", "logit"),
               "success": ("logistic", "logit")}
 TASK_CHAIN = ("task", "subtype", "repo", "type")
-FIXED_LEVELS = ("fixed", "round", "control")
+FIXED_LEVELS = ("fixed", "round", "control", "price")
 SCORE_CLAMP = (0.005, 0.995)
 _CACHE_LIMIT = 200_000
 MEAN_NODES = 12  # Gauss-Hermite nodes over an unseen normal effect
@@ -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,23 @@ 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))
+        # spec 04 section 2: the fit's price offset per model (log scale); none in fits before 0.2.2
+        self.price_offsets: dict[str, float] = dict((self.meta.get("price_offsets") or {}).get("models") or {})
         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 +405,23 @@ 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,
+                                             prices=self.price_offsets)
         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 +808,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.2/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.2/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"))