vertiq 0.2.0__py3-none-any.whl

vertiq/__init__.py

@@ -0,0 +1,23 @@
+"""vertiq: decision models for customers, revenue and inventory, for any business vertical.
+
+Plain data in, plain data out. vertiq never imports a web framework, an ORM or any host product:
+a host (a loyalty app, a POS, an enterprise CRM) reads its own database into the data
+contract (vertiq.contract), calls these functions, and stores the models (plain dicts) wherever
+it likes.
+
+  learn        logistic and ridge models over named features, AUC, calibration, tests, FDR control
+  features     what is known about a customer (account) at a moment, from their events only
+  churn        the chance a customer returns within a window, shared across businesses and verticals
+  uplift       who a message or an offer actually brings back, learned from control groups
+  value        revenue per campaign vs control, bill size, referrers
+  affinity     choices: combos, cross-sell, next items, refill cycles
+  insights     patterns tested before they are shown
+  inventory    reorder, slow movers, new arrivals, margins
+  offers       spend-more offers sized per customer
+  trends       trends matched to what a business sells and a customer buys
+  research     web tactics, kept only with a source and a mechanism that can test them
+  dataset      checks, masking and exports for training a language model
+  experiments  comparing message variants against each other and a control group
+  verticals    per-vertical settings (windows, nouns, currency, tactics)
+"""
+__version__ = "0.2.0"

vertiq/actions.py

