loopmath 0.2.7__tar.gz → 0.2.8__tar.gz

{loopmath-0.2.7/src/loopmath.egg-info → loopmath-0.2.8}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.2.7"
+version = "0.2.8"
 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.7 → loopmath-0.2.8}/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.7"
+__version__ = "0.2.8"

{loopmath-0.2.7 → loopmath-0.2.8}/src/loopmath/belief/compose.py

@@ -18,6 +18,13 @@ simulated per draw (run noise and gate outcomes), and the interval is its 10th a
 percentiles. Rounds, success and `ell` are parameter-draw quantities. Without a generator,
 `compose` computes the expectations only (the mean path in state.py).
 
+Tokens (0.2.8): one execution's dollars are `U = exp(eta_u + sigma_u z1)` and its price per token
+`R = exp(eta_r + sigma_r z2)`, from the rate head; its tokens are `T = U / max(R, f)`, with `f` the model's
+cache-read rate (its floor, none for a model without one). So `T f <= U` in every draw, and every shown pair of
+dollars and tokens clears the floor: per draw, in the mean, at every percentile and summed over pieces. The two
+normals are drawn in 0.2.7's order (dollars, then the second one), so the simulated dollars and the gates after
+them are 0.2.7's. The expected tokens are `E[U] E[1 / max(R, f)]` (`inv_rate_mean`).
+
 Per piece, `PieceDraws.exp_*` is the piece's expected full-run contribution, summed over
 the rounds it runs, so pieces add up to the run. `cost_per_round()` gives the expected cost of
 one execution: the per-execution prediction when the piece's cost does not depend on the round
@@ -28,8 +35,11 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 
+import math
+from collections.abc import Mapping
+
 import numpy as np
-from scipy.special import expit
+from scipy.special import expit, log_ndtr
 
 from .design import Structure
 
@@ -64,12 +74,33 @@ class RunDraws:
     reach: dict[tuple[str, int], np.ndarray] = field(default_factory=dict)  # (piece, k) -> P(piece runs in round k)
 
 
-def compose(st: Structure, cost_eta: dict, tokens_eta: dict, gate_eta: dict, *, sigma_usd: float,
-            sigma_tokens: float, rng: np.random.Generator | None) -> RunDraws:
-    """Compose one configuration. `*_eta[(piece, k)]` and `gate_eta[(gate index, k)]` are draw arrays.
-    With `rng` None nothing is simulated: the `sim_*` arrays stay zero."""
+def inv_rate_mean(m, v, floor: float | None) -> np.ndarray:
+    """`E[1 / max(R, f)]` for `log R ~ N(m, v)` and the floor `f` ($ per token; None or 0: no floor), per entry
+    of `m`. With `l = log f`: `exp(-m + v/2) Phi((m - l)/sqrt(v) - sqrt(v)) + exp(-l) Phi((l - m)/sqrt(v))`,
+    each term in logs (`log Phi`), so a far tail never multiplies an overflow by 0. With `v = 0` the rate is
+    certain: `1 / max(exp(m), f)`."""
+    m = np.asarray(m, float)
+    v = np.broadcast_to(np.asarray(v, float), m.shape)
+    if not floor or floor <= 0:
+        return np.exp(-m + 0.5 * v)
+    lf = math.log(floor)
+    certain = v <= 0
+    sd = np.sqrt(np.where(certain, 1.0, v))
+    spread = np.exp(-m + 0.5 * v + log_ndtr((m - lf) / sd - sd)) + np.exp(log_ndtr((lf - m) / sd) - lf)
+    return np.where(certain, np.exp(-np.maximum(m, lf)), spread)
+
+
+def compose(st: Structure, cost_eta: dict, rate_eta: dict, gate_eta: dict, *, sigma_usd: float,
+            sigma_rate: float, floors: Mapping[str, float] | None = None, rate_var: Mapping | None = None,
+            rng: np.random.Generator | None) -> RunDraws:
+    """Compose one configuration. `cost_eta[(piece, k)]`, `rate_eta[(piece, k)]` and `gate_eta[(gate index, k)]`
+    are draw arrays; `floors[piece]` is the piece model's floor in $ per token (absent or 0: none). The expected
+    tokens take `log R ~ N(rate_eta, rate_var[(piece, k)])`, `sigma_rate ** 2` when `rate_var` is None (the mean
+    path passes the rate rows' known parts and adds their unseen variance there). With `rng` None nothing is
+    simulated: the `sim_*` arrays stay zero."""
     n = len(next(iter(cost_eta.values())))