@@ -0,0 +1,104 @@
+"""Smart actions: the few things worth doing now, each ready to become a campaign draft (who, why,
+with which offer, and what it should bring in). A host turns an action into its own campaign.
+
+  winback        persuadable and needs-offer customers from targeting (goal winback)
+  second_visit   first-timers targeting says a message would bring back
+  slow_mover     a slow-moving item, offered only to the people who buy it or its category
+  new_arrival    something new, told to the people who buy that kind of thing
+  cross_sell     people who buy A but never B, when A and B go together
+  referral       loyal regulars, asked to bring a friend
+
+Every action carries a stable key (so "create this" finds the same action again), the audience ids,
+the goal, and either an expected extra revenue (when targeting has one) or the money at stake.
+"""
+from __future__ import annotations
+
+from . import inventory
+
+MIN_AUDIENCE = 5
+
+
+def _targeted(plan: dict | None, key: str, title: str, goal: str, why: str, only=None) -> dict | None:
+    if not plan or plan.get("status") != "ok":
+        return None
+    people = [p for p in plan["customers"] if p["send"] and (only is None or only(p))]
+    if len(people) < MIN_AUDIENCE:
+        return None
+    offer = plan.get("offer")
+    with_offer = [p["id"] for p in people if p["with_offer"]]
+    return {"key": key, "title": title.format(n=len(people)), "goal": goal, "why": why,
+            "audience_ids": [p["id"] for p in people], "audience_count": len(people),
+            "offer": offer["label"] if offer and with_offer else "", "with_offer_count": len(with_offer),
+            "expected_extra_revenue": round(sum(p["expected_value"] for p in people)), "source": plan.get("source")}
+
+
+def _fans(choices: dict, inv_view: dict | None, item: str) -> list[str]:
+    """Customers who bought `item`, or anything in its catalogue category."""
+    k = inventory.key(item)
+    cat = (inv_view or {}).get("category", {}).get(k, "")
+    out = []
+    for cid, bought in (choices.get("_bought") or {}).items():
+        keys = {inventory.key(i) for i in bought}
+        if k in keys or (cat and any((inv_view or {}).get("category", {}).get(x) == cat for x in keys)):
+            out.append(cid)
+    return out
+
+
+def suggest(*, winback_plan: dict | None = None, second_visit_plan: dict | None = None, choices: dict | None = None,
+            inv_report: dict | None = None, inv_view: dict | None = None, referrers: dict | None = None,
+            one_visit_ids: set | None = None, currency: str = "₹", limit: int = 6) -> list[dict]:
+    out = []
+    a = _targeted(winback_plan, "winback", "Win back {n} customers who would come back if asked", "winback",
+                  "Targeting learned from your control groups says a message brings these people back.")
+    if a:
+        out.append(a)
+    a = _targeted(second_visit_plan, "second_visit", "Bring {n} first-timers back for a second visit", "secondVisit",
+                  "A second visit is where most customers are won or lost.",
+                  only=(lambda p: p["id"] in one_visit_ids) if one_visit_ids is not None else None)
+    if a:
+        out.append(a)
+    ch = choices or {}
+    rep = inv_report or {}
+    for s in (rep.get("slow_movers") or [])[:2]:
+        who = _fans(ch, inv_view, s["name"])
+        if len(who) >= MIN_AUDIENCE:
+            out.append({"key": f"slow_mover:{inventory.key(s['name'])}", "goal": "custom",
+                        "title": f"Offer {s['name']} to {len(who)} people who buy it or its kind",
+                        "why": f"{currency}{s.get('tied_up', 0):,} is tied up in it and it's selling slowly.",
+                        "audience_ids": who, "audience_count": len(who), "offer": "", "item": s["name"],
+                        "money_at_stake": s.get("tied_up", 0)})
+    for n in (rep.get("new_arrivals") or [])[:1]:
+        who = [c for c in _fans(ch, inv_view, n["name"])
+               if inventory.key(n["name"]) not in {inventory.key(i) for i in ch.get("_bought", {}).get(c, {})}]
+        if len(who) >= MIN_AUDIENCE:
+            out.append({"key": f"new_arrival:{inventory.key(n['name'])}", "goal": "custom",
+                        "title": f"Tell {len(who)} people about the new {n['name']}",
+                        "why": "They buy this kind of thing and haven't tried it yet.",
+                        "audience_ids": who, "audience_count": len(who), "offer": "", "item": n["name"]})
+    for x in (ch.get("cross_sell") or [])[:1]:
+        if inventory.blocked(inv_view, x["to"]):
+            continue
+        who = [c for c, bought in (ch.get("_bought") or {}).items() if x["from"] in bought and x["to"] not in bought]
+        if len(who) >= MIN_AUDIENCE:
+            out.append({"key": f"cross_sell:{inventory.key(x['from'])}>{inventory.key(x['to'])}", "goal": "custom",
+                        "title": f"Suggest {x['to']} to {len(who)} people who buy {x['from']}",
+                        "why": f"{x['also_buy_pct']:g}% of {x['from']} buyers also buy {x['to']}.",
+                        "audience_ids": who, "audience_count": len(who), "offer": "", "item": x["to"]})
+    r = referrers or {}
+    if r.get("count", 0) >= MIN_AUDIENCE:
+        ids = [c["id"] for c in r["customers"]]
+        out.append({"key": "referral", "goal": "custom", "title": f"Ask {len(ids)} loyal regulars to bring a friend",
+                    "why": "They visit often, recently, and are likely to stay.", "audience_ids": ids,
+                    "audience_count": len(ids), "offer": ""})
+    out.sort(key=_rank)
+    return out[:limit]
+
+
+def _rank(a: dict) -> tuple:
+    """Actions with an expected extra revenue first (largest first), then stock actions by the money
+    tied up, then the rest: the two numbers measure different things, so they are never compared."""
+    if a.get("expected_extra_revenue") is not None:
+        return (0, -a["expected_extra_revenue"])
+    if a.get("money_at_stake"):
+        return (1, -a["money_at_stake"])
+    return (2, -a.get("audience_count", 0))

vertiq/affinity.py

@@ -0,0 +1,147 @@
+"""Customer choices from line items: what sells together (combos), what a customer would likely
+try next (cross-sell), and items people buy again on a cycle (refills).
+
+  combos       two items on the same bill far more often than chance (lift), for combo offers
+  cross_sell   people who buy A tend to buy B too; the people with A and never B are the audience
+  next_items   per customer: what they haven't tried that people like them buy
+  refills      items bought again on a steady cycle, and who is due now
+
+Lift = how many times more often two things go together than if choices were independent:
+1.0 is chance, 2.0 is twice as often. Only pairs seen at least MIN_PAIR times count, so a single
+big order never makes a pattern. Plain data in: [(customer id, bill id, when, item name)].
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta
+from itertools import combinations
+from statistics import median
+
+MIN_PAIR = 5
+MIN_BASKETS = 30
+MAX_ITEMS_PER_BILL = 30
+
+
+def clean_item(name) -> str:
+    """An item name as it should be compared: spaces collapsed, placeholders ("item") dropped."""
+    n = " ".join(str(name or "").split())[:60]
+    return "" if n.lower() in ("", "item") else n
+
+
+def analyse(lines, min_pair: int = MIN_PAIR) -> dict:
+    """Everything affinity knows from [(customer id, bill id, when, item name)]."""
+    bills: dict[str, set] = defaultdict(set)
+    owner: dict[str, str] = {}
+    bought: dict[str, dict[str, list]] = defaultdict(lambda: defaultdict(list))   # cid -> item -> [dates]
+    for cid, tid, at, item in lines:
+        bills[tid].add(item)
+        owner[tid] = cid
+        bought[cid][item].append(at)
+    n_bills = len(bills)
+    result = {"bills": n_bills, "customers": len(bought), "status": "ok", "combos": [], "cross_sell": [],
+              "refills": [], "top_items": [], "_lifts": {}, "_bought": {}, "_cycles": {}}
+    if n_bills < MIN_BASKETS:
+        result["status"] = "learning"
+        return result
+    item_bills: Counter = Counter()
+    pair_bills: Counter = Counter()
+    for items in bills.values():
+        items = sorted(items)[:MAX_ITEMS_PER_BILL]
+        item_bills.update(items)
+        pair_bills.update(combinations(items, 2))
+    n_cust = len(bought)
+    item_cust = Counter(i for items in bought.values() for i in items)
+    pair_cust: Counter = Counter()
+    for items in bought.values():
+        pair_cust.update(combinations(sorted(items)[:MAX_ITEMS_PER_BILL * 3], 2))
+    result["top_items"] = [{"item": i, "customers": c, "share": round(100 * c / n_cust, 1)}
+                           for i, c in item_cust.most_common(8)]
+    result["combos"] = _combos(pair_bills, item_bills, n_bills, min_pair)
+    lifts, cross = _cross_sell(pair_cust, item_cust, n_cust, bought, min_pair)
+    result["cross_sell"], result["_lifts"] = cross, lifts
+    result["_bought"] = {cid: {i: max(ds) for i, ds in items.items()} for cid, items in bought.items()}
+    result["refills"], result["_cycles"] = _refills(bought)
+    return result
+
+
+def _combos(pair_bills: Counter, item_bills: Counter, n: int, min_pair: int = 5) -> list[dict]:
+    out = []
+    for (a, b), together in pair_bills.items():
+        if together < min_pair:
+            continue
+        lift = together * n / (item_bills[a] * item_bills[b])
+        if lift < 1.3:
+            continue
+        out.append({"items": [a, b], "bills_together": together, "lift": round(lift, 2),
+                    "a_then_b": round(100 * together / item_bills[a], 1),
+                    "b_then_a": round(100 * together / item_bills[b], 1)})
+    out.sort(key=lambda c: (-c["lift"] * min(c["bills_together"], 50), c["items"]))
+    return out[:10]
+
+
+def _cross_sell(pair_cust: Counter, item_cust: Counter, n: int, bought: dict, min_pair: int = 5):
+    lifts: dict[str, dict[str, float]] = defaultdict(dict)
+    pairs = []
+    for (a, b), both in pair_cust.items():
+        if both < min_pair:
+            continue
+        lift = both * n / (item_cust[a] * item_cust[b])
+        if lift < 1.2:
+            continue
+        lifts[a][b] = lifts[b][a] = round(lift, 3)
+        for x, y in ((a, b), (b, a)):
+            pairs.append({"from": x, "to": y, "lift": round(lift, 2),
+                          "also_buy_pct": round(100 * both / item_cust[x], 1),
+                          "audience": item_cust[x] - both})
+    pairs.sort(key=lambda p: (-(p["lift"] * min(p["audience"], 100)), p["from"], p["to"]))
+    return {k: dict(v) for k, v in lifts.items()}, pairs[:10]
+
+
+def _refills(bought: dict):
+    """Items people buy again on a steady cycle: each repeat buyer's median gap, then the median
+    across buyers. Needs 5 repeat buyers. Returns (summary, {item: cycle days})."""
+    gaps_by_item: dict[str, list] = defaultdict(list)
+    for items in bought.values():
+        for item, dates in items.items():
+            days = sorted({d.date() for d in dates})
+            gaps = [(days[i] - days[i - 1]).days for i in range(1, len(days))]
+            if gaps:
+                gaps_by_item[item].append(median(gaps))
+    cycles = {i: float(median(g)) for i, g in gaps_by_item.items() if len(g) >= 5 and median(g) >= 3}
+    summary = sorted(({"item": i, "cycle_days": round(c), "repeat_buyers": len(gaps_by_item[i])}
+                      for i, c in cycles.items()), key=lambda r: -r["repeat_buyers"])
+    return summary[:10], cycles
+
+
+def next_items(a: dict, customer_id: str, limit: int = 3) -> list[dict]:
+    """What this customer hasn't tried, ranked by how strongly their own items point to it."""
+    mine = a["_bought"].get(customer_id) or {}
+    scores: dict[str, float] = {}
+    because: dict[str, str] = {}
+    for item in mine:
+        for other, lift in (a["_lifts"].get(item) or {}).items():
+            if other in mine:
+                continue
+            if lift > scores.get(other, 0):
+                scores[other], because[other] = lift, item
+    ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))[:limit]
+    return [{"item": i, "lift": round(s, 2), "because": because[i], "confident": s >= 1.5} for i, s in ranked]
+
+
+def due_refills(a: dict, customer_id: str, today: datetime, early: int = 3, late: int = 10) -> list[dict]:
+    """Items on a cycle this customer is due to buy again (from `early` days before to `late` after)."""
+    out = []
+    for item, last in (a["_bought"].get(customer_id) or {}).items():
+        cycle = a["_cycles"].get(item)
+        if not cycle:
+            continue
+        due = last + timedelta(days=cycle)
+        off = (today - due).days
+        if -early <= off <= late:
+            out.append({"item": item, "cycle_days": round(cycle), "days_from_due": off})
+    return sorted(out, key=lambda r: abs(r["days_from_due"]))
+
+
+def public(a: dict) -> dict:
+    """The analysis without its private lookup tables, for the API."""
+    return {k: v for k, v in a.items() if not k.startswith("_")}