-    half_u, half_t = 0.5 * sigma_usd ** 2, 0.5 * sigma_tokens ** 2
+    half_u, var_r = 0.5 * sigma_usd ** 2, sigma_rate ** 2
+    floors = floors or {}
     exp_u, exp_t = np.zeros(n), np.zeros(n)
     sim_u, sim_t = np.zeros(n), np.zeros(n)
     rounds = np.ones(n)
@@ -79,7 +110,7 @@ def compose(st: Structure, cost_eta: dict, tokens_eta: dict, gate_eta: dict, *,
         pieces[p] = PieceDraws(np.zeros(n), np.zeros(n), np.zeros(n), np.zeros(n), np.ones(n), sim_runs=np.zeros(n))
         if st.piece_loop.get(p) is not None:
             pieces[p].round_free = all(
-                np.array_equal(cost_eta[(p, k)], cost_eta[(p, 1)]) and np.array_equal(tokens_eta[(p, k)], tokens_eta[(p, 1)])
+                np.array_equal(cost_eta[(p, k)], cost_eta[(p, 1)]) and np.array_equal(rate_eta[(p, k)], rate_eta[(p, 1)])
                 for k in range(2, st.k_max + 1))
     gate_after = {g.after: gi for gi, g in enumerate(st.gates)}
     for piece, gi in gate_after.items():
@@ -88,17 +119,20 @@ def compose(st: Structure, cost_eta: dict, tokens_eta: dict, gate_eta: dict, *,
 
     def run_piece(piece: str, k: int, weight: np.ndarray, alive: np.ndarray):
         w = st.widths[piece]
-        eu, et = cost_eta[(piece, k)], tokens_eta[(piece, k)]
+        eu, er = cost_eta[(piece, k)], rate_eta[(piece, k)]
+        f = float(floors.get(piece) or 0.0)
         cu = w * np.exp(eu + half_u)
-        ct = w * np.exp(et + half_t)
+        ct = cu * inv_rate_mean(er, var_r if rate_var is None else rate_var[(piece, k)], f)
         pd = pieces[piece]
         pd.exp_usd += weight * cu
         pd.exp_tokens += weight * ct
         su = np.zeros(n)
         stt = np.zeros(n)
         for _ in range(w if rng is not None else 0):
-            su += np.exp(eu + sigma_usd * rng.standard_normal(n))
-            stt += np.exp(et + sigma_tokens * rng.standard_normal(n))
+            u = np.exp(eu + sigma_usd * rng.standard_normal(n))
+            r = np.exp(er + sigma_rate * rng.standard_normal(n))
+            su += u
+            stt += u / (np.maximum(r, f) if f > 0 else r)
         pd.sim_usd += alive * su
         pd.sim_tokens += alive * stt
         pd.sim_runs += alive

{loopmath-0.2.7 → loopmath-0.2.8}/src/loopmath/belief/design.py

@@ -30,8 +30,12 @@ from .pricing import price_term
 Term = tuple[str, "str | None", float]
 
 # Node names of this design (spec 04 section 4). 2 (loopmath 0.2): shape keys, psrc nodes and role groups.
-# 3 (0.2): `horizon:log2h` is relative to the fit's reference horizon. A fit of another version is not read.
-DESIGN_VERSION = 3
+# 3 (0.2): `horizon:log2h` is relative to the fit's reference horizon. 4 (0.2.8): a `rate` head on the price
+# per token replaces the tokens head. A fit of another version is not read.
+DESIGN_VERSION = 4
+# The version the seed key hashes (spec 04 section 3). It stays 3 from 0.2.8: the same data seeds the same
+# draws as in 0.2.7, so every number that is not a token count is 0.2.7's.
+SEED_VERSION = 3
 HEURISTIC_COST_WEIGHT = 0.7  # spec 04 section 2 and D27: allocated (heuristic) cost rows
 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)

{loopmath-0.2.7 → loopmath-0.2.8}/src/loopmath/belief/features.py

@@ -35,6 +35,8 @@ LN2 = math.log(2.0)
 # cost and tokens scale with an elasticity of 1 +- 0.5; logit and score heads start flat.
 HORIZON_PRIOR = {
     "cost": {"horizon:log2h": (LN2, 0.35), "horizon:timebox": (0.0, 1.5)},
+    # the price per token (0.2.8): a longer horizon buys more tokens, not dearer ones
+    "rate": {"horizon:log2h": (0.0, 0.35), "horizon:timebox": (0.0, 1.5)},
     "logit": {"horizon:log2h": (0.0, 0.25), "horizon:timebox": (0.0, 1.0)},
     "score": {"horizon:log2h": (0.0, 0.25), "horizon:timebox": (0.0, 1.0)},
 }

{loopmath-0.2.7 → loopmath-0.2.8}/src/loopmath/belief/fit.py

@@ -31,12 +31,12 @@ 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 .design import (DESIGN_VERSION, SEED_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 .pricing import PRICE_NODE, PRICE_PRIOR_SD, STREAMS, fit_offsets, price_term, rate_floors
 from .gaussian import N_DRAWS, Factors, GaussianHead, HeadFit, LogisticHead, Prior
 from .state import SCORE_CLAMP, inverse_transform, transform  # noqa: F401  (re-exported)
 
@@ -44,8 +44,12 @@ FIT_LOCK = ".fit.lock"
 KEEP_FITS = 5  # The newest fits kept, besides the ones a receipt or stored recommendation names
 TASK_LEVELS = ("org", "type", "repo", "subtype", "task")
 MIN_SCORE_RUNS = 3  # spec 04 section 2: a score head needs at least 3 measured runs
-HEAD_KIND = {"cost": ("gaussian", "cost"), "tokens": ("gaussian", "cost"),
+# `tokens` (log tokens) is 0.2.7's head: from 0.2.8 its rows are built for the seed key and the node index
+# only, never fitted. `rate` (log usd - log tokens, the price per token) is fitted in its place (spec 04 section 2).
+HEAD_KIND = {"cost": ("gaussian", "cost"), "tokens": ("gaussian", "cost"), "rate": ("gaussian", "cost"),
              "gate": ("logistic", "logit"), "success": ("logistic", "logit")}
+KEY_ONLY = ("tokens",)  # heads whose rows the seed key and the node index read, and no fit
+NOT_KEYED = ("rate",)  # heads the seed key leaves out, so 0.2.8 seeds every draw as 0.2.7 did
 
 
 class FitBusy(RuntimeError):
@@ -273,6 +277,9 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
                     acc[i] += v
             if a.tokens:
                 heads["tokens"].add(terms, math.log(a.tokens), a.weight, pr.run_id, pr.source, ttype)
+            if a.usd and a.tokens:
+                heads["rate"].add(terms, math.log(a.usd) - math.log(a.tokens), a.weight, pr.run_id, pr.source,
+                                  ttype)
         for gi, k, passed in pr.gates:
             heads["gate"].add(gate_row(pr.task, pr.source, st, st.gates[gi], k, features), 1.0 if passed else 0.0,
                               1.0, pr.run_id, pr.source, ttype)
@@ -305,6 +312,8 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
     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)
+    heads["rate"].prices = heads["cost"].prices  # the price per token carries the same offset (spec 04 section 2)
+    _price_rows(heads["rate"])
     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)
 
@@ -313,7 +322,12 @@ def add_prices(hr: HeadRows, runs: dict[str, int], streams: dict[str, list[float
     """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"]
+    _price_rows(hr)
+
+
+def _price_rows(hr: HeadRows) -> None:
+    """Each row with its model's `price:offset` term under `hr.prices`."""
+    offsets = hr.prices.get("models")
     if not offsets:
         return
     rows = []
@@ -325,10 +339,11 @@ def add_prices(hr: HeadRows, runs: dict[str, int], streams: dict[str, list[float
 
 
 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."""
+    """The prior that holds `price:offset` at 1, on the cost and rate heads 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,
+    return [prior_data.FactorSpec(hr.name, [(PRICE_NODE, None, 1.0)], 1.0, PRICE_PRIOR_SD ** 2,
                                   f"{PRICE_NODE} held at 1, prior N(1, {PRICE_PRIOR_SD}^2)")]
 
 
@@ -417,18 +432,21 @@ def seed_for(fit_id: str, head: str) -> int:
 
 
 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
+    """The fit's `seed_key` (spec 04 section 3): the sha256 of the seed 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.
 
     A success row's weight is its q. With `outcome.q` configured, the key takes each row's q under the built-in
-    map (`HeadRows.seed_w`), so setting q redraws nothing: only the success head's posterior moves (0.2.7)."""
+    map (`HeadRows.seed_w`), so setting q redraws nothing: only the success head's posterior moves (0.2.7).
+
+    From 0.2.8 the key reads 0.2.7's heads: the tokens rows, which no head fits any more, and not the rate rows,
+    with the seed version 0.2.7 hashed as its design version. The same data seeds the same draws as in 0.2.7."""
     h = hashlib.sha256()
-    h.update(repr((DESIGN_VERSION, design_rows.TIMEBOX_EFFORT_COST, design_rows.TIMEBOX_LEVELS,
+    h.update(repr((SEED_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):
+    for name in sorted(n for n in heads_rows if n not in NOT_KEYED):
         hr = heads_rows[name]
         h.update(f"\n{name}:{len(hr.rows)}".encode())
         weights = hr.seed_w or hr.w
@@ -618,9 +636,12 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
                 continue
             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 += horizon_specs(name, "rate" if name == "rate" else hr.kind, nodes)
+            if name in ("cost", "rate"):  # the price offset (spec 04 section 2)
                 head_specs += price_spec(hr)
+            if name in KEY_ONLY:  # 0.2.7's tokens head: its nodes enter the index where they did, unfitted
+                build_matrix(hr.rows, forest, [(n, p) for spec in head_specs for n, p, _ in spec.terms])
+                continue
             fitted[name] = fit_head(hr, forest, head_specs, eb=eb)
         fit_id = new_fit_id(fits, now)
         partial = fits / f"{fit_id}.partial"
@@ -685,6 +706,8 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
             "features": {**tally.report, **({"error": features_error} if features_error else {})},
             "horizons": tally.horizon_report(),
             "price_offsets": heads_rows["cost"].prices,
+            # the cheapest rate of each priced model, $ per token: a draw's tokens never cost less (spec 04 section 3)
+            "rate_floors": rate_floors(design_rows._price_table()),
         }
         if full:
             meta["full"] = _full_check(fitted)

{loopmath-0.2.7 → loopmath-0.2.8}/src/loopmath/belief/lookahead.py

@@ -394,7 +394,7 @@ def _condition_head(head: HeadState, terms: Sequence[tuple], tau2: float) -> Hea
 def conditioned(state: FitState, task: Task, config: Configuration, rule: AcceptanceRule | None = None) -> FitState:
     heads = dict(state.heads)
     terms, n_obs = _explore_cost_obs(state, task, config)
-    for name in ("cost", "tokens"):
+    for name in ("cost", "rate"):
         heads[name] = _condition_head(state.heads[name], terms, state.heads[name].sigma ** 2 / n_obs)
     run_terms = state.task_terms(task) + list(state._plan(config)["run"])
     succ = state.heads["success"]

{loopmath-0.2.7 → loopmath-0.2.8}/src/loopmath/belief/pricing.py

@@ -1,7 +1,8 @@
-"""The price offset on the cost head (spec 04 section 2, 0.2.2).
+"""The price offset on the cost and rate heads (spec 04 section 2, 0.2.2), and the rate floors (0.2.8).
 
-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
+A model's run cost moves with its list price. Every cost row of a model version `m`, and from 0.2.8 every rate
+row (the price per token), carries the fixed term `price:offset` (not the gate, success or score rows), with
+the value
 
     o_m = s_m * log(P_m / R_m),   s_m = n0 / (n0 + n_m),
 
@@ -18,6 +19,10 @@ the same at fit and at prediction:
 
 `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.
+
+`rate_floors` gives each priced model's cache-read rate in $ per token, the cheapest rate any of its tokens
+bills at (in every row of the packaged table, no nonzero rate is lower). A draw's price per token is held at or
+above it, so its tokens never cost less than its dollars (spec 04 section 3). `meta.json` stores them too.
 """
 
 from __future__ import annotations
@@ -140,3 +145,17 @@ def price_term(offsets: Mapping[str, float] | None, model: str) -> tuple[tuple[s
         return ()
     o = offsets.get(model)
     return ((PRICE_NODE, None, float(o)),) if o else ()
+
+
+def rate_floors(table) -> dict[str, float]:
+    """Model (canonical id) to its cache-read rate in $ per token, for every model with a positive one; empty
+    without a table. Two table keys of one model keep the lower rate."""
+    out: dict[str, float] = {}
+    if table is None:
+        return out
+    for key, rate in table.rates.items():
+        floor = float(rate.get("cache_read") or 0.0) / 1e6
+        if floor > 0:
+            model = canonical_model_id(key)
+            out[model] = min(floor, out.get(model, floor))
+    return dict(sorted(out.items()))