vertiq/autotune.py

@@ -0,0 +1,123 @@
+"""A gated search over task settings and candidate features: try one change at a time, keep it only if
+it improves the validation score, and let the evaluation gate judge the final configuration.
+
+Every trial is scored on validation splits carved from the training entities only (entities the gate
+holds out are removed before the search starts), so the gate's held-out score stays unbiased. The final
+configuration is trained by the normal task and must beat the baseline rule and the untuned
+configuration on the held-out entities, at the usual confidence; otherwise the untuned one is kept.
+
+  result = autotune.search(ds, target="breakdown", window_days=30,
+                           options={"learner": ["logistic", "boosted"], "survival": [False, True]},
+                           features={"skipped_pm_60": skipped_pm_60, "shift_pattern": shift_pattern})
+  result["task"], result["config"], result["trials"]
+
+This is the loop sometimes described as automated research (propose a change, measure, keep or revert),
+applied with a held-out gate so that repeated trials cannot overfit the score that decides promotion.
+"""
+from __future__ import annotations
+
+import math
+
+from . import harness, plugins
+from .contract import Dataset
+from .tasks import predict_event, predict_value
+
+PACK = "__autotune__"
+
+
+def _subset(ds: Dataset, keep: set[str]) -> Dataset:
+    return Dataset([e for e in ds.entities if e.id in keep], [e for e in ds.events if e.entity in keep])
+
+
+def _fold(key: str, folds: int) -> int:
+    return int(harness.hashlib.md5((key + "#tune").encode(), usedforsecurity=False).hexdigest(), 16) % folds
+
+
+def _run(ds: Dataset, kind: str, target: str, window_days: int, config: dict, chosen: list[str], features: dict,
+         pack: str | None, previous=None, confidence=harness.CONFIDENCE, holdout=None):
+    plugins.clear(PACK)
+    for fn in plugins.features_for(pack):
+        plugins.feature(PACK)(fn)
+    for name in chosen:
+        plugins.feature(PACK)(features[name])
+    kw = {k: v for k, v in config.items() if not (kind == "value" and k == "survival")}
+    task_fn = predict_event if kind == "event" else predict_value
+    try:
+        return task_fn(ds, target=target, window_days=window_days, pack=PACK, previous=previous,
+                       confidence=confidence, holdout=holdout, **kw)
+    finally:
+        plugins.clear(PACK)
+
+
+def _score(task, kind: str) -> float | None:
+    m = task.report().get("metrics") or {}
+    if kind == "event":
+        return m.get("auc")
+    return -m["mae"] if m.get("mae") is not None else None
+
+
+def search(ds: Dataset, *, target: str, window_days: int, kind: str = "event", pack: str | None = None,
+           base: dict | None = None, options: dict | None = None, features: dict | None = None,
+           folds: int = 5, min_step: float = 0.003, agree: int | None = None, rounds: int = 2) -> dict:
+    """Greedy search from `base` (task keyword arguments, e.g. {"learner": "logistic"}) over `options`
+    ({argument: [values]}) and candidate plugin `features` ({name: fn(entity, before, cut)}), plus the
+    features already registered under `pack`. The training entities are split into `folds` folds, and
+    each fold in turn is the validation set. A change is kept when the mean validation score rises by at
+    least `min_step` and the score rises in at least `agree` folds (default: all but one), so a gain
+    that comes from one lucky fold is not kept (AUC for event tasks; minus the mean absolute error for
+    value tasks). Returns {"task" (the tuned task if the gate
+    promoted it over the untuned one, else the untuned task), "tuned_promoted", "tuned", "untuned",
+    "config", "features", "validation_score", "trials" (every change tried, with its score)}."""
+    base = dict(base or {"learner": "logistic" if kind == "event" else "linear"})
+    options, features = options or {}, features or {}
+    agree = folds - 1 if agree is None else agree
+    train = _subset(ds, {e.id for e in ds.entities if not harness.held_out(e.id)})
+
+    def evaluate(config, chosen):
+        scores = [_score(_run(train, kind, target, window_days, config, chosen, features, pack, confidence=None,
+                              holdout=lambda key, k=k: _fold(key, folds) == k), kind) for k in range(folds)]
+        return None if any(x is None for x in scores) else scores
+
+    def mean(scores):
+        return sum(scores) / len(scores) if scores else -math.inf
+
+    config, chosen = dict(base), []
+    best_folds = evaluate(config, chosen)
+    best = mean(best_folds)
+    trials = [{"change": "start", "score": _r(best), "kept": True}]
+    for _round in range(rounds):
+        improved = False
+        moves = [(k, v) for k, vals in options.items() for v in vals]
+        moves += [("+feature", n) for n in features] + [("-feature", n) for n in features]
+        for key, val in moves:
+            if key == "+feature" and val in chosen or key == "-feature" and val not in chosen:
+                continue
+            if key not in ("+feature", "-feature") and config.get(key) == val:
+                continue
+            cfg, ch = dict(config), list(chosen)
+            if key == "+feature":
+                ch.append(val)
+            elif key == "-feature":
+                ch.remove(val)
+            else:
+                cfg[key] = val
+            f = evaluate(cfg, ch)
+            s = mean(f)
+            wins = sum(a > b for a, b in zip(f, best_folds)) if f and best_folds else 0
+            keep = s >= best + min_step and wins >= agree
+            trials.append({"change": f"{key} {val}" if key.endswith("feature") else f"{key}={val}",
+                           "score": _r(s), "folds_improved": f"{wins}/{folds}", "kept": keep})
+            if keep:
+                config, chosen, best, best_folds, improved = cfg, ch, s, f, True
+        if not improved:
+            break
+    untuned = _run(ds, kind, target, window_days, base, [], features, pack)
+    final = (_run(ds, kind, target, window_days, config, chosen, features, pack, previous=untuned.model)
+             if (config, chosen) != (base, []) else untuned)
+    use = final if final is not untuned and final.status == "trained" else untuned
+    return {"task": use, "tuned_promoted": use is final and final is not untuned, "tuned": final, "untuned": untuned,
+            "config": config, "features": chosen, "validation_score": _r(best), "trials": trials}
+
+
+def _r(x):
+    return round(x, 4) if x not in (None, -math.inf) else None

vertiq/boost.py

@@ -0,0 +1,198 @@
+"""Gradient-boosted decision trees in pure Python: a learner for signals a linear model cannot express,
+such as thresholds and interactions ("risk rises only when maintenance was skipped *and* the asset is
+old"). Registered as "boosted" (classification, logistic loss) and "boosted_regression" (squared loss).
+
+Each tree is fitted to the gradient of the loss with second-order (Newton) leaf values, on quantile
+bins of each feature, with row subsampling. Explanations follow each tree's path: a feature's
+contribution is the change in the node value at every split on that feature (the Saabas method), so
+a score lists what raised and lowered it, as the linear models do.
+
+A model is a plain dict (`to_dict`), like every other Vertiq model.
+"""
+from __future__ import annotations
+
+import bisect
+import math
+import random
+
+from .learn import Linear, Logistic, logit, sigmoid
+
+MAX_BINS = 16
+
+
+class BoostedClassifier:
+    """Boosted trees on {feature name: value} rows, logistic loss. Output: a probability."""
+
+    loss = "logistic"
+
+    # defaults chosen on the benchmark scenarios: shallow trees with large leaves generalise better on the
+    # few-thousand-row datasets typical of one organisation's history than deeper ones
+    def __init__(self, names: list[str] | None = None, *, trees: int = 60, depth: int = 2, rate: float = 0.1,
+                 min_leaf: int = 40, l2: float = 1.0, subsample: float = 0.8, seed: int = 7):
+        self.names: list[str] = list(names or [])
+        self.trees_n, self.depth, self.rate, self.min_leaf, self.l2 = trees, depth, rate, min_leaf, l2
+        self.subsample, self.seed = subsample, seed
+        self.cuts: dict[str, list[float]] = {}
+        self.fill: dict[str, float] = {}
+        self.base: float = 0.0
+        self.trees: list[dict] = []
+        self.offsets: dict[str, float] = {}
+
+    # ---- fitting -------------------------------------------------------------------------------
+    def _start(self, y: list) -> float:
+        return logit(min(1 - 1e-3, max(1e-3, sum(y) / len(y))))
+
+    def _grad(self, raw: float, y: float) -> tuple[float, float]:
+        p = sigmoid(raw)
+        return p - y, max(p * (1 - p), 1e-6)
+
+    def _value(self, raw: float) -> float:
+        return sigmoid(raw)
+
+    def _bins(self, rows: list[dict]) -> list[list[int]]:
+        if not self.names:
+            self.names = sorted({k for r in rows for k in r})
+        cols = []
+        for k in self.names:
+            vals = sorted(float(r.get(k, 0.0)) for r in rows)
+            self.fill[k] = vals[len(vals) // 2]
+            uniq = sorted(set(vals))
+            if len(uniq) <= MAX_BINS:
+                cuts = uniq[:-1]
+            else:
+                cuts = sorted({vals[(i * len(vals)) // MAX_BINS] for i in range(1, MAX_BINS)})
+            self.cuts[k] = cuts
+            cols.append([bisect.bisect_left(cuts, float(r.get(k, self.fill[k]))) for r in rows])
+        return cols
+
+    def _tree(self, cols, idx, g, h, depth) -> dict:
+        G, H = sum(g[i] for i in idx), sum(h[i] for i in idx)
+        node = {"v": -G / (H + self.l2)}
+        if depth == self.depth or len(idx) < 2 * self.min_leaf:
+            return node
+        parent = G * G / (H + self.l2)
+        best = (1e-9, None, None)
+        for j, col in enumerate(cols):
+            nb = len(self.cuts[self.names[j]]) + 1
+            if nb < 2:
+                continue
+            gb, hb, cb = [0.0] * nb, [0.0] * nb, [0] * nb
+            for i in idx:
+                b = col[i]
+                gb[b] += g[i]
+                hb[b] += h[i]
+                cb[b] += 1
+            gl = hl = 0.0
+            cl = 0
+            for b in range(nb - 1):
+                gl, hl, cl = gl + gb[b], hl + hb[b], cl + cb[b]
+                cr = len(idx) - cl
+                if cl < self.min_leaf or cr < self.min_leaf:
+                    continue
+                gain = gl * gl / (hl + self.l2) + (G - gl) ** 2 / (H - hl + self.l2) - parent
+                if gain > best[0]:
+                    best = (gain, j, b)
+        _gain, j, b = best
+        if j is None:
+            return node
+        left = [i for i in idx if cols[j][i] <= b]
+        right = [i for i in idx if cols[j][i] > b]
+        node.update(f=self.names[j], t=self.cuts[self.names[j]][b], j=j, b=b,
+                    l=self._tree(cols, left, g, h, depth + 1), r=self._tree(cols, right, g, h, depth + 1))
+        return node
+
+    @staticmethod
+    def _walk_bins(node: dict, cols, i: int) -> float:
+        while "f" in node:
+            node = node["l"] if cols[node["j"]][i] <= node["b"] else node["r"]
+        return node["v"]
+
+    def fit(self, rows: list[dict], y: list, **_unused) -> "BoostedClassifier":
+        if len(rows) != len(y) or not rows:
+            raise ValueError("need matching, non-empty rows and labels")
+        cols = self._bins(rows)
+        n = len(rows)
+        self.base = self._start(y)
+        raw = [self.base] * n
+        rnd = random.Random(self.seed)
+        self.trees = []
+        for _ in range(self.trees_n):
+            gh = [self._grad(raw[i], y[i]) for i in range(n)]
+            g, h = [a for a, _ in gh], [b for _, b in gh]
+            idx = [i for i in range(n) if rnd.random() < self.subsample] or list(range(n))
+            tree = self._tree(cols, idx, g, h, 0)
+            self.trees.append(tree)
+            for i in range(n):
+                raw[i] += self.rate * self._walk_bins(tree, cols, i)
+        for t in self.trees:                     # binned indices are a training aid only
+            _strip(t)
+        return self
+
+    def fit_offsets(self, rows: list[dict], y: list, groups: list[str], *, prior: float = 200.0) -> None:
+        """A shift per group on the raw scale, shrunk toward 0 (as the linear models do)."""
+        Logistic.fit_offsets(self, rows, y, groups, prior=prior)
+
+    # ---- scoring -------------------------------------------------------------------------------
+    def _x(self, row: dict, k: str) -> float:
+        return float(row.get(k, self.fill.get(k, 0.0)))
+
+    def raw(self, row: dict) -> float:
+        z = self.base
+        for t in self.trees:
+            node = t
+            while "f" in node:
+                node = node["l"] if self._x(row, node["f"]) <= node["t"] else node["r"]
+            z += self.rate * node["v"]
+        return z
+
+    def predict(self, row: dict, group: str | None = None) -> float:
+        return self._value(self.raw(row) + (self.offsets.get(group, 0.0) if group else 0.0))
+
+    def contributions(self, row: dict) -> list[tuple[str, float]]:
+        """Each feature's push on the raw score for this row, largest first (signed)."""
+        c: dict[str, float] = {}
+        for t in self.trees:
+            node = t
+            while "f" in node:
+                nxt = node["l"] if self._x(row, node["f"]) <= node["t"] else node["r"]
+                c[node["f"]] = c.get(node["f"], 0.0) + self.rate * (nxt["v"] - node["v"])
+                node = nxt
+        return sorted(c.items(), key=lambda kv: -abs(kv[1]))
+
+    # ---- storage -------------------------------------------------------------------------------
+    def to_dict(self) -> dict:
+        return {"kind": self.loss, "names": self.names, "base": self.base, "rate": self.rate, "fill": self.fill,
+                "trees": self.trees, "offsets": self.offsets}
+
+    @classmethod
+    def from_dict(cls, d: dict):
+        m = cls(d.get("names") or [])
+        m.base, m.rate, m.fill = float(d["base"]), float(d["rate"]), dict(d.get("fill") or {})
+        m.trees, m.offsets = list(d["trees"]), dict(d.get("offsets") or {})
+        return m
+
+
+class BoostedRegressor(BoostedClassifier):
+    """Boosted trees with squared loss. Output: the raw value (e.g. the log of a bill)."""
+
+    loss = "squared"
+
+    def _start(self, y: list) -> float:
+        return sum(y) / len(y)
+
+    def _grad(self, raw: float, y: float) -> tuple[float, float]:
+        return raw - y, 1.0
+
+    def _value(self, raw: float) -> float:
+        return raw
+
+    def fit_offsets(self, rows, y, groups, *, prior: float = 200.0) -> None:
+        Linear.fit_offsets(self, rows, y, groups, prior=prior)
+
+
+def _strip(node: dict) -> None:
+    node.pop("j", None)
+    node.pop("b", None)
+    if "l" in node:
+        _strip(node["l"])
+        _strip(node["r"])